From 2986230aca8d4a6152b0695987723ee62a4d041f Mon Sep 17 00:00:00 2001
From: yipengfei <pofey@me.com>
Date: Tue, 13 Oct 2026 11:04:55 +0800
Subject: [PATCH 001/132] feat(disc): play a DVD-Video VIDEO_TS folder over
 HTTP

A DiscDirectoryReader whose listing holds VIDEO_TS/ files is now read as
DVD-Video instead of Blu-ray. The title-set code of wrapDVD moves into
dvdTitleSet, which takes a listing and a way to read one whole file, so an
image and a folder share the VMGI filtering, durations, chapters, languages and
the selected title's VTS IFO. wrapDVDFolder concatenates the selected title
set's VOBs in part order with MultiFileConcatIOReader; that is the same run of
bytes as their sectors on a disc, so the cell spans and the VTS time map apply
unchanged. A listing without VIDEO_TS/ is read as Blu-ray, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  9 +++
 Sources/AetherEngine/Disc/DiscDirectory.swift | 49 ++++++++++++---
 Sources/AetherEngine/Disc/DiscReader.swift    | 49 ++++++++-------
 .../DVDCellTimelineTests.swift                |  2 +-
 Tests/AetherEngineTests/DVDFolderTests.swift  | 59 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 docs/formats.md                               |  2 +
 7 files changed, 143 insertions(+), 29 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DVDFolderTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 62041fd06..9c3d161e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,15 @@ the public-API contract.
 
 ## [Unreleased]
 
+### Added
+
+- **A DVD-Video ripped as a `VIDEO_TS` folder plays over HTTP, as a `BDMV` folder does.** A
+  `DiscDirectoryReader` (or `HTTPDiscDirectoryReader`) whose listing holds `VIDEO_TS/` files is now read
+  as DVD-Video: the title sets, VMGI filtering, durations, chapters and languages come from the same code
+  as an image's (`DiscReader.dvdTitleSet`, now shared), the selected title's VOBs play back to back in
+  part order, and the cell timeline and VTS time map apply as on an image, since the VOBs in order are
+  the same run of bytes as their sectors. A listing without `VIDEO_TS/` is read as Blu-ray, as before.
+
 ### Fixed
 
 - **The surround-downmix warning no longer fires on 5.1 inside a Dolby MAT carrier.** After an APAC
diff --git a/Sources/AetherEngine/Disc/DiscDirectory.swift b/Sources/AetherEngine/Disc/DiscDirectory.swift
index b42dfc86f..8015b2e91 100644
--- a/Sources/AetherEngine/Disc/DiscDirectory.swift
+++ b/Sources/AetherEngine/Disc/DiscDirectory.swift
@@ -1,15 +1,16 @@
 import Foundation
 
-/// A Blu-ray disc that a host serves as a FOLDER (the `BDMV` tree, one address per file) rather than
-/// as a single image. Hand one to `load(source: .custom(reader))`: the engine reads the playlists,
-/// selects the title and concatenates its clips the same way it does for a Blu-ray ISO, so titles,
-/// chapters, track languages and the multi-clip timeline (AE#105) all behave as they do there.
+/// A disc that a host serves as a FOLDER (the `BDMV` or `VIDEO_TS` tree, one address per file) rather
+/// than as a single image. Hand one to `load(source: .custom(reader))`: the engine selects the title and
+/// concatenates its clips or VOBs the same way it does for an ISO, so titles, chapters, track languages,
+/// the multi-clip and multi-cell timelines and the seek tables all behave as they do there. A listing
+/// with `VIDEO_TS/` in it is read as DVD-Video, anything else as Blu-ray.
 ///
 /// A folder carries no bytes of its own: `read` is never called on it. The engine recognizes the
 /// conformance before it reads anything and opens the files it needs through `openDiscFile(_:)`.
 public protocol DiscDirectoryReader: IOReader {
     /// Every file of the disc that can be read: its path relative to the disc root, with `/` as the
-    /// separator (`BDMV/STREAM/00001.m2ts`), and its size in bytes.
+    /// separator (`BDMV/STREAM/00001.m2ts`, `VIDEO_TS/VTS_01_1.VOB`), and its size in bytes.
     var discFiles: [(path: String, size: Int64)] { get }
 
     /// A new, independent reader over one file of `discFiles` (matched case-insensitively), or nil when
@@ -18,11 +19,11 @@ public protocol DiscDirectoryReader: IOReader {
 
     /// The `.mpls` file name of the title to play (`00800.mpls`), when the host already knows it. The
     /// engine then reads only that playlist and publishes it as the only title; nil reads every playlist
-    /// and selects the main title by the engine's own rules, as on an ISO.
+    /// and selects the main title by the engine's own rules, as on an ISO. Blu-ray only.
     var preferredPlaylist: String? { get }
 }
 
-/// A Blu-ray folder over HTTP: one URL per file, each read through its own range reader, so an origin
+/// A disc folder over HTTP: one URL per file, each read through its own range reader, so an origin
 /// serves the disc as plain files and never remuxes it.
 public final class HTTPDiscDirectoryReader: DiscDirectoryReader {
     public struct File: Sendable {
@@ -239,6 +240,40 @@ final class MultiFileConcatIOReader: IOReader, SourceTransferCounting, @unchecke
 }
 
 extension DiscReader {
+    /// A DVD-Video folder: the image path (`wrapDVD`) with files in place of sector ranges. A title set's
+    /// VOBs follow each other in part order, which is the same run of bytes as their sectors on a disc, so
+    /// the cell spans and the time map from its VTS IFO apply unchanged.
+    static func wrapDVDFolder(_ folder: DiscDirectoryReader, selectTitleID: Int?) -> DiscInfo? {
+        // Only VIDEO_TS's own files; a folder has no sectors, so each file is listed by name and size.
+        let entries = folder.discFiles.filter { $0.path.uppercased().hasPrefix("VIDEO_TS/") }
+        var byName: [String: (path: String, size: Int64)] = [:]
+        let files = entries.compactMap { entry -> DiscFile? in
+            let name = String(entry.path.split(separator: "/").last ?? "")
+            guard !name.isEmpty, entry.size > 0, entry.size <= Int64(Int.max) else { return nil }
+            byName[name.uppercased()] = entry
+            return DiscFile(name: name, startSector: 0, length: Int(entry.size))
+        }
+        let readFile: (DiscFile) -> [UInt8] = { file in
+            guard let entry = byName[file.name.uppercased()], let reader = folder.openDiscFile(entry.path) else { return [] }
+            defer { reader.close() }
+            return readAll(reader, [(offset: 0, length: entry.size)])
+        }
+        guard let set = dvdTitleSet(files: files, selectTitleID: selectTitleID, readFile: readFile) else {
+            EngineLog.emit("[disc] VIDEO_TS folder: no title VOBs among \(entries.count) files", category: .demux)
+            return nil
+        }
+        let segments = set.vobs.compactMap { vob in
+            byName[vob.name.uppercased()].map { MultiFileConcatIOReader.Segment(path: $0.path, size: $0.size) }
+        }
+        guard !segments.isEmpty else { return nil }
+        let (cellTimeline, timeMap) = set.selectedIFO.map(dvdCellTimeline) ?? ([], nil)
+        EngineLog.emit("[disc] DVD-Video folder recognized: \(set.titles.count) title(s), selected \(set.selectedIndex) "
+                       + "VOBs=\(segments.map(\.path)) bytes=\(segments.reduce(0) { $0 + $1.size })", category: .demux)
+        return DiscInfo(reader: MultiFileConcatIOReader(segments: segments, opener: { folder.openDiscFile($0) }),
+                        formatHint: "mpeg", titles: set.titles, selectedTitleIndex: set.selectedIndex,
+                        clipTimeline: cellTimeline, dvdTimeMap: timeMap)
+    }
+
     /// A Blu-ray folder: the image path (`wrapBluRay`) with files in place of UDF extents. The playlist scan
     /// and the clip assembly are the same bounded code, so a folder cannot make recognition do more than
     /// an image can (audit NET-103).
diff --git a/Sources/AetherEngine/Disc/DiscReader.swift b/Sources/AetherEngine/Disc/DiscReader.swift
index 5b0aa7de1..033aa440f 100644
--- a/Sources/AetherEngine/Disc/DiscReader.swift
+++ b/Sources/AetherEngine/Disc/DiscReader.swift
@@ -276,6 +276,9 @@ enum DiscReader {
         // A disc folder is a set of files, not one byte range, so it is recognized before the cache,
         // which rebuilds a reader from extents of a single image.
         if let folder = reader as? DiscDirectoryReader {
+            if folder.discFiles.contains(where: { $0.path.uppercased().hasPrefix("VIDEO_TS/") }) {
+                return wrapDVDFolder(folder, selectTitleID: selectTitleID)
+            }
             return wrapBluRayFolder(folder, selectTitleID: selectTitleID)
         }
         if let cacheKey, let cached = DiscRecognitionCache.lookup(key: cacheKey, selectTitleID: selectTitleID) {
@@ -343,6 +346,26 @@ enum DiscReader {
     /// listing holds no title VOBs.
     private static func wrapDVD(_ reader: IOReader, files: [DiscFile], sectorSize: Int, selectTitleID: Int?,
                                 cacheKey: String?) -> DiscInfo? {
+        let readFile: (DiscFile) -> [UInt8] = { file in
+            readAll(reader, [(offset: Int64(file.startSector * sectorSize), length: Int64(file.length))])
+        }
+        guard let set = dvdTitleSet(files: files, selectTitleID: selectTitleID, readFile: readFile) else { return nil }
+        let extents = set.vobs.map {
+            (offset: Int64($0.startSector * sectorSize), length: Int64($0.length))
+        }
+        let (cellTimeline, timeMap) = set.selectedIFO.map(dvdCellTimeline) ?? ([], nil)
+        storeRecognition(cacheKey: cacheKey, selectTitleID: selectTitleID,
+                         formatHint: "mpeg", titles: set.titles, selectedIndex: set.selectedIndex, extents: extents,
+                         clipTimeline: cellTimeline, dvdTimeMap: timeMap)
+        return DiscInfo(reader: ConcatIOReader(base: reader, extents: extents),
+                        formatHint: "mpeg", titles: set.titles, selectedTitleIndex: set.selectedIndex,
+                        clipTimeline: cellTimeline, dvdTimeMap: timeMap)
+    }
+
+    /// The titles of a `VIDEO_TS` listing and the selected one's VOBs (in part order) and VTS IFO, whatever
+    /// holds the bytes: `readFile` reads one whole file. nil when the listing holds no title VOBs.
+    static func dvdTitleSet(files: [DiscFile], selectTitleID: Int?, readFile: (DiscFile) -> [UInt8])
+        -> (titles: [DiscTitle], selectedIndex: Int, vobs: [DiscFile], selectedIFO: [UInt8]?)? {
         let groups = DVDTitleSelector.enumerateTitleVOBGroups(files)
         guard !groups.isEmpty else { return nil }
         // VIDEO_TS.IFO's TT_SRPT names which title sets are real titles; filter the VOB groups to those so
@@ -350,19 +373,12 @@ enum DiscReader {
         // falls back to the full VOB-grouped set, so a disc with an unreadable VMGI still plays multi-title.
         var orderedGroups = groups
         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 * sectorSize),
-                                             length: Int64(ifoFile.length))])
-            if let ifoTitles = DVDIFOParser.parseTitles(ifoBytes) {
-                let titleVTSNs = Set(ifoTitles.map(\.vtsn))
-                let filtered = groups.filter { titleVTSNs.contains($0.vtsn) }
-                if !filtered.isEmpty { orderedGroups = filtered }
-            }
+        if let ifoFile = filesByName["VIDEO_TS.IFO"], let ifoTitles = DVDIFOParser.parseTitles(readFile(ifoFile)) {
+            let titleVTSNs = Set(ifoTitles.map(\.vtsn))
+            let filtered = groups.filter { titleVTSNs.contains($0.vtsn) }
+            if !filtered.isEmpty { orderedGroups = filtered }
         }
         let selectedIndex = selectTitleID.flatMap { orderedGroups.indices.contains($0) ? $0 : nil } ?? 0
-        let extents = orderedGroups[selectedIndex].vobs.map {
-            (offset: Int64($0.startSector * sectorSize), length: Int64($0.length))
-        }
         // Whole-VTS titles. Each VTS_NN_0.IFO's main PGC gives the title duration and chapter starts; a disc
         // with an unreadable VTS IFO keeps duration 0 / no chapters but still plays. dvdVTSN keeps the
         // title -> title-set mapping.
@@ -376,8 +392,7 @@ enum DiscReader {
             let nn = g.vtsn < 10 ? "0\(g.vtsn)" : "\(g.vtsn)"
             let ifoName = "VTS_\(nn)_0.IFO"
             if let vtsIFO = filesByName[ifoName] {
-                let bytes = readAll(reader, [(offset: Int64(vtsIFO.startSector * sectorSize),
-                                             length: Int64(vtsIFO.length))])
+                let bytes = readFile(vtsIFO)
                 if idx == selectedIndex { selectedIFO = bytes }
                 if let detail = DVDIFOParser.parseTitleDetail(bytes) {
                     durationTicks = detail.durationTicks
@@ -392,13 +407,7 @@ enum DiscReader {
                              streamLanguages: streamLanguages,
                              dvdSubpictureStreamIDs: subpictureStreamIDs)
         }
-        let (cellTimeline, timeMap) = selectedIFO.map(dvdCellTimeline) ?? ([], nil)
-        storeRecognition(cacheKey: cacheKey, selectTitleID: selectTitleID,
-                         formatHint: "mpeg", titles: titles, selectedIndex: selectedIndex, extents: extents,
-                         clipTimeline: cellTimeline, dvdTimeMap: timeMap)
-        return DiscInfo(reader: ConcatIOReader(base: reader, extents: extents),
-                        formatHint: "mpeg", titles: titles, selectedTitleIndex: selectedIndex,
-                        clipTimeline: cellTimeline, dvdTimeMap: timeMap)
+        return (titles, selectedIndex, orderedGroups[selectedIndex].vobs, selectedIFO)
     }
 
     /// The selected DVD title's cells as AE#105 clip spans, and its time map.
diff --git a/Tests/AetherEngineTests/DVDCellTimelineTests.swift b/Tests/AetherEngineTests/DVDCellTimelineTests.swift
index aa99c71bd..a116fb2f6 100644
--- a/Tests/AetherEngineTests/DVDCellTimelineTests.swift
+++ b/Tests/AetherEngineTests/DVDCellTimelineTests.swift
@@ -27,7 +27,7 @@ struct DVDCellTimelineTests {
     }
 
     /// A PGC whose cell playback table holds `cells`, one program per cell.
-    private static func pgc(_ cells: [CellSpec]) -> [UInt8] {
+    static func pgc(_ cells: [CellSpec]) -> [UInt8] {
         var pgc = [UInt8](repeating: 0, count: 0xEC)
         pgc[2] = UInt8(cells.count)
         pgc[3] = UInt8(cells.count)
diff --git a/Tests/AetherEngineTests/DVDFolderTests.swift b/Tests/AetherEngineTests/DVDFolderTests.swift
new file mode 100644
index 000000000..2ccebea0c
--- /dev/null
+++ b/Tests/AetherEngineTests/DVDFolderTests.swift
@@ -0,0 +1,59 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// A DVD-Video served as a `VIDEO_TS` folder (`DiscDirectoryReader`): the same title sets, cell spans
+/// and time map as an image, over files instead of sectors.
+@Suite("DVD-Video folder sources")
+struct DVDFolderTests {
+    typealias Folder = BluRayFolderTests.MemoryFolder
+
+    static func bytes(_ seed: UInt8, _ count: Int) -> Data {
+        Data((0..<count).map { UInt8(truncatingIfNeeded: Int(seed) &* 41 &+ $0) })
+    }
+
+    /// Two title sets; the first one's content is two VOBs. `vts1IFO` stands in for VTS_01_0.IFO; the
+    /// default is unreadable, so the title sets come from the VOB names alone.
+    static func folder(vts1IFO: [UInt8]? = nil) -> Folder {
+        Folder([
+            ("VIDEO_TS/VIDEO_TS.IFO", bytes(1, 2048)),
+            ("VIDEO_TS/VIDEO_TS.VOB", bytes(2, 2048)),
+            ("VIDEO_TS/VTS_01_0.IFO", vts1IFO.map { Data($0) } ?? bytes(3, 2048)),
+            ("VIDEO_TS/VTS_01_0.VOB", bytes(4, 2048)),
+            ("VIDEO_TS/VTS_01_1.VOB", bytes(5, 7000)),
+            ("VIDEO_TS/VTS_01_2.VOB", bytes(6, 4000)),
+            ("VIDEO_TS/VTS_02_1.VOB", bytes(7, 3000)),
+        ])
+    }
+
+    @Test("the main title set's VOBs play back to back in part order, and the other title is selectable")
+    func titleSetsFromAFolder() throws {
+        let folder = Self.folder()
+        let info = try #require(try DiscReader.wrap(folder))
+        #expect(info.formatHint == "mpeg")
+        #expect(info.titles.map(\.dvdVTSN) == [1, 2])
+        #expect(BluRayFolderTests.readToEnd(info.reader) == Self.bytes(5, 7000) + Self.bytes(6, 4000))
+        #expect(info.reader.seek(offset: 0, whence: 65536) == 11000)
+        // The menu VOBs are never opened, and no Blu-ray path is tried.
+        #expect(!folder.openedPaths.contains("VIDEO_TS/VTS_01_0.VOB"))
+
+        let second = try #require(try DiscReader.wrap(Self.folder(), selectTitleID: 1))
+        #expect(BluRayFolderTests.readToEnd(second.reader) == Self.bytes(7, 3000))
+    }
+
+    @Test("the selected title's cells and time map apply to the folder's concatenated VOBs")
+    func cellTimelineFromAFolder() throws {
+        let ifo = DVDCellTimelineTests.vtsIFO(pgcs: [DVDCellTimelineTests.pgc(DVDCellTimelineTests.threeCells)],
+                                              timeMaps: [(unit: 4, sectors: [10, 20])])
+        let info = try #require(try DiscReader.wrap(Self.folder(vts1IFO: ifo)))
+        #expect(info.clipTimeline.map(\.concatByteStart) == [0, 1000 * 2048, 3000 * 2048])
+        #expect(info.dvdTimeMap?.byteOffsets == [10 * 2048, 20 * 2048])
+        #expect(info.titles.first?.durationTicks == UInt64(2100 * discTickRate))
+    }
+
+    @Test("a VIDEO_TS folder without title VOBs is not a disc")
+    func noTitleVOBs() throws {
+        let folder = Folder([("VIDEO_TS/VIDEO_TS.IFO", Self.bytes(1, 2048)), ("VIDEO_TS/VIDEO_TS.VOB", Self.bytes(2, 2048))])
+        #expect(try DiscReader.wrap(folder) == nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index ecf343240..8db9b8b72 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. |
-| `DiscDirectoryReader`, `HTTPDiscDirectoryReader` | A Blu-ray ripped as a `BDMV` folder, for `.custom(reader)`: `discFiles` lists the files (root-relative path and size), `openDiscFile(_:)` opens one, `preferredPlaylist` optionally names the title's `.mpls`. `HTTPDiscDirectoryReader(files:preferredPlaylist:httpHeaders:)` serves each `File` (path, size, url) from its own `Range` origin. See [Blu-ray folders](formats.md#disc-dvd--blu-ray-iso). |
+| `DiscDirectoryReader`, `HTTPDiscDirectoryReader` | A Blu-ray ripped as a `BDMV` folder, or a DVD-Video as a `VIDEO_TS` folder, for `.custom(reader)`: `discFiles` lists the files (root-relative path and size), `openDiscFile(_:)` opens one, `preferredPlaylist` optionally names the title's `.mpls`. `HTTPDiscDirectoryReader(files:preferredPlaylist:httpHeaders:)` serves each `File` (path, size, url) from its own `Range` origin. See [Blu-ray folders](formats.md#disc-dvd--blu-ray-iso). |
 | `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. |
diff --git a/docs/formats.md b/docs/formats.md
index 7e916c61b..10b0e973c 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -510,6 +510,8 @@ A remote `.iso` / `.img` / `.udf` needs an origin that honours HTTP `Range`, bec
 
 **Blu-ray folders.** A disc that was ripped as a `BDMV` folder rather than an image plays the same way through `MediaSource.custom` with a `DiscDirectoryReader`: the host lists the folder's files (path relative to the disc root, and size) and opens any one of them on request. `HTTPDiscDirectoryReader` is the ready-made one, with one URL per file, so an origin serves the disc as plain files over `Range` and never remuxes it. Recognition is the image path with files in place of UDF extents: the same bounded playlist scan and title selection, the selected title's `.m2ts` files concatenated in playlist order as one MPEG-TS, the same multi-clip timeline, chapters and STN track languages, and the same seek by the clips' EP maps when the folder carries `BDMV/CLIPINF`. A host that already knows the main playlist names it in `preferredPlaylist`, and only that playlist is read and published as the title. The concatenating reader opens a clip's file when the read reaches it and keeps at most three open. A controlled probe (`limits` or `cancellation`) does not recognize a folder yet; an uncontrolled `probe(source:)` and `load(source:)` do.
 
+**DVD-Video folders.** A listing that holds `VIDEO_TS/` files is read as DVD-Video instead, by the same title-set code as an image: the selected title set's VOBs are concatenated in part order, which is the same run of bytes as their sectors on a disc, so the cell timeline and the VTS time map apply unchanged. `preferredPlaylist` does not apply.
+
 **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 3bf8acc850411b9960db9fd48ff26df701658ca9 Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Tue, 13 Oct 2026 15:29:16 +0800
Subject: [PATCH 002/132] fix(cache): publish retained software VOD resident
 ranges

---
 CHANGELOG.md                                  |   6 +
 .../AetherEngine/AetherEngine+Loading.swift   |   7 +
 Sources/AetherEngine/AetherEngine.swift       |   3 +-
 .../Native/SoftwarePacketCoverage.swift       |  26 +++
 .../Native/SoftwarePacketDiskFIFO.swift       |   1 +
 .../Native/SoftwarePacketReadAhead.swift      |  89 ++++++++
 .../Native/SoftwarePlaybackHost.swift         |  62 ++++++
 .../Native/SoftwareVideoPacketCoverage.swift  |   6 +
 .../SoftwareResidentRangesTests.swift         | 204 ++++++++++++++++++
 docs/api.md                                   |  19 +-
 10 files changed, 420 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SoftwareResidentRangesTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 73d956cdd..d02c73bff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ the public-API contract.
 
 ### Fixed
 
+- **Software VOD exposes retained cache ranges to host timelines.** `residentRanges` now covers
+  compressed video packets together with the selected audio stream, including retained history,
+  gaps and disk eviction. Cached seeks keep the same spans; cold seeks and teardown clear them.
+  Sampling continues while paused and runs off the main actor, with stale seek/stop results
+  discarded. Hosts no longer need to infer a cache band's start from the moving playhead.
+
 - **A host with its own Objective-C and C++ links again (#752).** Since 7.34.0 LibTrueHD and LibDovi
   each brought a `rust_eh_personality`, and with the host's `__objc_personality_v0` and
   `__gxx_personality_v0` that made four personality routines, one more than compact unwind encodes
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index c6a71dc6b..f88276bbf 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1941,6 +1941,13 @@ extension AetherEngine {
         // #353: the settled picture size, wired next to the frame times because a host laying out an
         // overlay needs the rectangle as well as the clock, and both come off this renderer.
         mirrorSoftwareDisplaySize(from: host.$videoDisplaySize, storeIn: &softwareCancellables)
+        host.$residentRanges
+            .sink { [weak self, weak host] ranges in
+                guard let self, let host, self.softwareHost === host,
+                      self.loadGeneration == generation, !self.isLive else { return }
+                self.residentRanges = ranges
+            }
+            .store(in: &softwareCancellables)
         // SW-PiP: publish the bridge once the session owns its layer (the layer object is stable for
         // the session; the host attaches it to the view and, on PiP start, to the system window).
         softwarePiPSource = SoftwarePiPSource(layer: host.displayLayer, isLive: isLive, engine: self)
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 295e5c0e7..8c22f2a17 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -83,7 +83,8 @@ public final class AetherEngine: ObservableObject {
         didSet { recomputePlaybackPhase() }
     }
 
-    /// Where the loopback segment cache holds picture right now, on the same 0-based display axis as
+    /// Where the loopback segment cache or software VOD packet cache holds picture right now,
+    /// with selected audio coverage required for software A/V, on the same 0-based display axis as
     /// `currentTime`, `duration` and `seek(to:)`. An empty array is the nil-equivalent, and live
     /// sessions publish one always: their rewind depth is `clock.seekableLiveRange`, a different
     /// contract. Residency is not a promise that a seek inside a range will be instant; the player may
diff --git a/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift b/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift
index bd1e2998c..20408a1e1 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift
@@ -22,6 +22,32 @@ struct SoftwarePacketCoverage: Sendable {
     var rangeCount: Int { ranges.count }
     var isFull: Bool { ranges.count >= maximumRangeCount }
 
+    /// Immutable presentation spans for a background residency snapshot. Never round over a gap.
+    func rangesSeconds(timeBaseNumerator: Int32, timeBaseDenominator: Int32) -> [ClosedRange<Double>] {
+        guard timeBaseNumerator > 0, timeBaseDenominator > 0 else { return [] }
+        return ranges.compactMap { range in
+            guard Int64(exactly: Double(range.lowerBound)) == range.lowerBound,
+                  Int64(exactly: Double(range.upperBound)) == range.upperBound else { return nil }
+            let start = Double(range.lowerBound) * Double(timeBaseNumerator) / Double(timeBaseDenominator)
+            let end = Double(range.upperBound) * Double(timeBaseNumerator) / Double(timeBaseDenominator)
+            guard start.isFinite, end.isFinite, start < end else { return nil }
+            return start...end
+        }
+    }
+
+    /// Linear intersection of sorted, disjoint spans; selected audio is required even when muted.
+    static func intersection(_ video: [ClosedRange<Double>], _ audio: [ClosedRange<Double>]) -> [ClosedRange<Double>] {
+        var result: [ClosedRange<Double>] = []
+        var v = 0, a = 0
+        while v < video.count, a < audio.count {
+            let start = max(video[v].lowerBound, audio[a].lowerBound)
+            let end = min(video[v].upperBound, audio[a].upperBound)
+            if start < end { result.append(start...end) }
+            if video[v].upperBound < audio[a].upperBound { v += 1 } else { a += 1 }
+        }
+        return result
+    }
+
     /// 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.
     @discardableResult
diff --git a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
index 2126cbf78..c665727fe 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
@@ -57,6 +57,7 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
     let staleSweepResult: StaleSweepResult
     private let chunkTargetBytes: Int
     private let retainConsumed: Bool
+    var retainsConsumedPackets: Bool { retainConsumed }
     private let lock = NSLock()
     private var writer: FileHandle?
     private var reader: FileHandle?
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 3a7ee53d2..5d4e533cf 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -82,6 +82,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     }
     private var keyframes: [Keyframe] = []
     private let maximumKeyframes = 65_536
+    private var residency = SoftwarePacketResidency()
 
     /// Construct only off-main: creating the FIFO touches the temporary volume.
     init(video: Stream, audio: Stream?, byteBudget: Int, forwardSeconds: Double,
@@ -134,6 +135,35 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                         cacheSeekMisses: cacheSeekMisses)
     }
 
+    /// Called only by a background sampler. Copy bounded metadata under the short state lock;
+    /// timestamp conversion/intersection and keyframe selection happen after releasing it. No I/O.
+    var residentRanges: [ClosedRange<Double>] {
+        condition.lock()
+        guard !closed, !sourceRepositioning, !resetPending, failure == nil,
+              fifo.retainsConsumedPackets else { condition.unlock(); return [] }
+        let videoCoverage = self.videoCoverage
+        let presentationCoverage = self.presentationCoverage
+        let audioCoverage = self.audioCoverage
+        let keyframes = self.keyframes
+        let videoFloor = residency.videoFloor
+        let audioFloor = residency.audioFloor
+        condition.unlock()
+        let videoRanges = presentationCoverage?.rangesSeconds ?? videoCoverage.rangesSeconds(
+            timeBaseNumerator: video.numerator, timeBaseDenominator: video.denominator)
+        let ranges: [ClosedRange<Double>]
+        if let audio {
+            ranges = SoftwarePacketCoverage.intersection(videoRanges, audioCoverage.rangesSeconds(
+                timeBaseNumerator: audio.numerator, timeBaseDenominator: audio.denominator))
+        } else { ranges = videoRanges }
+        guard let keyframe = keyframes.lazy.map(\.seconds)
+            .filter({ $0 >= videoFloor }).min() else { return [] }
+        let floor = max(keyframe, audio == nil ? -.infinity : audioFloor)
+        return ranges.compactMap { range in
+            let start = max(range.lowerBound, floor)
+            return start < range.upperBound ? start...range.upperBound : nil
+        }
+    }
+
     /// Main-thread safe: metadata only. Decode/render backpressure still belongs to the old loop.
     func updatePlayhead(_ seconds: Double) {
         guard seconds.isFinite else { return }
@@ -405,6 +435,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         videoCoverage.reset(); audioCoverage.reset(); presentationCoverage?.reset()
         storedVideoSeconds = nil; consumedVideoSeconds = nil
         keyframes.removeAll(keepingCapacity: true)
+        residency = SoftwarePacketResidency()
     }
 
     /// Presentation seconds of a stored packet, or nil when this stream cannot express them.
@@ -420,6 +451,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         residentBytes = state.residentByteCount
         if let floor = state.oldestRetainedChunkID {
             keyframes.removeAll { $0.cursor.chunkID < floor }
+            residency.evict(before: floor)
         } else { keyframes.removeAll(keepingCapacity: true) }
     }
 
@@ -497,6 +529,12 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                     condition.lock()
                     if token == sourceEpoch, !closed, !sourceRepositioning {
                         copyDiskStateLocked(state)
+                        if packet.streamIndex == video.index || packet.streamIndex == audio?.index {
+                            let stream = packet.streamIndex == video.index ? video : audio!
+                            residency.insert(chunkID: cursor.chunkID, pts: packet.pts,
+                                duration: packet.duration, numerator: stream.numerator,
+                                denominator: stream.denominator, isVideo: packet.streamIndex == video.index)
+                        }
                         if packet.streamIndex == video.index {
                             if presentationCoverage != nil {
                                 if presentationCoverage?.isFull == true, let tick = playheadTick(video) {
@@ -640,3 +678,54 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
             + "qos=\(QoSClass.name(reportedProducerQoS))"
     }
 }
+
+/// Constant-size summaries per retained disk chunk, never per packet. The cumulative discarded
+/// high-water marks also cover reordered PTS: clipping at the first packet in the new chunk alone
+/// could otherwise claim an evicted B picture or audio packet still exists. Metadata pressure may
+/// conservatively shorten a displayed range; it never changes disk retention or seek policy.
+struct SoftwarePacketResidency: Sendable {
+    private struct Chunk: Sendable {
+        let id: UInt64
+        var videoEnd = -Double.infinity
+        var audioEnd = -Double.infinity
+    }
+    private var chunks: [Chunk] = []
+    private(set) var videoFloor = -Double.infinity
+    private(set) var audioFloor = -Double.infinity
+    private let maximumChunks: Int
+
+    init(maximumChunks: Int = 4096) { self.maximumChunks = max(1, maximumChunks) }
+
+    mutating func insert(chunkID: UInt64, pts: Int64, duration: Int64,
+                         numerator: Int32, denominator: Int32, isVideo: Bool) {
+        if chunks.last?.id != chunkID {
+            if chunks.count == maximumChunks { discardFirst(1) }
+            chunks.append(Chunk(id: chunkID))
+        }
+        // A successor-duration video with no packet duration still excludes the evicted PTS.
+        let (end, overflow) = pts.addingReportingOverflow(max(1, duration))
+        let seconds: Double
+        if pts == Int64.min || overflow || numerator <= 0 || denominator <= 0
+            || Int64(exactly: Double(end)) != end {
+            seconds = .infinity // unknown discarded timestamps cannot prove later residency
+        } else {
+            seconds = Double(end) * Double(numerator) / Double(denominator)
+        }
+        let index = chunks.count - 1
+        if isVideo { chunks[index].videoEnd = max(chunks[index].videoEnd, seconds) }
+        else { chunks[index].audioEnd = max(chunks[index].audioEnd, seconds) }
+    }
+
+    mutating func evict(before chunkID: UInt64) {
+        discardFirst(chunks.prefix { $0.id < chunkID }.count)
+    }
+
+    private mutating func discardFirst(_ count: Int) {
+        guard count > 0 else { return }
+        for chunk in chunks.prefix(count) {
+            videoFloor = max(videoFloor, chunk.videoEnd)
+            audioFloor = max(audioFloor, chunk.audioEnd)
+        }
+        chunks.removeFirst(count)
+    }
+}
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index a383b4d29..58199214d 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -138,6 +138,8 @@ final class SoftwarePlaybackHost {
     private var vodPacketReadAhead: SoftwarePacketReadAhead?
     /// #687: this host's entries in the process-wide retention ledger, released on `stop()`.
     private var retentionClaims: [RetentionClaims.Claim] = []
+    @Published private(set) var residentRanges: [ClosedRange<Double>] = []
+    private let residentRangePublication = SoftwareResidentRangePublication()
 
     /// 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.
@@ -1473,6 +1475,7 @@ final class SoftwarePlaybackHost {
         // reposition can tell on `seekQueue` whether a newer seek has already taken over.
         bumpSeekGeneration()
         let generation = seekGeneration
+        residentRangePublication.invalidate()
         didReachEnd = false
         didParkClockAtEnd = false
         didEmitParkedDiag = false
@@ -1538,6 +1541,7 @@ final class SoftwarePlaybackHost {
             switch preparation {
             case .success(let hit):
                 cacheHit = hit
+                if !hit { residentRanges = [] }
                 EngineLog.emit(
                     "[SWHost] packet cache seek generation=\(generation) "
                     + "result=\(hit ? "hit" : "miss") "
@@ -1553,6 +1557,7 @@ final class SoftwarePlaybackHost {
                 // a normal cache miss. Leave playback parked and publish an explicit failure.
                 seekInFlight = false
                 packetSource.close()
+                residentRanges = []
                 noteSeekSettled(generation)
                 EngineLog.emit("[SWHost] packet cache seek generation=\(generation) result=error",
                                category: .swPlayback)
@@ -1842,6 +1847,8 @@ final class SoftwarePlaybackHost {
         noteSeekSettled(seekGeneration)
         timeTimer?.cancel()
         timeTimer = nil
+        residentRangePublication.invalidate()
+        residentRanges = []
         vodPacketReadAhead?.close()
         vodPacketReadAhead = nil
         renderer.subtitleCompositor.reset()
@@ -3285,6 +3292,32 @@ final class SoftwarePlaybackHost {
 
     // MARK: - Time updates
 
+    nonisolated static func displayResidentRanges(_ ranges: [ClosedRange<Double>],
+                                                  sessionZeroSeconds: Double) -> [ClosedRange<Double>] {
+        guard sessionZeroSeconds.isFinite else { return [] }
+        let zero = max(0, sessionZeroSeconds)
+        return ranges.compactMap { range in
+            let start = max(0, range.lowerBound - zero), end = range.upperBound - zero
+            return start.isFinite && end.isFinite && start < end ? start...end : nil
+        }
+    }
+
+    /// Also runs while paused, independently of rendered-time events. At most one bounded
+    /// metadata calculation is pending. Cached seeks keep the last valid spans; a miss clears
+    /// them at the actual discard decision. Seek/stop invalidate any pre-operation result.
+    private func sampleResidentRanges() {
+        guard !isLive, !stopRequested, !seekInFlight,
+              let source = vodPacketReadAhead else { return }
+        let zero = clockSessionZero
+        residentRangePublication.sample {
+            Self.displayResidentRanges(source.residentRanges, sessionZeroSeconds: zero)
+        } publish: { [weak self] ranges in
+            guard let self, self.vodPacketReadAhead === source, !self.stopRequested,
+                  self.clockSessionZero == zero else { return }
+            if self.residentRanges != ranges { self.residentRanges = ranges }
+        }
+    }
+
     private func startTimeUpdates() {
         timeTimer = Timer.publish(every: 0.25, on: .main, in: .common)
             .autoconnect()
@@ -3292,6 +3325,7 @@ final class SoftwarePlaybackHost {
                 guard let self else { return }
                 // Independent of the clock below: a seek in flight must not defer the one check.
                 self.checkSurfaceVisibilityIfDue()
+                self.sampleResidentRanges()
                 guard let aOut = self.audioOutput else { return }
                 // #254: a reposition in flight holds `currentTime` at its target; the synchronizer is
                 // still on the pre-seek anchor and would drag the published position backwards.
@@ -3576,3 +3610,31 @@ extension SoftwarePlaybackHost: LiveRecordingHost {
         )
     }
 }
+
+/// A single background snapshot at a time. Invalidating at seek/stop prevents a delayed snapshot
+/// from restoring a discarded range or from clearing a newer request. Main never waits for work.
+@MainActor
+final class SoftwareResidentRangePublication {
+    private var task: Task<Void, Never>?
+    private var revision: UInt64 = 0
+
+    func invalidate() {
+        revision &+= 1
+        task?.cancel()
+        task = nil
+    }
+
+    @discardableResult
+    func sample(_ read: @escaping @Sendable () async -> [ClosedRange<Double>],
+                publish: @escaping @MainActor ([ClosedRange<Double>]) -> Void) -> Task<Void, Never>? {
+        guard task == nil else { return nil }
+        let token = revision
+        task = Task { [weak self] in
+            let ranges = await Task.detached(priority: .utility, operation: read).value
+            guard let self, !Task.isCancelled, self.revision == token else { return }
+            self.task = nil
+            publish(ranges)
+        }
+        return task
+    }
+}
diff --git a/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift b/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
index 136b77b1a..ae44a14e9 100644
--- a/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
+++ b/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
@@ -48,6 +48,12 @@ struct SoftwareVideoPacketCoverage: Sendable {
     var rangeCount: Int { coverage.rangeCount }
     var isFull: Bool { coverage.isFull }
 
+    var rangesSeconds: [ClosedRange<Double>] {
+        guard !isInvalidated else { return [] }
+        return coverage.rangesSeconds(timeBaseNumerator: timeBaseNumerator,
+                                      timeBaseDenominator: timeBaseDenominator)
+    }
+
     /// 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.
     @discardableResult
diff --git a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
new file mode 100644
index 000000000..62e0573aa
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
@@ -0,0 +1,204 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+@Suite("Software VOD resident ranges", .timeLimit(.minutes(2)))
+struct SoftwareResidentRangesTests {
+    private final class Input: @unchecked Sendable {
+        private let lock = NSLock()
+        private var packets: [SoftwareStoredPacket]
+        private var index = 0
+        init(_ packets: [SoftwareStoredPacket]) { self.packets = packets }
+        func next() -> SoftwareStoredPacket? {
+            lock.lock(); defer { lock.unlock() }
+            guard index < packets.count else { return nil }
+            defer { index += 1 }; return packets[index]
+        }
+    }
+    private func packet(_ pts: Int64, stream: Int32 = 0, duration: Int64 = 40,
+                        key: Bool = true) -> SoftwareStoredPacket {
+        .init(pts: pts, dts: pts, duration: duration, position: 0, streamIndex: stream,
+              flags: key ? 1 : 0, timeBaseNumerator: 1, timeBaseDenominator: 1000,
+              bytes: Data(repeating: 7, count: 100), sideData: [])
+    }
+    private func source(_ packets: [SoftwareStoredPacket], audio: Bool = false,
+                        reorder: Int? = nil, budget: Int = 1_000_000,
+                        chunkBytes: Int = 1024) throws -> SoftwarePacketReadAhead {
+        let input = Input(packets)
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: chunkBytes, retainConsumed: true)
+        let source = SoftwarePacketReadAhead(video: .init(index: 0, numerator: 1, denominator: 1000),
+            audio: audio ? .init(index: 1, numerator: 1, denominator: 1000) : nil,
+            byteBudget: budget, forwardSeconds: 3600, initialSourceClock: 0,
+            fifo: fifo, videoReorderDepth: reorder) { _ in input.next() }
+        source.start()
+        return source
+    }
+
+    @Test("Backward and forward cache hits preserve the same spans through begin, prepare and settle")
+    func cachedSeeks() async throws {
+        let source = try source((0..<100).map { packet(Int64($0) * 40) })
+        defer { source.close() }
+        try await waitFor { source.snapshot.sourceEnded }
+        #expect(source.residentRanges == [0...4])
+        for target in [3.0, 1, 2.5, 0.5] {
+            source.updatePlayhead(target)
+            let token = source.beginSeek(to: target)
+            #expect(source.residentRanges == [0...4])
+            #expect(try source.prepareSeek(token, to: target))
+            #expect(source.residentRanges == [0...4])
+            source.endSeek(token, sourceClock: target)
+            #expect(source.residentRanges == [0...4])
+        }
+        let miss = source.beginSeek(to: 8)
+        #expect(try !source.prepareSeek(miss, to: 8))
+        #expect(source.residentRanges.isEmpty)
+        source.close()
+        #expect(source.residentRanges.isEmpty)
+    }
+
+    @Test("Required audio intersects video, keeps holes, and missing selected audio proves nothing")
+    func audioIntersection() async throws {
+        let video = (0..<100).map { packet(Int64($0) * 40) }
+        let audio = [packet(500, stream: 1, duration: 500), packet(2000, stream: 1, duration: 1000)]
+        let source = try source(video + audio, audio: true)
+        defer { source.close() }
+        try await waitFor { source.snapshot.sourceEnded }
+        #expect(source.residentRanges == [0.5...1, 2...3])
+        let missing = try self.source(video, audio: true)
+        defer { missing.close() }
+        try await waitFor { missing.snapshot.sourceEnded }
+        #expect(missing.residentRanges.isEmpty)
+    }
+
+    @Test("Successor PTS retains reorder semantics, a discontinuity, and no invented final frame")
+    func reorderedVideo() async throws {
+        let pts: [Int64] = [0, 120, 40, 80, 160, 2000, 2120, 2040, 2080]
+        let source = try source(pts.map { packet($0, duration: 0) }, reorder: 4)
+        defer { source.close() }
+        try await waitFor { source.snapshot.sourceEnded }
+        #expect(source.residentRanges == [0...0.16, 2...2.12])
+        let invalid = try self.source(([Int64](stride(from: 0, to: 2000, by: 40)) + [0])
+            .map { packet($0) }, reorder: 4)
+        defer { invalid.close() }
+        try await waitFor { invalid.snapshot.sourceEnded }
+        #expect(invalid.residentRanges.isEmpty)
+    }
+
+    @Test("Real FIFO eviction shortens backward coverage without changing the read bytes")
+    func diskEviction() async throws {
+        let packets = (0..<100).map { packet(Int64($0) * 40) }
+        let source = try source(packets, budget: 1400, chunkBytes: 512)
+        defer { source.close() }
+        let retained = try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<[SoftwareStoredPacket], Error>) in
+                Thread.detachNewThread {
+                    do {
+                        var values: [SoftwareStoredPacket] = []
+                        while let packet = try source.read() {
+                            values.append(packet)
+                            source.updatePlayhead(Double(packet.pts) / 1000)
+                        }
+                        continuation.resume(returning: values)
+                    } catch { continuation.resume(throwing: error) }
+                }
+            }
+        } onCancel: { source.close() }
+        #expect(retained == packets)
+        try await waitFor { source.snapshot.sourceEnded }
+        let spans = source.residentRanges
+        #expect(!spans.isEmpty)
+        #expect((spans.first?.lowerBound ?? 0) > 3)
+        #expect(spans.last?.upperBound == 4)
+        let miss = source.beginSeek(to: 0.1)
+        #expect(try !source.prepareSeek(miss, to: 0.1))
+        #expect(source.residentRanges.isEmpty)
+    }
+
+    @Test("Evicted reordered timestamps and metadata pressure only shorten coverage")
+    func residencyWatermarks() {
+        var value = SoftwarePacketResidency(maximumChunks: 2)
+        value.insert(chunkID: 0, pts: 900, duration: 40, numerator: 1, denominator: 1000, isVideo: true)
+        value.insert(chunkID: 1, pts: 100, duration: 40, numerator: 1, denominator: 1000, isVideo: true)
+        value.insert(chunkID: 1, pts: 1100, duration: 40, numerator: 1, denominator: 1000, isVideo: false)
+        value.evict(before: 1)
+        #expect(value.videoFloor == 0.94)
+        #expect(value.audioFloor == -.infinity)
+        value.insert(chunkID: 2, pts: 1200, duration: 0, numerator: 1, denominator: 1000, isVideo: true)
+        value.insert(chunkID: 3, pts: 1300, duration: 0, numerator: 1, denominator: 1000, isVideo: true)
+        #expect(value.videoFloor == 0.94)
+        #expect(value.audioFloor == 1.14)
+        value.evict(before: 4)
+        #expect(value.videoFloor == 1.301)
+    }
+
+    @Test("Invalid discarded timestamps fail closed and reset begins a separate residency lifetime")
+    func invalidWatermark() {
+        var value = SoftwarePacketResidency()
+        value.insert(chunkID: 0, pts: .max, duration: 40, numerator: 1, denominator: 1000, isVideo: true)
+        value.evict(before: 1)
+        #expect(value.videoFloor == .infinity)
+        value = SoftwarePacketResidency()
+        #expect(value.videoFloor == -.infinity)
+    }
+
+    @Test("Source origin mapping preserves gaps, clips negatives and rejects unknown origins")
+    func displayMapping() {
+        let spans = [90.0...105, 110...120]
+        #expect(SoftwarePlaybackHost.displayResidentRanges(spans, sessionZeroSeconds: 100) == [0...5, 10...20])
+        #expect(SoftwarePlaybackHost.displayResidentRanges(spans, sessionZeroSeconds: .nan).isEmpty)
+        #expect(SoftwarePlaybackHost.displayResidentRanges(spans, sessionZeroSeconds: 200).isEmpty)
+    }
+
+    @Test("Large inexact timestamps do not manufacture display ranges")
+    func exactness() {
+        var coverage = SoftwarePacketCoverage()
+        coverage.insert(pts: 9_007_199_254_740_993, duration: 4)
+        #expect(coverage.rangesSeconds(timeBaseNumerator: 1, timeBaseDenominator: 1).isEmpty)
+    }
+}
+
+@MainActor
+@Suite("Software resident range publication", .timeLimit(.minutes(2)))
+struct SoftwareResidentRangePublicationTests {
+    private actor Gate {
+        private(set) var entered = false
+        private var waiter: CheckedContinuation<Void, Never>?
+        func wait() async {
+            await withCheckedContinuation { waiter = $0; entered = true }
+        }
+        func release() { waiter?.resume(); waiter = nil }
+    }
+
+    @Test("A delayed sampler leaves main responsive, coalesces ticks, and cannot publish after seek/stop")
+    func delayedSnapshots() async throws {
+        let publisher = SoftwareResidentRangePublication()
+        let gate = Gate()
+        var received: [[ClosedRange<Double>]] = []
+        let old = publisher.sample {
+            await gate.wait()
+            return [0...100]
+        } publish: { received.append($0) }
+        #expect(publisher.sample({ [0...999] }, publish: { received.append($0) }) == nil)
+        try await waitFor { await gate.entered }
+        // This main-actor turn can run while the background read is suspended. A new seek or stop
+        // invalidates it; a new session/seek can immediately publish without waiting for that read.
+        publisher.invalidate()
+        let replacement = publisher.sample({ [200...220] }, publish: { received.append($0) })
+        await replacement?.value
+        #expect(received == [[200...220]])
+        await gate.release()
+        await old?.value
+        #expect(received == [[200...220]])
+    }
+
+    @Test("Paused growth, eviction and a reset publish without a clock tick")
+    func pausedUpdates() async {
+        let publisher = SoftwareResidentRangePublication()
+        var received: [[ClosedRange<Double>]] = []
+        for spans: [ClosedRange<Double>] in [[10...30], [10...60], [20...60], [], [80...90]] {
+            let work = publisher.sample({ spans }, publish: { received.append($0) })
+            await work?.value
+        }
+        #expect(received == [[10...30], [10...60], [20...60], [], [80...90]])
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index ecf343240..7ecfb3ae4 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -585,10 +585,25 @@ Time lives on `player.clock`, a separate `ObservableObject`, so ~10 Hz ticks nev
 | `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 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. |
+| `$residentRanges` | where the loopback segment cache or software VOD packet 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 |
 
+For software VOD, `residentRanges` intersects video presentation coverage with the selected audio
+stream, even if muted; a video-only source does not require audio. H.264/HEVC use verified
+successor-PTS intervals, so the final picture with no known successor does not acquire an invented
+end. Ranges are clipped against retained keyframes and discarded packet timestamps; unknown or
+invalid coverage stays empty. Metadata limits can conservatively omit old spans rather than claim
+packets that no longer exist.
+
+The software sampler computes an immutable snapshot in the background and publishes on the main
+actor, including while paused. Cached seeks preserve retained spans; a cache miss clears them when
+the old store is discarded. Seek, replacement and teardown guards reject a late snapshot. Display
+these spans directly on the `currentTime` axis: `bufferedPosition` alone is a forward frontier and
+cannot establish a backward cache start. Live playback continues to expose its separate seekable
+window rather than VOD resident ranges.
+
+
 **`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
@@ -1128,7 +1143,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. |
 | `progressiveSegmentDelivery` | false | Serve each VOD loopback segment while it is being written: the muxer flushes a fragment about every half second and the loopback server sends each one as it lands, so AVPlayer shows and starts on a segment's first fragments instead of waiting for its cut. Changes nothing on a source fast enough to cut segments before AVPlayer asks; on a slow link it removes a whole segment's download from startup and from a seek outside the buffer. A segment the producer abandons (restart, failed cut) ends its connection without the final chunk, so AVPlayer asks for it again. VOD only; ignored on live, `nativeRemoteHLS` and the software path. |
-| `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`. |
+| `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`, and its retained spans (including history and gaps) are `$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, 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). |

From 761b031bcf406ada527d82fad251a25bb2415567 Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Tue, 13 Oct 2026 15:43:56 +0800
Subject: [PATCH 003/132] fix(cache): use upstream blocking executor for
 residency sampling

---
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 58199214d..82f584abd 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -3630,7 +3630,7 @@ final class SoftwareResidentRangePublication {
         guard task == nil else { return nil }
         let token = revision
         task = Task { [weak self] in
-            let ranges = await Task.detached(priority: .utility, operation: read).value
+            let ranges = await BlockingWork.detached(priority: .utility, operation: read).value
             guard let self, !Task.isCancelled, self.revision == token else { return }
             self.task = nil
             publish(ranges)

From 4a5eae0eefb750923355152f9326df33f5f94f08 Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Tue, 13 Oct 2026 17:08:55 +0800
Subject: [PATCH 004/132] test(cache): guard residency sampling executor

---
 .../SoftwareResidentRangesTests.swift         | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
index 62e0573aa..8cd47c854 100644
--- a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
+++ b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
@@ -160,6 +160,25 @@ struct SoftwareResidentRangesTests {
 @MainActor
 @Suite("Software resident range publication", .timeLimit(.minutes(2)))
 struct SoftwareResidentRangePublicationTests {
+    private nonisolated static func isMainThread() -> Bool {
+        Thread.isMainThread
+    }
+
+    @Test("Residency sampling leaves both main and the cooperative executor")
+    @available(visionOS 2, *)
+    func samplingExecutor() async {
+        let publisher = SoftwareResidentRangePublication()
+        var received: [ClosedRange<Double>] = []
+        let work = publisher.sample {
+            let label = String(cString: __dispatch_queue_get_label(nil))
+            #expect(!Self.isMainThread())
+            #expect(!label.contains("cooperative"), "residency read ran on \(label)")
+            return [1...2]
+        } publish: { received = $0 }
+        await work?.value
+        #expect(received == [1...2])
+    }
+
     private actor Gate {
         private(set) var entered = false
         private var waiter: CheckedContinuation<Void, Never>?

From 02e1f022473722e53fabc4f7e65a330eb8ab2754 Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Tue, 13 Oct 2026 17:56:40 +0800
Subject: [PATCH 005/132] fix(demux): repair variable-cadence H264 heads and
 hierarchical partial offsets

---
 CHANGELOG.md                                  |  6 ++
 .../test-h264-partial-composition-controls.sh | 14 ++++
 ...4PartialCompositionRuntimeStandalone.swift | 36 +++++++-
 .../H264PartialCompositionStandalone.swift    | 66 +++++++++++++++
 Scripts/tests/make-missing-head-fixture.py    | 77 +++++++++++++++++
 .../Video/H264CompositionOffsetRepair.swift   | 22 +++++
 .../Video/H264PartialCompositionRepair.swift  | 80 ++++++++++++++++--
 .../H264PartialCompositionRepairSession.swift | 83 ++++++++++++++++---
 .../H264CompositionOffsetRepairTests.swift    | 34 ++++++++
 docs/formats.md                               | 25 ++++--
 10 files changed, 412 insertions(+), 31 deletions(-)
 create mode 100644 Scripts/tests/make-missing-head-fixture.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 751e60c90..a118685f0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,12 @@ the public-API contract.
 
 ### Fixed
 
+- **H.264 MP4s with missing composition offsets keep display order across cadence changes and
+  hierarchical B pictures.** A corroborated missing-offset head with a changing decode cadence now
+  reuses the existing timestamp slots. Later zero-offset regions can prove a forward-coded anchor
+  farther ahead than the declared backward reorder delay, using a bounded complete-prefix check.
+  Original DTS, audio, payload and index remain unchanged; unsupported sequences still pass through.
+
 - **A host with its own Objective-C and C++ links again (#752).** Since 7.34.0 LibTrueHD and LibDovi
   each brought a `rust_eh_personality`, and with the host's `__objc_personality_v0` and
   `__gxx_personality_v0` that made four personality routines, one more than compact unwind encodes
diff --git a/Scripts/test-h264-partial-composition-controls.sh b/Scripts/test-h264-partial-composition-controls.sh
index 9e2c82177..4c9bdf6b0 100644
--- a/Scripts/test-h264-partial-composition-controls.sh
+++ b/Scripts/test-h264-partial-composition-controls.sh
@@ -32,3 +32,17 @@ ffmpeg -hide_banner -loglevel error -n \
 ruby "$TASK_ROOT/Scripts/tests/make-partial-ctts-fixture.rb" \
   "$TASK_TMP/healthy-scenecut.mp4" "$TASK_TMP/variable.mp4" tail 300 1200 1200
 bash "$TASK_ROOT/Scripts/test-h264-partial-composition-runtime.sh" "$TASK_TMP/variable.mp4" 0 12 0
+
+# Entire missing-offset head with a decode cadence change, plus its untouched healthy control.
+python3 "$TASK_ROOT/Scripts/tests/make-missing-head-fixture.py" "$TASK_TMP"
+bash "$TASK_ROOT/Scripts/test-h264-partial-composition-runtime.sh" "$TASK_TMP/missing-head.mp4" 0 1.5 0 20 40
+bash "$TASK_ROOT/Scripts/test-h264-partial-composition-runtime.sh" "$TASK_TMP/healthy-head.mp4" 0
+
+# Hierarchical B pictures: forward distance 3, declared backward depth 2. The healthy twin
+# supplies an exact PTS oracle for both a damaged tail and a damaged middle with recovery.
+python3 "$TASK_ROOT/Scripts/tests/make-missing-head-fixture.py" "$TASK_TMP" --partial-hierarchical
+AETHER_TIMESTAMP_HEALTHY_TWIN="$TASK_TMP/healthy-b3.mp4" \
+  bash "$TASK_ROOT/Scripts/test-h264-partial-composition-runtime.sh" "$TASK_TMP/tail-b3.mp4" 0 12 0 6 22
+AETHER_TIMESTAMP_HEALTHY_TWIN="$TASK_TMP/healthy-b3.mp4" \
+  bash "$TASK_ROOT/Scripts/test-h264-partial-composition-runtime.sh" "$TASK_TMP/middle-b3.mp4" 0 12 0 6 18 22
+bash "$TASK_ROOT/Scripts/test-h264-partial-composition-runtime.sh" "$TASK_TMP/healthy-b3.mp4" 0
diff --git a/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift b/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift
index c11ea29ed..bec0e4c3b 100644
--- a/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift
+++ b/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift
@@ -54,6 +54,7 @@ struct H264PartialCompositionRuntimeTests {
     enum Failure: Error { case open, decoder, demux, decode, session, boundedRead }
     static func main() throws {
         guard CommandLine.arguments.count >= 2 else { throw Failure.open }
+        EngineLog.handler = { FileHandle.standardError.write(Data(($0 + "\n").utf8)) }
         av_log_set_level(AV_LOG_QUIET)
         var format: UnsafeMutablePointer<AVFormatContext>?
         guard avformat_open_input(&format, CommandLine.arguments[1], nil, nil) >= 0, let format else { throw Failure.open }
@@ -62,6 +63,7 @@ struct H264PartialCompositionRuntimeTests {
         let index = av_find_best_stream(format, AVMEDIA_TYPE_VIDEO, -1, -1, nil, 0)
         guard index >= 0, let stream = format.pointee.streams[Int(index)],
               let par = stream.pointee.codecpar, par.pointee.codec_id == AV_CODEC_ID_H264 else { throw Failure.open }
+        let twinPTS = try ProcessInfo.processInfo.environment["AETHER_TIMESTAMP_HEALTHY_TWIN"].map(referenceTimes)
         let name = format.pointee.iformat.flatMap { $0.pointee.name }.map(String.init(cString:)) ?? ""
         let matroska = name.contains("matroska")
         guard !matroska else { throw Failure.session }
@@ -96,6 +98,9 @@ struct H264PartialCompositionRuntimeTests {
                     precondition(actual.duration == expected.duration && actual.flags == expected.flags)
                     precondition(actual.position == expected.position && actual.streamIndex == expected.streamIndex)
                     precondition(actual.dts == expected.dts, "partial repair must preserve the published decode/index axis")
+                    if let twinPTS {
+                        precondition(twinPTS[actual.dts] == actual.pts, "repaired video PTS must exactly match its healthy twin")
+                    }
                     try decode(fixed, packet: packet, into: &fixedPTS)
                 } else { precondition(actual == expected) }
                 delivered += 1
@@ -120,7 +125,8 @@ struct H264PartialCompositionRuntimeTests {
                     try decode(raw, packet: packet, into: &rawPTS)
                 }
                 if !session.ingest(packet) { try emit(packet) }
-                observedRepair = observedRepair || session.summary.contains("confirmed_partial_composition_offsets")
+                observedRepair = observedRepair || (session.summary.contains("confirmed_partial_composition_offsets") || session.summary.contains("confirmed_missing_composition_offsets"))
+
             }
             session.endOfStream()
             while let packet = session.dequeue() { try emit(packet) }
@@ -130,7 +136,7 @@ struct H264PartialCompositionRuntimeTests {
             let rawRegressions = zip(rawPTS, rawPTS.dropFirst()).filter { $1 <= $0 }.count
             let fixedRegressions = zip(fixedPTS, fixedPTS.dropFirst()).filter { $1 <= $0 }.count
             let diagnostic = session.summary
-            observedRepair = observedRepair || diagnostic.contains("confirmed_partial_composition_offsets")
+            observedRepair = observedRepair || (diagnostic.contains("confirmed_partial_composition_offsets") || diagnostic.contains("confirmed_missing_composition_offsets"))
             FileHandle.standardError.write(Data("MEASURE seek=\(position) raw=\(rawRegressions) fixed=\(fixedRegressions) offset=\(session.decodeTimestampOffset ?? 0) state=\(diagnostic) lead=\(0) shift=\(0)\n".utf8))
             precondition(rawPTS.count == fixedPTS.count && !fixedPTS.isEmpty)
             precondition(fixedRegressions == 0)
@@ -145,6 +151,29 @@ struct H264PartialCompositionRuntimeTests {
         }
     }
 
+    /// Optional generated healthy twin checks exact timestamps, beyond monotonic decoded output.
+    static func referenceTimes(_ path: String) throws -> [Int64: Int64] {
+        var input: UnsafeMutablePointer<AVFormatContext>?
+        guard avformat_open_input(&input, path, nil, nil) >= 0, let input else { throw Failure.open }
+        defer { var owned: UnsafeMutablePointer<AVFormatContext>? = input; avformat_close_input(&owned) }
+        guard avformat_find_stream_info(input, nil) >= 0 else { throw Failure.open }
+        let index = av_find_best_stream(input, AVMEDIA_TYPE_VIDEO, -1, -1, nil, 0)
+        guard index >= 0 else { throw Failure.open }
+        var result: [Int64: Int64] = [:]
+        while true {
+            guard let packet = trackedPacketAlloc() else { throw Failure.demux }
+            defer { av_packet_free_safe(packet) }
+            let status = av_read_frame(input, packet)
+            if status == -541478725 { break }
+            guard status >= 0 else { throw Failure.demux }
+            if packet.pointee.stream_index == index {
+                precondition(result.count < 8000 && result[packet.pointee.dts] == nil)
+                result[packet.pointee.dts] = packet.pointee.pts
+            }
+        }
+        return result
+    }
+
     static func lifecycleChecks(session: H264CompositionOffsetRepairSession,
         format: UnsafeMutablePointer<AVFormatContext>, stream: UnsafeMutablePointer<AVStream>, index: Int32,
         position: Double) throws {
@@ -172,7 +201,7 @@ struct H264PartialCompositionRuntimeTests {
             var confirmed = false
             for _ in 0..<4000 {
                 try read()
-                if session.summary.contains("confirmed_partial_composition_offsets") { confirmed = true; break }
+                if (session.summary.contains("confirmed_partial_composition_offsets") || session.summary.contains("confirmed_missing_composition_offsets")) { confirmed = true; break }
             }
             precondition(confirmed)
             guard let packet = trackedPacketAlloc() else { throw Failure.demux }
@@ -181,6 +210,7 @@ struct H264PartialCompositionRuntimeTests {
             packet.pointee.pts = malformed.pts
             if !session.ingest(packet) { av_packet_free_safe(packet) }
             while let packet = session.dequeue() { av_packet_free_safe(packet) }
+            precondition(session.summary.contains("partial_composition_sequence_unproven"))
             precondition(PacketBalanceTracker.alive == 0, "a refusal still owns every packet it took")
             // A refused sequence streams through the session rather than out of its queue, so
             // count both ways a packet can come back.
diff --git a/Scripts/tests/H264PartialCompositionStandalone.swift b/Scripts/tests/H264PartialCompositionStandalone.swift
index bb914f09f..f7088400c 100644
--- a/Scripts/tests/H264PartialCompositionStandalone.swift
+++ b/Scripts/tests/H264PartialCompositionStandalone.swift
@@ -32,7 +32,73 @@ struct H264PartialCompositionTests {
         return (times, deepest, !queue.isEmpty)
     }
 
+    static func missingHeadChecks() {
+        let ticks: [Int64] = [-48000, 0, 48000, 96000, 144000, 192000, 240000, 288000, 336000, 384000, 424040, 464080]
+        let order: [Int64] = [0, 6, 2, 4, 12, 8, 10, 18, 14, 16, 22, 20]
+        let keys = [true] + Array(repeating: false, count: 11)
+        func proof(_ dts: [Int64] = ticks, pts: [Int64]? = nil, pocs: [Int64] = order,
+                   start: Int64 = 0, origin: Int64 = -48000, depth: Int = 1) -> Int? {
+            Policy.missingHeadForwardDepth(dts: dts, pts: pts ?? dts, pocs: pocs, keys: keys,
+                streamStart: start, ladderStart: origin, reorderDepth: depth)
+        }
+        precondition(proof() == 2) // Forward-coded P differs from backward reorder lead.
+        precondition(proof(start: -48000) == nil)
+        precondition(proof(start: 1) == nil)
+        precondition(proof(origin: 0) == nil)
+        precondition(proof(depth: 0) == nil)
+        precondition(proof(depth: 17) == nil)
+        precondition(proof(pocs: Array(stride(from: Int64(0), to: 24, by: 2))) == nil)
+        for bad: Int64 in [-1, 3, 6, 1000, Int64.max] {
+            var changed = order; changed[4] = bad
+            precondition(proof(pocs: changed) == nil)
+        }
+        var offset = ticks; offset[3] += 1
+        precondition(proof(pts: offset) == nil)
+        var flat = ticks; flat[3] = flat[2]
+        precondition(proof(flat) == nil)
+        var missing = ticks; missing[3] = Int64.min
+        precondition(proof(missing) == nil)
+        precondition(proof(Array(ticks.prefix(11))) == nil)
+        print("PASS missing head: corroborated lead, variable slots, bounded forward reorder; invalid/ambiguous evidence refused")
+    }
+
+    static func forwardProofChecks() {
+        let ranks = [0, 4, 2, 1, 3, 8, 6, 5, 7, 12, 10, 9]
+        let dts = (0..<12).map { Int64($0) * 3600 }
+        func proof(_ order: [Int] = ranks, slots: [Int64] = dts, lead: Int64 = 7200,
+                   depth: Int = 2) -> Int? {
+            Policy.provenForwardDepth(dts: slots, ranks: order, lead: lead, reorderDepth: depth)
+        }
+        precondition(proof() == 3)
+        precondition(proof(slots: dts.map { $0 + 63_000_000 }) == 3)
+        precondition(proof(lead: 3600) == nil)
+        precondition(proof(depth: 1) == nil)
+        precondition(proof(Array(ranks.prefix(11)), slots: Array(dts.prefix(11))) == nil)
+        precondition(proof(Array(0..<12)) == nil)
+        for bad in [-1, 0, 1000, Int.max] {
+            var order = ranks; order[4] = bad
+            precondition(proof(order) == nil)
+        }
+        // Unique bounded ranks can still omit a display slot: no complete prefix, no proof.
+        precondition(proof([0, 5, 3, 2, 4, 9, 7, 6, 8, 13, 11, 10]) == nil)
+        var repeated = dts; repeated[4] = repeated[3]
+        precondition(proof(slots: repeated) == nil)
+        var missing = dts; missing[4] = Int64.min
+        precondition(proof(slots: missing) == nil)
+        precondition(proof(slots: dts.map { Int64.max - 40000 + $0 }) == nil)
+        var ladder = Policy.SlotLadder()
+        for value in dts { precondition(ladder.append(dts: value)) }
+        precondition(ladder.claim(rank: 4, decodeIndex: 1, lead: 7200, reorderDepth: 2) == .refuse)
+        precondition(ladder.refusalReason == "forward_wait_depth_exceeded")
+        precondition(ladder.claim(rank: 4, decodeIndex: 1, lead: 7200, reorderDepth: 2, forwardDepth: 3) == .time(21600))
+        precondition(ladder.claim(rank: 4, decodeIndex: 1, lead: 7200, reorderDepth: 2, forwardDepth: 3) == .refuse)
+        precondition(ladder.refusalReason == "duplicate_display_rank")
+        print("PASS partial forward proof: complete prefix, asymmetric depth, exact slot, invalid evidence refused")
+    }
+
     static func main() {
+        missingHeadChecks()
+        forwardProofChecks()
         let expected = pocs.map { slots[Int($0 / 2)] + lead }
         let plain = run()
         precondition(!plain.refused)
diff --git a/Scripts/tests/make-missing-head-fixture.py b/Scripts/tests/make-missing-head-fixture.py
new file mode 100644
index 000000000..a1546ee41
--- /dev/null
+++ b/Scripts/tests/make-missing-head-fixture.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Generate a public variable-cadence H.264 twin, never consume real media.
+
+Run the timestamp runtime on missing-head.mp4 at 0 1.5 0 20 40, and on
+healthy-head.mp4 at 0. The former must remove frame-PTS regressions while
+preserving DTS/audio/payload; the latter must remain byte-for-byte unchanged.
+This fixture proves display ordering, not recovery of an arbitrary writer's
+lost original composition timestamps or physical A/V synchronization.
+"""
+import argparse
+from pathlib import Path
+import struct
+import subprocess
+
+parser = argparse.ArgumentParser(description=__doc__)
+parser.add_argument('output', type=Path)
+parser.add_argument('--partial-hierarchical', action='store_true', help='Generate healthy/tail/middle B3 twins for the partial-region path')
+args = parser.parse_args()
+args.output.mkdir(parents=True, exist_ok=True)
+if args.partial_hierarchical:
+    healthy = args.output / 'healthy-b3.mp4'
+    subprocess.run([
+        'ffmpeg', '-hide_banner', '-loglevel', 'error', '-n',
+        '-f', 'lavfi', '-i', 'color=c=blue:s=96x64:r=25:d=24',
+        '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000:duration=24',
+        '-c:v', 'libx264', '-preset', 'fast', '-pix_fmt', 'yuv420p', '-g', '49', '-bf', '3',
+        '-x264-params', 'scenecut=0:b-adapt=0', '-c:a', 'aac', '-video_track_timescale', '90000',
+        '-metadata', 'comment=Aether synthetic timestamp fixture', '-movflags', '+faststart', str(healthy),
+    ], check=True)
+    # 49-picture GOPs align the IDR boundaries with ctts runs; mutate offsets only.
+    for mode in ('tail', 'middle'):
+        subprocess.run(['ruby', str(Path(__file__).with_name('make-partial-ctts-fixture.rb')),
+                        str(healthy), str(args.output / (mode + '-b3.mp4')), mode, '196', '392', '600'], check=True)
+    raise SystemExit(0)
+
+healthy = args.output / 'healthy-head.mp4'
+missing = args.output / 'missing-head.mp4'
+if healthy.exists() or missing.exists():
+    raise SystemExit('Refusing to replace an existing fixture')
+subprocess.run([
+    'ffmpeg', '-hide_banner', '-loglevel', 'error', '-n',
+    '-f', 'lavfi', '-i', 'testsrc2=s=96x64:r=25:d=60',
+    '-f', 'lavfi', '-i', 'sine=frequency=440:sample_rate=48000:duration=60',
+    '-vf', "settb=1/1200000,setpts='if(lt(N,8),N*48000,384000+(N-8)*40040)'",
+    '-fps_mode', 'passthrough', '-enc_time_base', '1/1200000',
+    '-c:v', 'libx264', '-preset', 'fast', '-pix_fmt', 'yuv420p',
+    '-g', '60', '-bf', '2', '-x264-params', 'scenecut=0:b-adapt=0:b-pyramid=none',
+    '-c:a', 'aac', '-video_track_timescale', '1200000',
+    '-metadata', 'comment=Aether synthetic timestamp fixture',
+    '-movflags', '+faststart', str(healthy),
+], check=True)
+data = bytearray(healthy.read_bytes())
+changed = 0
+
+
+def zero_offsets(start, end):
+    global changed
+    while start < end:
+        size, kind = struct.unpack_from('>I4s', data, start)
+        assert size >= 8 and start + size <= end
+        if kind in (b'moov', b'trak', b'mdia', b'minf', b'stbl'):
+            zero_offsets(start + 8, start + size)
+        elif kind == b'ctts':
+            count = struct.unpack_from('>I', data, start + 12)[0]
+            assert size == 16 + 8 * count
+            for index in range(count):
+                offset = start + 16 + 8 * index
+                changed += struct.unpack_from('>I', data, offset)[0]
+                struct.pack_into('>I', data, offset + 4, 0)
+        start += size
+
+
+zero_offsets(0, len(data))
+assert changed == 1500
+with missing.open('xb') as output:
+    output.write(data)
+print('PASS generated missing-head twin: 1500 frames, retained edit/index/audio/payload')
diff --git a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
index f718bd9d2..1f0329007 100644
--- a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
+++ b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
@@ -622,6 +622,7 @@ final class H264CompositionOffsetRepairSession {
     private let partialRepairCandidate: H264PartialCompositionRepairSession?
     private var monitorsPartialOffsets = false
     private var samples: [H264CompositionOffsetRepair.Sample] = []
+    private var sampledFramePictures = true
     private var held: [(packet: UnsafeMutablePointer<AVPacket>, pictureOrderCount: Int64?)] = []
     private var heldBytes = 0
     private var verdictDescription = "sampling"
@@ -701,6 +702,7 @@ final class H264CompositionOffsetRepairSession {
             var pictureOrderCount: Int64?
             if packet.pointee.stream_index == streamIndex {
                 pictureOrderCount = reader?.pictureOrderCount(for: packet)
+                sampledFramePictures = sampledFramePictures && reader?.isFramePicture == true
                 samples.append(
                     H264CompositionOffsetRepair.Sample(
                         dts: packet.pointee.dts,
@@ -801,6 +803,7 @@ final class H264CompositionOffsetRepairSession {
         case .sampling:
             // The sample restarts where the source now stands.
             samples.removeAll(keepingCapacity: true)
+            sampledFramePictures = true
         case .repairing:
             rewriter?.noteSeek()
             reader?.reset()
@@ -882,6 +885,25 @@ final class H264CompositionOffsetRepairSession {
             verdictDescription = "healthy"
             disarm()
         case .inconclusive(let reason):
+            if reason == "decode ladder is not uniform", sampledFramePictures,
+               let candidate = partialRepairCandidate,
+               let forwardDepth = H264PartialCompositionRepair.missingHeadForwardDepth(
+                   dts: samples.map(\.dts), pts: samples.map(\.pts),
+                   pocs: samples.map(\.pictureOrderCount), keys: samples.map(\.isKeyframe),
+                   streamStart: streamStartTime, ladderStart: ladderStart, reorderDepth: videoDelay),
+               let firstPacket = held.first(where: { $0.packet.pointee.stream_index == streamIndex })?.packet,
+               candidate.enableMissingHead(forwardDepth: forwardDepth, firstPacket: firstPacket) {
+                // Reuse #513's streaming slots. Hand over each interleaved packet once;
+                // leading non-video packets remain ahead of the candidate's queue.
+                monitorsPartialOffsets = true
+                disarm()
+                let input = held
+                held.removeAll(keepingCapacity: false)
+                heldBytes = 0
+                for entry in input where !candidate.ingest(entry.packet) { held.append(entry) }
+                samples.removeAll(keepingCapacity: false)
+                return
+            }
             verdictDescription = "inconclusive (\(reason))"
             // Only worth a line when the stream looked like a candidate: a file that simply carries
             // composition offsets is the normal case and says nothing.
diff --git a/Sources/AetherEngine/Video/H264PartialCompositionRepair.swift b/Sources/AetherEngine/Video/H264PartialCompositionRepair.swift
index 6f5f887c9..4ed6cb1e0 100644
--- a/Sources/AetherEngine/Video/H264PartialCompositionRepair.swift
+++ b/Sources/AetherEngine/Video/H264PartialCompositionRepair.swift
@@ -9,8 +9,8 @@ import Foundation
 /// slot waits exactly the mini-GOP the reorder created, so nothing is held for the length of a
 /// sequence and no sequence is too long to repair.
 enum H264PartialCompositionRepair {
-    /// A picture cannot sit further from its own slot than the reorder delay the container
-    /// declares. `video_delay` is the honest bound; this is only the ceiling on believing it.
+    /// Backward displacement must fit the declared reorder delay. Forward-coded anchors may
+    /// be further ahead (#700); a separate bounded prefix proof must establish that distance.
     static let maximumReorderDepth = 16
     /// A sequence past this is not a GOP any more, and the ladder is one Int64 per picture.
     static let maximumPictures = 1 << 16
@@ -23,6 +23,59 @@ enum H264PartialCompositionRepair {
     /// that reorders at all shows it within its reorder delay; this is slack, not a policy.
     static let maximumProofPictures = 64
 
+    /// A missing-offset head has no healthy packet to corroborate its lead. Require
+    /// the container start/index distance to equal the observed reorder head, then
+    /// dry-run the existing slots. Never fit an average rate to variable timestamps.
+    static func missingHeadForwardDepth(
+        dts: [Int64], pts: [Int64], pocs: [Int64], keys: [Bool],
+        streamStart: Int64, ladderStart: Int64, reorderDepth: Int
+    ) -> Int? {
+        guard dts.count >= 12, dts.count <= maximumProofPictures,
+              pts.count == dts.count, pocs.count == dts.count, keys.count == dts.count,
+              (1...maximumReorderDepth).contains(reorderDepth), reorderDepth < dts.count,
+              streamStart != Int64.min, ladderStart != Int64.min,
+              dts.first == ladderStart, keys.first == true, pocs.first == 0,
+              !keys.dropFirst().contains(true), pts == dts else { return nil }
+        let (lead, overflow) = streamStart.subtractingReportingOverflow(ladderStart)
+        let (observed, headOverflow) = dts[reorderDepth].subtractingReportingOverflow(ladderStart)
+        guard !overflow, !headOverflow, lead > 0, lead == observed else { return nil }
+        var ranks: [Int] = []
+        for poc in pocs {
+            guard poc >= 0, poc % 2 == 0, poc / 2 < Int64(maximumPictures) else { return nil }
+            ranks.append(Int(poc / 2))
+        }
+        return provenForwardDepth(dts: dts, ranks: ranks, lead: lead, reorderDepth: reorderDepth)
+    }
+
+    /// Reuse #700's closed decode-prefix evidence for #513's original timestamp slots.
+    /// Uniqueness plus [0...prefix.count-1] coverage proves a complete mini-GOP prefix;
+    /// the declared backward depth and every observed slot/lead still have to agree.
+    static func provenForwardDepth(dts: [Int64], ranks: [Int], lead: Int64,
+                                   reorderDepth: Int) -> Int? {
+        guard (12...maximumProofPictures).contains(dts.count), ranks.count == dts.count,
+              ranks.first == 0, lead > 0, (1...maximumReorderDepth).contains(reorderDepth),
+              ranks.allSatisfy({ $0 >= 0 && $0 < maximumPictures }),
+              Set(ranks).count == ranks.count,
+              zip(ranks, ranks.dropFirst()).contains(where: { $1 < $0 }) else { return nil }
+        var ladder = SlotLadder()
+        for timestamp in dts { guard ladder.append(dts: timestamp) else { return nil } }
+        var high = 0
+        var closedPrefix = false
+        var forward = reorderDepth
+        for (index, rank) in ranks.enumerated() {
+            high = max(high, rank)
+            if index >= 8, high == index { closedPrefix = true }
+            guard index - rank <= reorderDepth, rank - index <= maximumReorderDepth else { return nil }
+            forward = max(forward, rank - index)
+        }
+        guard closedPrefix else { return nil }
+        for (index, rank) in ranks.enumerated() {
+            if ladder.claim(rank: rank, decodeIndex: index, lead: lead,
+                            reorderDepth: reorderDepth, forwardDepth: forward) == .refuse { return nil }
+        }
+        return forward
+    }
+
     enum Claim: Equatable {
         /// The slot is still ahead of the reader. The picture waits, and so does everything
         /// behind it, because the container's own order is what leaves this demuxer.
@@ -36,6 +89,7 @@ enum H264PartialCompositionRepair {
     struct SlotLadder {
         private var slots: [Int64] = []
         private var claimed: [Bool] = []
+        private(set) var refusalReason = "none"
 
         var count: Int { slots.count }
         var isEmpty: Bool { slots.isEmpty }
@@ -52,14 +106,26 @@ enum H264PartialCompositionRepair {
 
         /// The presentation time the picture at `decodeIndex` owns, given its display `rank`.
         /// `.wait` while its slot is still ahead of the reader, which is the mini-GOP.
-        mutating func claim(rank: Int, decodeIndex: Int, lead: Int64, reorderDepth: Int) -> Claim {
+        mutating func claim(rank: Int, decodeIndex: Int, lead: Int64, reorderDepth: Int,
+                            forwardDepth: Int? = nil) -> Claim {
+            refusalReason = "none"
+            let forward = forwardDepth ?? reorderDepth
             guard lead > 0, rank >= 0, decodeIndex >= 0, decodeIndex < slots.count,
-                  abs(rank - decodeIndex) <= reorderDepth, rank < Self.limit else { return .refuse }
+                  (1...H264PartialCompositionRepair.maximumReorderDepth).contains(forward),
+                  rank < Self.limit else { refusalReason = "invalid_slot_claim"; return .refuse }
+            guard decodeIndex - rank <= reorderDepth else {
+                refusalReason = "backward_reorder_depth_exceeded"; return .refuse
+            }
+            guard rank - decodeIndex <= forward else {
+                refusalReason = "forward_wait_depth_exceeded"; return .refuse
+            }
             guard rank < slots.count else { return .wait }
-            // One slot, one picture. A rank claimed twice is a sequence this policy cannot own.
-            guard !claimed[rank] else { return .refuse }
+            guard !claimed[rank] else { refusalReason = "duplicate_display_rank"; return .refuse }
             let (pts, overflow) = slots[rank].addingReportingOverflow(lead)
-            guard !overflow, pts >= slots[decodeIndex] else { return .refuse }
+            guard !overflow else { refusalReason = "presentation_time_overflow"; return .refuse }
+            guard pts >= slots[decodeIndex] else {
+                refusalReason = "presentation_before_decode"; return .refuse
+            }
             claimed[rank] = true
             return .time(pts)
         }
diff --git a/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift b/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift
index b69941ec3..825d831be 100644
--- a/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift
+++ b/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift
@@ -24,6 +24,12 @@ final class H264PartialCompositionRepairSession {
     private let timeBase: AVRational
     private let lead: Int64
     private let reorderDepth: Int
+    private var missingHead = false
+    private var forwardDepth: Int?
+    // Numeric evidence only, capped independently of interleaved packet/byte budgets.
+    private var proofDTS: [Int64] = []
+    private var proofRanks: [Int] = []
+    private var forwardProofs = 0
     private let framing: VideoNALFraming
     private let reader: H264PictureOrderReader
     private var pending: [Entry] = []
@@ -55,7 +61,21 @@ final class H264PartialCompositionRepairSession {
     }
 
     deinit { releasePackets() }
-    var hasDecision: Bool { reason != "composition_offsets_present" }
+    var hasDecision: Bool { missingHead || reason != "composition_offsets_present" }
+
+    /// Only the parent's head proof enables this. Healthy-head behavior is unchanged.
+    func enableMissingHead(forwardDepth: Int, firstPacket: UnsafeMutablePointer<AVPacket>) -> Bool {
+        precondition(!inSequence && pending.isEmpty && ready.isEmpty)
+        guard isIDR(firstPacket) else { return false }
+        missingHead = true
+        self.forwardDepth = forwardDepth
+        reason = "missing_composition_offsets_pending"
+        return true
+    }
+
+    private var confirmedReason: String {
+        missingHead ? "confirmed_missing_composition_offsets" : "confirmed_partial_composition_offsets"
+    }
 
     private func isIDR(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
         guard packet.pointee.flags & AV_PKT_FLAG_KEY != 0,
@@ -96,16 +116,20 @@ final class H264PartialCompositionRepairSession {
             inSequence = true
         }
         if abandoned { return handBack(packet) }
-        guard !missing, ladder.append(dts: packet.pointee.dts) else { return failOpen(with: packet) }
+        guard !missing, ladder.append(dts: packet.pointee.dts) else { return failOpen(with: packet, cause: "missing_or_nonincreasing_dts") }
         let poc = reader.pictureOrderCount(for: packet)
         // Complete, closed, progressive sequences only. Fields, open-GOP leading pictures and a
         // parser that cannot read an order are not guessed at.
         guard let poc, reader.isFramePicture, poc >= 0, poc % 2 == 0,
               decodeIndex > 0 || poc == 0,
               packet.pointee.flags & AV_PKT_FLAG_KEY == 0 || (idr && poc == 0)
-        else { return failOpen(with: packet) }
+        else { return failOpen(with: packet, cause: "unsupported_picture_order") }
         let rank = Int(poc / 2)
         if rank != decodeIndex { sequenceReordered = true }
+        if !missingHead && proofRanks.count < H264PartialCompositionRepair.maximumProofPictures {
+            proofDTS.append(packet.pointee.dts)
+            proofRanks.append(rank)
+        }
         append(packet, rank: rank)
         decodeIndex += 1
         drain()
@@ -119,21 +143,43 @@ final class H264PartialCompositionRepairSession {
         guard confirmed || sequenceReordered else { return }
         while let first = pending.first {
             guard let rank = first.rank else { promoteFirst(); continue }
-            switch ladder.claim(rank: rank, decodeIndex: first.decodeIndex, lead: lead, reorderDepth: reorderDepth) {
+            if !missingHead, forwardDepth == nil, rank - first.decodeIndex > reorderDepth {
+                // Keep the existing fast path for ordinary mini-GOPs. Only an anchor beyond the
+                // old symmetric allowance waits for bounded, complete-prefix evidence.
+                if let depth = H264PartialCompositionRepair.provenForwardDepth(
+                    dts: proofDTS, ranks: proofRanks, lead: lead, reorderDepth: reorderDepth),
+                    rank - first.decodeIndex <= depth {
+                    forwardDepth = depth
+                    forwardProofs += 1
+                    if forwardProofs <= 8 {
+                        EngineLog.emit("[Demuxer] H264 slot forward wait proven: rank=\(rank)"
+                            + " decode_index=\(first.decodeIndex) samples=\(proofRanks.count)"
+                            + " reorder_depth=\(reorderDepth) forward_depth=\(depth)", category: .demux)
+                    }
+                } else if proofRanks.count < H264PartialCompositionRepair.maximumProofPictures {
+                    deepestWait = max(deepestWait, pending.count)
+                    return
+                } else {
+                    failOpen(cause: "forward_prefix_unproven")
+                    return
+                }
+            }
+            switch ladder.claim(rank: rank, decodeIndex: first.decodeIndex, lead: lead,
+                                reorderDepth: reorderDepth, forwardDepth: forwardDepth) {
             case .wait:
                 deepestWait = max(deepestWait, pending.count)
                 return
             case .refuse:
-                failOpen()
+                failOpen(cause: ladder.refusalReason)
                 return
             case .time(let pts):
                 first.packet.pointee.pts = pts
                 repairedCount += 1
                 if !confirmed {
                     confirmed = true
-                    reason = "confirmed_partial_composition_offsets"
+                    reason = confirmedReason
                     EngineLog.emit(
-                        "[Demuxer] partial H264 composition offsets confirmed: reorder_depth=\(reorderDepth)"
+                        "[Demuxer] H264 slot composition offsets confirmed: kind=\(confirmedReason) reorder_depth=\(reorderDepth)"
                         + " presentation_lead=\(lead) decode_offset=0 time_base=\(timeBase.num)/\(timeBase.den)",
                         category: .demux
                     )
@@ -160,18 +206,25 @@ final class H264PartialCompositionRepairSession {
         if pending.count >= H264PartialCompositionRepair.maximumHeldPackets
             || bytes >= H264PartialCompositionRepair.maximumHeldBytes
             || (!confirmed && !sequenceReordered && decodeIndex > H264PartialCompositionRepair.maximumProofPictures) {
-            failOpen()
+            failOpen(cause: "packet_byte_or_proof_limit")
         }
     }
 
     /// Hands every held packet back untouched and lets the rest of this sequence stream through.
     /// The next IDR starts a new candidate; nothing about the session is given up.
     @discardableResult
-    private func failOpen(with packet: UnsafeMutablePointer<AVPacket>? = nil) -> Bool {
+    private func failOpen(with packet: UnsafeMutablePointer<AVPacket>? = nil, cause: String) -> Bool {
         if !abandoned, inSequence {
             abandoned = true
             abandonedSequences += 1
-            if reason == "confirmed_partial_composition_offsets" {
+            // One bounded diagnostic per refused sequence; never log payloads or source URLs.
+            if abandonedSequences <= 8 {
+                EngineLog.emit("[Demuxer] H264 slot repair refused: cause=\(cause)"
+                    + " rank=\(pending.first?.rank ?? -1) decode_index=\(pending.first?.decodeIndex ?? decodeIndex)"
+                    + " samples=\(decodeIndex) reorder_depth=\(reorderDepth) forward_depth=\(forwardDepth ?? reorderDepth)"
+                    + " presentation_lead=\(lead) held_packets=\(pending.count) held_bytes=\(bytes)", category: .demux)
+            }
+            if reason == confirmedReason {
                 reason = "partial_composition_sequence_unproven_after_repair"
             } else {
                 reason = "partial_composition_sequence_unproven"
@@ -192,7 +245,7 @@ final class H264PartialCompositionRepairSession {
     private func closeSequence() {
         drain()
         // Anything still waiting is waiting for a slot this sequence never carried.
-        if !pending.isEmpty { failOpen() }
+        if !pending.isEmpty { failOpen(cause: "incomplete_sequence") }
         resetSequence()
     }
 
@@ -202,6 +255,9 @@ final class H264PartialCompositionRepairSession {
         inSequence = false
         sequenceReordered = false
         abandoned = false
+        proofDTS.removeAll(keepingCapacity: true)
+        proofRanks.removeAll(keepingCapacity: true)
+        if !missingHead { forwardDepth = nil }
     }
 
     private func publishPending() {
@@ -227,7 +283,7 @@ final class H264PartialCompositionRepairSession {
         reader.reset()
         resetSequence()
         confirmed = false
-        reason = "composition_offsets_present"
+        reason = missingHead ? "missing_composition_offsets_pending" : "composition_offsets_present"
     }
 
     private func releasePackets() {
@@ -239,7 +295,8 @@ final class H264PartialCompositionRepairSession {
 
     var summary: String {
         "reason=\(reason) repaired=\(repairedCount) abandoned_sequences=\(abandonedSequences)"
-            + " deepest_wait=\(deepestWait) reorder_depth=\(reorderDepth)"
+            + " deepest_wait=\(deepestWait) reorder_depth=\(reorderDepth) forward_proofs=\(forwardProofs)"
             + " presentation_lead=\(lead) decode_offset=0"
     }
+
 }
diff --git a/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift b/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift
index d01688edd..9612b7df7 100644
--- a/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift
+++ b/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift
@@ -68,6 +68,40 @@ struct H264CompositionOffsetRepairTests {
         #expect(verdict(samples) == .inconclusive("decode ladder is not uniform"))
     }
 
+    @Test("a hierarchical anchor proves forward distance separately from backward reorder depth")
+    func partialForwardPrefix() {
+        let ranks = [0, 4, 2, 1, 3, 8, 6, 5, 7, 12, 10, 9]
+        let dts = (0..<12).map { Int64($0) * 3600 }
+        #expect(H264PartialCompositionRepair.provenForwardDepth(
+            dts: dts, ranks: ranks, lead: 7200, reorderDepth: 2) == 3)
+        #expect(H264PartialCompositionRepair.provenForwardDepth(
+            dts: dts, ranks: ranks, lead: 3600, reorderDepth: 2) == nil)
+        #expect(H264PartialCompositionRepair.provenForwardDepth(
+            dts: dts, ranks: ranks, lead: 7200, reorderDepth: 1) == nil)
+        #expect(H264PartialCompositionRepair.provenForwardDepth(
+            dts: dts, ranks: [0, 5, 3, 2, 4, 9, 7, 6, 8, 13, 11, 10],
+            lead: 7200, reorderDepth: 2) == nil)
+    }
+
+    @Test("a variable-cadence missing head requires an exactly corroborated container lead")
+    func variableCadenceHeadProof() {
+        let dts: [Int64] = [-96000, -48000, 0, 48000, 96000, 144000,
+                            192000, 240000, 288000, 328040, 368080, 408120]
+        let pocs: [Int64] = [0, 6, 2, 4, 12, 8, 10, 18, 14, 16, 24, 20]
+        let keys = [true] + Array(repeating: false, count: 11)
+        #expect(H264PartialCompositionRepair.missingHeadForwardDepth(
+            dts: dts, pts: dts, pocs: pocs, keys: keys,
+            streamStart: 0, ladderStart: -96000, reorderDepth: 2) == 2)
+        #expect(H264PartialCompositionRepair.missingHeadForwardDepth(
+            dts: dts, pts: dts, pocs: pocs, keys: keys,
+            streamStart: 1, ladderStart: -96000, reorderDepth: 2) == nil)
+        var healthy = dts
+        healthy[0] = 0
+        #expect(H264PartialCompositionRepair.missingHeadForwardDepth(
+            dts: dts, pts: healthy, pocs: pocs, keys: keys,
+            streamStart: 0, ladderStart: -96000, reorderDepth: 2) == nil)
+    }
+
     @Test("a sample that does not start on a picture-order origin cannot be anchored")
     func mustStartOnOrigin() {
         var samples = malformedSamples()
diff --git a/docs/formats.md b/docs/formats.md
index 9d8f1e5df..b154e40e6 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -57,10 +57,16 @@ zero). A source is only repaired when every sampled pair is equal, the decode la
 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
+short of that (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; the HEVC case (#699) by @ijuniorfu.
 
+For H.264 only, a changing decode cadence can instead use the original-slot policy described below.
+This fallback requires a progressive IDR head with equal PTS/DTS, a container start/index lead that
+exactly matches the observed reorder head, and a complete, distinct picture-order prefix whose
+timestamps pass the slot policy. It assigns existing slots plus that lead rather than fitting a
+frame rate; DTS, audio and the keyframe index remain unchanged. An ambiguous head stays untouched.
+
 ### Matroska with presentation slots in coding order
 
 Matroska block timestamps are presentation timestamps by specification, and the format has no
@@ -104,10 +110,9 @@ offsets. Seeking into that region can produce persistent judder despite normal
 aggregate FPS and sufficient network buffering.
 
 When a healthy origin picture corroborates the container's edit/index lead, the
-demuxer keeps a zero-hold healthy path and watches for zero-offset IDRs. One
-bounded, complete IDR-to-IDR progressive sequence is parsed for picture order.
-If every selected packet has valid equal PTS/DTS and its distinct even POC fills
-the complete sequence, a proven permutation assigns its original DTS slots plus
+demuxer keeps a zero-hold healthy path and watches for zero-offset IDRs. Progressive
+pictures are parsed as they arrive. Valid equal PTS/DTS and distinct even POC let
+the streaming slot ladder assign original DTS slots plus
 the corroborated presentation lead by display rank. Original DTS, audio and the
 already published keyframe index never move. Actual timestamp slots, rather than
 an average-FPS clock, preserve interval changes and quantization within a sequence.
@@ -115,8 +120,11 @@ an average-FPS clock, preserve interval changes and quantization within a sequen
 The slot a picture needs is a packet away, not a plan away, exactly as in the Matroska
 policy above: a picture coded ahead of its own slot waits the mini-GOP the reorder
 created, so nothing waits for the end of a sequence and no sequence is too long to
-repair. The wait is bounded by the reorder delay the container declares, believed up
-to **16 pictures**, and the packets held behind it by **1024 interleaved packets and
+repair. Backward displacement remains bounded by the declared reorder delay. A forward-coded
+anchor farther ahead needs a bounded, complete decode-prefix proof, as in #700: distinct ranks
+fill a prefix, the backward delay still fits, and the observed slots plus lead pass a dry run.
+Only the measured forward distance is then allowed, limited to **16 pictures**; that proof resets
+at each candidate IDR. The packets held behind it remain bounded by **1024 interleaved packets and
 32 MiB**, which is a ceiling on a container's interleaving rather than on its GOP.
 A candidate sequence has to show its reordering within **64 pictures** before a single
 picture is rewritten.
@@ -127,7 +135,8 @@ not guessed at. **Every refusal hands the held packets back exactly as they arri
 and lets the rest of that sequence stream through, so a shape this policy does not own
 costs the repair and never the session; the next IDR is a fresh candidate. Seek and
 teardown release both unpublished input and pending output. No decoder-route or host-UI
-change is needed. The existing whole-file missing-offset policy above remains separate.
+change is needed. The uniform whole-file policy above is unchanged; its strictly proven
+variable-cadence H.264 fallback reuses this same slot ladder.
 
 See the [partial-composition regression and reproduction](partial-composition-regression.md)
 for generated fixtures, original numeric evidence and verification limits.

From b76b1153523760d6df2d1331d3d0a40e69af3fbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Sch=C3=B6ldstr=C3=B6m?= <m@oxy.fi>
Date: Tue, 13 Oct 2026 07:38:45 -0300
Subject: [PATCH 006/132] fix(demux): reconstruct clamped Matroska H264
 timestamps

Co-Authored-By: OpenAI Codex <noreply@openai.com>
---
 .../Video/H264MatroskaSlotPermutation.swift   | 206 ++++++++++++++++--
 .../Issue511MatroskaCodingOrderTests.swift    |  67 ++++++
 2 files changed, 258 insertions(+), 15 deletions(-)

diff --git a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
index 53720e956..6e6adf862 100644
--- a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
+++ b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
@@ -59,8 +59,8 @@ enum H264MatroskaSlotPermutation {
     typealias Sample = H264CompositionOffsetRepair.Sample
 
     /// Video pictures to sample before deciding, and the same held-packet ceilings the ISO-BMFF
-    /// sample pays. A well-formed MKV with B-frames never reaches any of them: its first stepped-back
-    /// slot ends the sampling, and that is normally the third packet.
+    /// sample pays. Streams without an exact whole-tick cadence still exit on their first
+    /// stepped-back slot, normally the third packet.
     static let sampleTarget = H264CompositionOffsetRepair.sampleTarget
     static let minimumSamples = H264CompositionOffsetRepair.minimumSamples
     static let sampleByteBudget = H264CompositionOffsetRepair.sampleByteBudget
@@ -71,6 +71,12 @@ enum H264MatroskaSlotPermutation {
     /// wait nobody should pay.
     static let lookaheadCeiling: Int64 = 32
 
+    private static func timestamp(anchor: Int64, index: Int64, step: Int64) -> Int64? {
+        let (offset, productOverflow) = index.multipliedReportingOverflow(by: step)
+        let (value, sumOverflow) = anchor.addingReportingOverflow(offset)
+        return productOverflow || sumOverflow ? nil : value
+    }
+
     enum Verdict: Equatable, Sendable {
         /// The container presents in display order, which is what the format says it should do.
         case healthy
@@ -78,29 +84,25 @@ enum H264MatroskaSlotPermutation {
         case inconclusive(String)
         /// Ticks a picture order count advances per displayed picture, measured rather than assumed.
         case permute(pocStep: Int64)
+        /// A CFR ladder whose B-picture timestamps were clamped forward onto their decode slots.
+        case reconstruct(step: Int64, pocStep: Int64)
     }
 
     /// Fail-closed decision over the sampled head. Anything unproven returns `.inconclusive`, which
     /// leaves the stream exactly as the container delivered it.
-    static func classify(samples: [Sample], videoDelay: Int) -> Verdict {
+    static func classify(samples: [Sample], videoDelay: Int, nominalStep: Int64? = nil) -> Verdict {
         guard videoDelay > 0, videoDelay <= 16 else {
             return .inconclusive("reorder delay \(videoDelay) outside 1...16")
         }
-        // One stepped-back slot is the container doing its job, and it ends the sampling before the
-        // window fills. `PTS != DTS` proves nothing here: libavformat synthesizes a decode ladder
-        // from a rising presentation one just as readily as from a reordered one, which is why the
-        // ISO-BMFF eligibility test cannot be reused.
         let slots = samples.map(\.pts)
-        if zip(slots, slots.dropFirst()).contains(where: { $1 < $0 }) { return .healthy }
+        if nominalStep == nil,
+           zip(slots, slots.dropFirst()).contains(where: { $1 < $0 }) { return .healthy }
         guard samples.count >= minimumSamples else {
             return .inconclusive("only \(samples.count) sampled pictures")
         }
         guard slots.allSatisfy({ $0 != Int64.min }) else {
             return .inconclusive("presentation slots are not all stated")
         }
-        guard !zip(slots, slots.dropFirst()).contains(where: { $1 == $0 }) else {
-            return .inconclusive("two pictures share a presentation slot")
-        }
         guard let first = samples.first, first.isKeyframe, first.pictureOrderCount == 0 else {
             return .inconclusive("sample does not start on a picture-order origin")
         }
@@ -141,6 +143,64 @@ enum H264MatroskaSlotPermutation {
               highest - lowest + 1 <= Int64(samples.count + videoDelay + 1) else {
             return .inconclusive("display ranks do not fill the sampled window")
         }
+
+        // Some Matroska writers preserve most CFR presentation slots but clamp a B picture whose
+        // true PTS precedes its synthesized DTS forward onto that DTS. The result has paired duplicate
+        // PTS/DTS slots and paired holes: decoded output alternates 0 and 2 frame intervals forever.
+        // Reconstruct only when the container's declared rate is an exact whole-tick cadence, every
+        // picture-order rank lands either on that lattice or on this precise forward clamp, and at
+        // least two clamps corroborate the shape. A VFR ladder, one damaged packet, and #511's
+        // coding-order-slot defect all fail closed.
+        if let step = nominalStep, step > 0 {
+            let anchor = first.pts
+            var clamped = 0
+            var reconstructable = true
+            for (decodeIndex, sample) in samples.enumerated() {
+                let rank = sample.pictureOrderCount / pocStep
+                guard let expectedPTS = timestamp(anchor: anchor, index: rank, step: step),
+                      let expectedDTS = timestamp(
+                        anchor: anchor,
+                        index: Int64(decodeIndex) - Int64(videoDelay), step: step)
+                else {
+                    reconstructable = false
+                    break
+                }
+                if sample.pts != expectedPTS {
+                    let (forward, overflow) = sample.pts.subtractingReportingOverflow(expectedPTS)
+                    guard !overflow, sample.pts == sample.dts, forward == step,
+                          !slots.contains(expectedPTS),
+                          slots.filter({ $0 == sample.pts }).count == 2 else {
+                        reconstructable = false
+                        break
+                    }
+                    clamped += 1
+                }
+                if sample.dts == Int64.min {
+                    guard decodeIndex < videoDelay else {
+                        reconstructable = false
+                        break
+                    }
+                } else if sample.dts != expectedDTS {
+                    let (forward, overflow) = sample.dts.subtractingReportingOverflow(expectedDTS)
+                    guard !overflow, sample.pts != expectedPTS, sample.dts == sample.pts,
+                          forward == step else {
+                        reconstructable = false
+                        break
+                    }
+                }
+            }
+            if reconstructable, clamped >= 2 {
+                return .reconstruct(step: step, pocStep: pocStep)
+            }
+        }
+
+        // One stepped-back slot is the container doing its job. `PTS != DTS` proves nothing here:
+        // libavformat synthesizes a decode ladder from a rising presentation one just as readily as
+        // from a reordered one, which is why the ISO-BMFF eligibility test cannot be reused.
+        if zip(slots, slots.dropFirst()).contains(where: { $1 < $0 }) { return .healthy }
+        guard !zip(slots, slots.dropFirst()).contains(where: { $1 == $0 }) else {
+            return .inconclusive("two pictures share a presentation slot")
+        }
         // The muxer invariant, checked on the window before a single packet is moved: a picture may
         // sit at most its own reorder delay behind the slot it owns, or its repaired presentation
         // time would land before the decode time the container states for it.
@@ -151,6 +211,64 @@ enum H264MatroskaSlotPermutation {
         return .permute(pocStep: pocStep)
     }
 
+    struct CFRRewriter {
+        let step: Int64
+        let pocStep: Int64
+        let videoDelay: Int
+        private(set) var brokenReason: String?
+        private var anchorPTS: Int64?
+        private var decodeIndex: Int64 = 0
+
+        mutating func noteSeek() {
+            anchorPTS = nil
+            decodeIndex = 0
+            brokenReason = nil
+        }
+
+        mutating func rewrite(
+            pts: Int64, dts: Int64, pictureOrderCount: Int64?, isKeyframe: Bool
+        ) -> (pts: Int64, dts: Int64)? {
+            guard brokenReason == nil else { return nil }
+            if isKeyframe, pictureOrderCount == 0 {
+                anchorPTS = nil
+                decodeIndex = 0
+                if pts != Int64.min { anchorPTS = pts }
+            }
+            guard let anchorPTS else {
+                return nil
+            }
+            defer { decodeIndex += 1 }
+            guard let pictureOrderCount, pictureOrderCount >= 0, pocStep > 0,
+                  pictureOrderCount % pocStep == 0 else {
+                brokenReason = "a picture carries no usable picture order"
+                return nil
+            }
+            guard let expectedPTS = H264MatroskaSlotPermutation.timestamp(
+                    anchor: anchorPTS, index: pictureOrderCount / pocStep, step: step),
+                  let expectedDTS = H264MatroskaSlotPermutation.timestamp(
+                    anchor: anchorPTS, index: decodeIndex - Int64(videoDelay), step: step)
+            else {
+                brokenReason = "timestamp reconstruction overflowed"
+                return nil
+            }
+
+            let ptsForward = pts.subtractingReportingOverflow(expectedPTS)
+            let dtsForward = dts.subtractingReportingOverflow(expectedDTS)
+            let unsetDTS = dts == Int64.min
+            let ptsFits = pts == expectedPTS
+                || (!ptsForward.overflow && ptsForward.partialValue == step)
+            let dtsFits = dts == expectedDTS
+                || unsetDTS
+                || (!dtsForward.overflow && dtsForward.partialValue == step)
+            guard ptsFits, dtsFits else {
+                brokenReason = "the timestamp ladder changed shape "
+                    + "(pts=\(pts)/\(expectedPTS) dts=\(dts)/\(expectedDTS))"
+                return nil
+            }
+            return (expectedPTS, expectedDTS)
+        }
+    }
+
     /// One coded video sequence, as the container hands it out. Values only, so the permutation is
     /// testable without FFmpeg.
     struct Sequence {
@@ -257,7 +375,7 @@ enum H264MatroskaSlotPermutation {
 /// interleave waits with it, which is one mini-GOP and not one sequence.
 final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
 
-    enum Phase: Equatable { case sampling, permuting, off }
+    enum Phase: Equatable { case sampling, permuting, reconstructing, off }
 
     private struct Entry {
         let packet: UnsafeMutablePointer<AVPacket>
@@ -279,6 +397,8 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
     private var ready: [UnsafeMutablePointer<AVPacket>] = []
     private var pendingBytes = 0
     private var sequence: H264MatroskaSlotPermutation.Sequence?
+    private var cfrRewriter: H264MatroskaSlotPermutation.CFRRewriter?
+    private let nominalStep: Int64?
     private var verdictDescription = "sampling"
 
     /// nil unless this stream is the shape the defect needs: Matroska, H.264, and a bitstream that
@@ -299,6 +419,12 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
         self.streamIndex = streamIndex
         self.videoDelay = Int(codecpar.pointee.video_delay)
         self.reader = reader
+        let rate = stream.pointee.avg_frame_rate.num > 0 && stream.pointee.avg_frame_rate.den > 0
+            ? stream.pointee.avg_frame_rate : stream.pointee.r_frame_rate
+        let numerator = Int64(stream.pointee.time_base.den) * Int64(rate.den)
+        let denominator = Int64(stream.pointee.time_base.num) * Int64(rate.num)
+        nominalStep = denominator > 0 && numerator > 0 && numerator % denominator == 0
+            ? numerator / denominator : nil
     }
 
     deinit { releasePending() }
@@ -329,11 +455,29 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
             if samples.count >= H264MatroskaSlotPermutation.sampleTarget
                 || pendingBytes >= H264MatroskaSlotPermutation.sampleByteBudget
                 || pending.count >= H264MatroskaSlotPermutation.heldPacketCeiling
-                || earlyHealthyVerdict {
+                || (nominalStep == nil && earlyHealthyVerdict) {
                 decide()
             }
             return true
         }
+        if phase == .reconstructing {
+            if isPicture, var rewriter = cfrRewriter {
+                applyCFRRepair(
+                    to: packet, pictureOrderCount: pictureOrderCount,
+                    using: &rewriter
+                )
+                cfrRewriter = rewriter
+                if let reason = rewriter.brokenReason {
+                    verdictDescription = "stopped (\(reason))"
+                    EngineLog.emit(
+                        "[Demuxer] Matroska H.264 CFR reconstruction stopped on stream "
+                        + "\(streamIndex): \(reason)", category: .demux)
+                    phase = .off
+                    cfrRewriter = nil
+                }
+            }
+            return false
+        }
         let rank = isPicture ? admit(packet, pictureOrderCount: pictureOrderCount) : nil
         append(packet, isPicture: isPicture, pictureOrderCount: pictureOrderCount, rank: rank)
         drain()
@@ -432,7 +576,7 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
     }
 
     /// A well-formed MKV with B-frames proves itself on the packet that steps back, which is normally
-    /// the third one, so it never pays the sample window.
+    /// the third one. Exact whole-tick CFR candidates keep sampling so duplicate slots can be checked.
     private var earlyHealthyVerdict: Bool {
         guard samples.count >= 2 else { return false }
         let last = samples[samples.count - 1]
@@ -441,7 +585,8 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
     }
 
     private func decide() {
-        let verdict = H264MatroskaSlotPermutation.classify(samples: samples, videoDelay: videoDelay)
+        let verdict = H264MatroskaSlotPermutation.classify(
+            samples: samples, videoDelay: videoDelay, nominalStep: nominalStep)
         switch verdict {
         case .permute(let pocStep):
             verdictDescription = "permute pocStep=\(pocStep)"
@@ -463,6 +608,23 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
                 pending[index].rank = rank
             }
             drain()
+        case .reconstruct(let step, let pocStep):
+            verdictDescription = "reconstruct step=\(step) pocStep=\(pocStep)"
+            phase = .reconstructing
+            var rewriter = H264MatroskaSlotPermutation.CFRRewriter(
+                step: step, pocStep: pocStep, videoDelay: videoDelay)
+            for entry in pending where entry.isPicture {
+                applyCFRRepair(
+                    to: entry.packet, pictureOrderCount: entry.pictureOrderCount,
+                    using: &rewriter
+                )
+            }
+            cfrRewriter = rewriter
+            flushPendingUntouched()
+            EngineLog.emit(
+                "[Demuxer] Matroska H.264 clamped CFR timestamps confirmed on stream "
+                + "\(streamIndex): \(verdictDescription) samples=\(samples.count)",
+                category: .demux)
         case .healthy:
             verdictDescription = "healthy"
             disarm()
@@ -502,6 +664,7 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
         reader.reset()
         if phase == .sampling { samples.removeAll(keepingCapacity: true) }
         sequence?.noteSeek()
+        cfrRewriter?.noteSeek()
     }
 
     private func releasePending() {
@@ -527,4 +690,17 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
             + "repaired=\(sequence?.repairedPictures ?? 0) "
             + "unrepaired=\(sequence?.unrepairedPictures ?? 0)"
     }
+
+    private func applyCFRRepair(
+        to packet: UnsafeMutablePointer<AVPacket>,
+        pictureOrderCount: Int64?,
+        using rewriter: inout H264MatroskaSlotPermutation.CFRRewriter
+    ) {
+        if let repaired = rewriter.rewrite(
+            pts: packet.pointee.pts, dts: packet.pointee.dts,
+            pictureOrderCount: pictureOrderCount, isKeyframe: isKeyframe(packet)) {
+            packet.pointee.pts = repaired.pts
+            packet.pointee.dts = repaired.dts
+        }
+    }
 }
diff --git a/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift b/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
index f63122715..09d0f1c0f 100644
--- a/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
+++ b/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
@@ -167,6 +167,73 @@ struct Issue511MatroskaCodingOrderTests {
         #expect(Permutation.classify(samples: Array(healthy.prefix(3)), videoDelay: 1) == .healthy)
     }
 
+    @Test("clamped CFR B-picture timestamps are reconstructed from picture order")
+    func reconstructsClampedCFR() throws {
+        let n = Int64.min
+        let samples = [
+            Sample(dts: n, pts: 0, pictureOrderCount: 0, isKeyframe: true),
+            Sample(dts: n, pts: 200, pictureOrderCount: 10, isKeyframe: false),
+            Sample(dts: 0, pts: 80, pictureOrderCount: 4, isKeyframe: false),
+            Sample(dts: 80, pts: 80, pictureOrderCount: 2, isKeyframe: false),
+            Sample(dts: 80, pts: 120, pictureOrderCount: 6, isKeyframe: false),
+            Sample(dts: 120, pts: 160, pictureOrderCount: 8, isKeyframe: false),
+            Sample(dts: 160, pts: 440, pictureOrderCount: 22, isKeyframe: false),
+            Sample(dts: 200, pts: 320, pictureOrderCount: 16, isKeyframe: false),
+            Sample(dts: 280, pts: 280, pictureOrderCount: 12, isKeyframe: false),
+            Sample(dts: 280, pts: 280, pictureOrderCount: 14, isKeyframe: false),
+            Sample(dts: 320, pts: 360, pictureOrderCount: 18, isKeyframe: false),
+            Sample(dts: 360, pts: 400, pictureOrderCount: 20, isKeyframe: false),
+        ]
+        #expect(Permutation.classify(samples: samples, videoDelay: 2, nominalStep: 40)
+            == .reconstruct(step: 40, pocStep: 2))
+
+        let repairedPTS: [Int64] = [0, 200, 80, 40, 120, 160, 440, 320, 240, 280, 360, 400]
+        let repairedDTS: [Int64] = [-80, -40, 0, 40, 80, 120, 160, 200, 240, 280, 320, 360]
+        let healthy = zip(samples.indices, samples).map { index, sample in
+            Sample(
+                dts: repairedDTS[index], pts: repairedPTS[index],
+                pictureOrderCount: sample.pictureOrderCount, isKeyframe: sample.isKeyframe)
+        }
+        #expect(Permutation.classify(samples: healthy, videoDelay: 2, nominalStep: 40) == .healthy)
+        #expect(Permutation.classify(samples: samples, videoDelay: 2, nominalStep: Int64.max)
+            == .healthy)
+        var oneClamp = samples
+        oneClamp[8] = Sample(
+            dts: 240, pts: 240, pictureOrderCount: 12, isKeyframe: false)
+        #expect(Permutation.classify(samples: oneClamp, videoDelay: 2, nominalStep: 40)
+            == .healthy)
+
+        var rewriter = Permutation.CFRRewriter(step: 40, pocStep: 2, videoDelay: 2)
+        let repaired = samples.map {
+            rewriter.rewrite(
+                pts: $0.pts, dts: $0.dts, pictureOrderCount: $0.pictureOrderCount,
+                isKeyframe: $0.isKeyframe)
+        }
+        #expect(try repaired.map { try #require($0).pts } == repairedPTS)
+        #expect(try repaired.map { try #require($0).dts } == repairedDTS)
+
+        #expect(rewriter.rewrite(
+            pts: n, dts: n, pictureOrderCount: 0, isKeyframe: true) == nil)
+        #expect(rewriter.rewrite(
+            pts: 480, dts: 400, pictureOrderCount: 2, isKeyframe: false) == nil)
+        #expect(rewriter.rewrite(
+            pts: 1_000, dts: n, pictureOrderCount: 0, isKeyframe: true)?.pts == 1_000)
+        _ = rewriter.rewrite(
+            pts: 1_200, dts: n, pictureOrderCount: 10, isKeyframe: false)
+        _ = rewriter.rewrite(
+            pts: 1_080, dts: 1_000, pictureOrderCount: 4, isKeyframe: false)
+        #expect(rewriter.rewrite(
+            pts: 1_160, dts: n, pictureOrderCount: 6, isKeyframe: false)?.pts == 1_120)
+        #expect(rewriter.rewrite(
+            pts: 1_200, dts: 1_120, pictureOrderCount: 8, isKeyframe: false)?.dts == 1_080)
+
+        var broken = Permutation.CFRRewriter(step: 40, pocStep: 2, videoDelay: 2)
+        _ = broken.rewrite(pts: 0, dts: n, pictureOrderCount: 0, isKeyframe: true)
+        #expect(broken.rewrite(pts: 200, dts: n, pictureOrderCount: nil, isKeyframe: false) == nil)
+        #expect(broken.brokenReason != nil)
+        #expect(broken.rewrite(pts: 80, dts: 0, pictureOrderCount: 4, isKeyframe: false) == nil)
+    }
+
     @Test("shapes this permutation does not describe are left alone")
     func failsClosed() {
         func verdict(slots: [Int64], pocs: [Int64], videoDelay: Int = 1) -> Permutation.Verdict {

From 523b90471a5570d4b43e3614ee390bd7b85ae129 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Oskar=20Sch=C3=B6ldstr=C3=B6m?= <m@oxy.fi>
Date: Tue, 13 Oct 2026 07:47:18 -0300
Subject: [PATCH 007/132] docs(changelog): note Matroska H264 cadence repair

Co-Authored-By: OpenAI Codex <noreply@openai.com>
---
 CHANGELOG.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 751e60c90..bdc77b362 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,14 @@ the public-API contract.
 
 ### Fixed
 
+- **A 25 fps H.264 Matroska file with forward-clamped B-picture timestamps plays at a steady
+  cadence.** Its packet timestamps repeated display slots and left the preceding slots empty, so
+  decoded output alternated 0 ms and 80 ms frame intervals instead of 40 ms. The demuxer now
+  recognizes that shape only from an exact CFR lattice, complete picture-order ranks and two
+  corroborating clamps, then reconstructs PTS and DTS from the IDR anchor, picture order and decode
+  order. A seek starts from a new IDR, and overflow or any later timestamp outside the proven shape
+  disables the repair and leaves that packet untouched.
+
 - **A host with its own Objective-C and C++ links again (#752).** Since 7.34.0 LibTrueHD and LibDovi
   each brought a `rust_eh_personality`, and with the host's `__objc_personality_v0` and
   `__gxx_personality_v0` that made four personality routines, one more than compact unwind encodes

From 93d2be8b72db9f0f2d61b5c57eb55d8fb7b4595c Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:29:07 +0100
Subject: [PATCH 008/132] feat(dovi): Metal FEL composer and Dolby Vision
 display metadata (not routed)

Adds the pieces that rebuild a Profile 7 FEL picture, with nothing selecting
them yet.

- DoviFelComposer (Metal): rebuilds the 12-bit picture from base layer,
  enhancement layer and RPU: reshaping curves (polynomial and MMR), inverse
  NLQ, MMR chroma, bilinear EL upsampling, ordered dither down to 10-bit,
  output in a pooled P010 buffer, composeAsync bounded at maxFramesInFlight.
  DoviMetalParams is the parameter ABI, DoviShaderSource the kernels. The
  output pool survives a seek flush (flush() trims idle buffers,
  releaseOutputPool() drops it on teardown): dropping it made post-seek
  frames allocate a second full pool beside the buffers the renderer still
  held, about +260 MB at 4K for ~0.6 s per seek; measured end to end with
  the decoder in the next PRs, peak 674 -> 500 MB over 12 seeks.
- DoviDisplayMetadata: attaches the Profile 8.1 RPU as DolbyVisionRPUData
  plus DolbyCompatibilityID (a CFString: a CFNumber aborts the render
  server). Both keys are undocumented; they are defined in this one file
  and UndocumentedDolbyVisionKeysTests fails if either literal appears in
  another source file.
- DoviRpuConverter.separateDualLayers splits one packet into base layer,
  enhancement-layer packet, converted RPU and composer parameters;
  convertPacketToProfile81 is now that walk with the EL dropped. The RPU
  attached to composed frames is converted with mode 2 (the composer has
  already applied the reshaping and added the residual, so the display side
  must not reshape again); DoviComposedFrameRpuTests pins this.

Nothing calls the composer, so no behaviour changes for any source. Public
API: none. Not in this PR: the dual-layer decoder, the routing flag and
host wiring, the aetherctl tooling, and dolby-vision-fel.md (comments here
cite its section numbers; the document arrives with the route PR).

Tests: GPU curve sweep, edge cases and adversarial inputs, layout probe (the
GPU reads each parameter sub-block back at the offset Swift wrote it),
shader/ABI sync, dither, enhancement upsampler, FEL math, FEL and
CRC-valid-mutation fuzzers, converter and guard tests, async compose,
look-ahead pool sizing. The real-clip tests skip without DV_FEL_TESTS_DIR.
---
 .../Video/DoviDisplayMetadata.swift           |  122 ++
 .../AetherEngine/Video/DoviRpuConverter.swift |  305 +++-
 .../Video/Metal/DoviFelComposer.swift         | 1452 +++++++++++++++++
 .../Video/Metal/DoviMetalParams.swift         |  315 ++++
 .../Video/Metal/DoviShaderSource.swift        |  722 ++++++++
 .../DoviComposeAsyncTests.swift               |  283 ++++
 .../DoviComposedFrameRpuTests.swift           |  305 ++++
 .../DoviCrcValidFuzzTests.swift               |  150 ++
 .../DoviDisplayMetadataTests.swift            |   99 ++
 Tests/AetherEngineTests/DoviDitherTests.swift |  291 ++++
 .../DoviElBitDepthTests.swift                 |  100 ++
 .../DoviEnhancementUpsamplerTests.swift       |   62 +
 .../AetherEngineTests/DoviFelFuzzTests.swift  |  252 +++
 .../AetherEngineTests/DoviFelMathTests.swift  |  323 ++++
 .../DoviFelRealFileTests.swift                |   46 +
 .../DoviGpuAdversarialTests.swift             |  210 +++
 .../DoviGpuCurveSweepTests.swift              |  393 +++++
 .../DoviGpuEdgeCaseTests.swift                |  492 ++++++
 .../DoviLayoutProbeTests.swift                |  240 +++
 .../DoviRpuConverterTests.swift               |  194 +++
 .../AetherEngineTests/DoviRpuGuardTests.swift |    7 +
 .../DoviShaderSyncTests.swift                 |   81 +
 .../SampleBufferRendererLookaheadTests.swift  |    5 +
 .../Support/DoviTestSupport.swift             |   31 +
 .../UndocumentedDolbyVisionKeysTests.swift    |   33 +
 docs/architecture.md                          |    9 +-
 26 files changed, 6453 insertions(+), 69 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/DoviDisplayMetadata.swift
 create mode 100644 Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
 create mode 100644 Sources/AetherEngine/Video/Metal/DoviMetalParams.swift
 create mode 100644 Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
 create mode 100644 Tests/AetherEngineTests/DoviComposeAsyncTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviDisplayMetadataTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviDitherTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviElBitDepthTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviFelFuzzTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviFelMathTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviFelRealFileTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviLayoutProbeTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviShaderSyncTests.swift
 create mode 100644 Tests/AetherEngineTests/Support/DoviTestSupport.swift
 create mode 100644 Tests/AetherEngineTests/UndocumentedDolbyVisionKeysTests.swift

diff --git a/Sources/AetherEngine/Video/DoviDisplayMetadata.swift b/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
new file mode 100644
index 000000000..5443014b1
--- /dev/null
+++ b/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
@@ -0,0 +1,122 @@
+import Foundation
+import CoreVideo
+
+/// Per-frame Dolby Vision display metadata carried on a `CVPixelBuffer`.
+///
+/// The FEL composer reconstructs the 12-bit master on the GPU, but reconstruction only
+/// restores *pixels*. The display side of Dolby Vision — L1 frame statistics, L2 creative
+/// trims, L5 active area, L8/L9/L11 — is metadata that has to travel alongside the frame
+/// so the compositor can drive the panel (or hand it to the TV over HDMI). On the
+/// `AVPlayer` path VideoToolbox does this itself; on the `AVSampleBufferDisplayLayer` path
+/// the buffers are ours, so the metadata is ours to attach.
+///
+/// ## The channel
+/// CoreVideo and IOSurface both expose this channel under plain string keys
+/// (`kCVImageBufferDolbyVisionRPUDataKey`, `kIOSurfaceDolbyVisionRPUData`), so it can be
+/// driven with `CVBufferSetAttachment` with no private symbol linkage. It is still
+/// SPI in spirit: the keys are not in any header, and nothing contractual says a
+/// given OS release will consume them.
+///
+/// ## The payload, established empirically
+/// Decoding a Profile 8.1 asset through `AVAssetReader` and dumping every attachment on the
+/// output buffers shows VideoToolbox setting exactly two keys per frame — `DolbyVisionRPUData`
+/// (a 188/189-byte `CFData` that changes frame to frame) and `DolbyCompatibilityID` (`1`) —
+/// on both the `CVBuffer` and its backing `IOSurface`. Comparing those payloads byte-for-byte
+/// against the source bitstream identifies them exactly: **the `unspec62` NAL with its 2-byte
+/// HEVC NAL header (`0x7C 0x01`) removed and emulation-prevention bytes retained.** The
+/// EPB-stripped RBSP is 176 bytes and does not match, which rules out the other plausible
+/// reading.
+///
+/// That is precisely what `DoviRpuConverter.separateDualLayers` already produces: libdovi
+/// converts the stream's Profile 7 RPU to Profile 8.1 with
+/// `dovi_convert_rpu_with_mode(rpu, 2)`, which preserves the full DM payload (L1/L2/L5/L8/L9/L11)
+/// and only rewrites the profile-specific container. The consumer on Apple platforms is the
+/// private `HDRProcessing.framework` (`DolbyVisionComposer`, `DolbyVisionDisplayManagement`,
+/// destination display types `…DolbyVisionTV` / `…LowLatencyDolbyVisionTV`).
+///
+/// ## What is verified
+/// Verified on macOS: VideoToolbox *produces* these attachments in this exact format, and a
+/// hand-set attachment propagates to the backing `IOSurface` and survives into `CMSampleBuffer`.
+///
+/// Verified on an Apple TV 4K (tvOS 27.0): the compositor **does** consume them from a
+/// client-supplied buffer on the `AVSampleBufferDisplayLayer` path. The proof arrived the hard
+/// way — as a `backboardd` crash report — but it is unambiguous, because the whole stack is in
+/// the trace:
+///
+/// ```
+/// CA::WindowServer::IOMFBServer::vsync_callback          (thread com.apple.coreanimation.display.external-0)
+/// CA::Render::ImageQueue::forward_dm
+/// CA::HDRProcessorInternal::create_surface_with_forward_dm
+/// CA::HDRProcessorInternal::tonemap_surface_internal(__IOSurface*, …, __CFData const*, …)
+/// -[HDRProcessor generateMSRColorConfigWithOperation:inputSurface:outputSurface:metadata:…]
+/// -[HDRProcessor processFrameInternalWithLayer0:layer1:outout:metadata:…]
+/// -[HDRProcessor applyDoVi81PolicyWithInput:WithRPU:]
+/// ```
+///
+/// That is the *external display* CoreAnimation thread, on the vsync callback, pulling forward
+/// display management off our `IOSurface` and applying Dolby Vision 8.1 policy with our RPU.
+/// Nothing else puts `HDRProcessor` on that thread with a `__CFData` in hand. The attachment
+/// channel works, and it reaches the HDMI output.
+enum DoviDisplayMetadata {
+
+    // MARK: Undocumented attachment keys
+    //
+    // These two strings are the ONLY undocumented platform contract the FEL route depends on, and
+    // this is the only place they are spelled (`UndocumentedDolbyVisionKeysTests` fails the build if
+    // either literal appears anywhere else in `Sources/`). Neither is in a public header; both are
+    // what VideoToolbox itself attaches with `kVTDecompressionPropertyKey_PropagatePerFrameHDRDisplayMetadata`,
+    // and what tvOS's compositor reads back. No OS release promises to keep honouring them. If one
+    // stops (the dv-pulse test in `Probes/DolbyVisionPulse` shows it: the pulse goes flat, like its "S" arm),
+    // this is the one spot to change, and `preferDualLayerDolbyVision = false` is the fallback.
+
+    /// `kCVImageBufferDolbyVisionRPUDataKey` / `kIOSurfaceDolbyVisionRPUData`. Undocumented.
+    static let rpuDataKey = "DolbyVisionRPUData"
+    /// `kCVImageBufferDolbyCompatibilityIDKey`. Undocumented.
+    static let compatibilityIDKey = "DolbyCompatibilityID"
+
+    /// Profile 8 compatibility ID 1 — HDR10-compatible base layer, which is what
+    /// `dovi_convert_rpu_with_mode(rpu, 2)` targets and what the composed frame is.
+    ///
+    /// A **string**, deliberately. VideoToolbox emits this attachment as a `CFString` `"1"`
+    /// (`NSTaggedPointerString`), not as a number, and tvOS depends on that: inside
+    /// `-[HDRProcessor applyDoVi81PolicyWithInput:WithRPU:]` the value is parsed with
+    /// `CFStringGetIntValue`, which messages `-length` on whatever it is handed. A `CFNumber`
+    /// here does not respond to `-length`, so it raises `NSInvalidArgumentException` on
+    /// backboardd's `com.apple.coreanimation.display.external-0` thread and aborts the render
+    /// server — which takes this app down with it, roughly a third of a second after the first
+    /// composed frame reaches the display. Confirmed twice on an Apple TV 4K (tvOS 27.0) and
+    /// diagnosed from the resulting `backboardd-*.ips`; the type was then read back off
+    /// VideoToolbox's own output to be sure. Do not "simplify" this to an integer.
+    static let profile81CompatibilityID = "1"
+
+    /// Attaches (or clears) the per-frame RPU on `buffer`.
+    ///
+    /// Pass `nil` to clear. Clearing matters: decoder output buffers are recycled from a
+    /// CoreVideo pool, so a frame that has no RPU must actively remove any attachment left
+    /// behind by a previous tenant rather than silently inherit stale trims.
+    ///
+    /// - Parameter nal: the Profile 8.1 `unspec62` NAL *including* its 2-byte header, as
+    ///   returned by `dovi_write_unspec62_nalu`. The header is stripped here.
+    static func attach(rpuNAL nal: [UInt8]?, to buffer: CVPixelBuffer) {
+        guard let payload = payload(fromNAL: nal) else {
+            CVBufferRemoveAttachment(buffer, rpuDataKey as CFString)
+            CVBufferRemoveAttachment(buffer, compatibilityIDKey as CFString)
+            return
+        }
+        CVBufferSetAttachment(buffer, rpuDataKey as CFString, payload as CFData, .shouldPropagate)
+        CVBufferSetAttachment(buffer, compatibilityIDKey as CFString, profile81CompatibilityID as CFString, .shouldPropagate)
+    }
+
+    /// Strips the `0x7C 0x01` unspec62 NAL header, leaving the RPU payload the attachment wants.
+    /// Emulation-prevention bytes are deliberately left in place — that is the form VideoToolbox
+    /// itself emits.
+    static func payload(fromNAL nal: [UInt8]?) -> Data? {
+        guard let nal, nal.count > 2 else { return nil }
+        if nal[0] == 0x7C && nal[1] == 0x01 {
+            return Data(nal.dropFirst(2))
+        }
+        // Already header-less (payload starts with the DV RPU prefix byte 0x19).
+        if nal[0] == 0x19 { return Data(nal) }
+        return nil
+    }
+}
diff --git a/Sources/AetherEngine/Video/DoviRpuConverter.swift b/Sources/AetherEngine/Video/DoviRpuConverter.swift
index a99b55b8c..62b972dd0 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter.swift
@@ -20,49 +20,156 @@ public enum DoviRpuConverter {
         }
     }
 
+    struct DualLayerPacketResult: @unchecked Sendable {
+        let elPacket: UnsafeMutablePointer<AVPacket>?
+        let rpuData: [UInt8]?
+        /// The Profile 8.1 RPU libdovi produced from `rpuData`, as a complete unspec62 NAL
+        /// (2-byte HEVC NAL header included). On the remux route this is what goes back into
+        /// the packet; on the FEL compose route it is the per-frame display metadata payload
+        /// (L1 statistics, L2 trims, L5/L8/L9/L11), which `DoviDisplayMetadata` attaches to the
+        /// composed pixel buffer. Nil when there was no RPU or the conversion failed.
+        let convertedRpu: [UInt8]?
+        let rpuParams: DoviMetalParams?
+        let isFEL: Bool
+        let isMEL: Bool
+        let success: Bool
+        /// `use_prev_vdr_rpu_flag`: the RPU carries no mapping and means "keep the previous one".
+        let usesPreviousMapping: Bool
+        /// This RPU's own `disable_residual_flag`. The header is read even when no mapping follows, so
+        /// a `use_prev_vdr_rpu_flag` frame can still say whether its residual applies.
+        let disableResidual: Bool
+
+        init(elPacket: UnsafeMutablePointer<AVPacket>?, rpuData: [UInt8]?, convertedRpu: [UInt8]? = nil, rpuParams: DoviMetalParams? = nil, isFEL: Bool, isMEL: Bool = false, success: Bool, usesPreviousMapping: Bool = false, disableResidual: Bool = false) {
+            self.elPacket = elPacket
+            self.rpuData = rpuData
+            self.convertedRpu = convertedRpu
+            self.rpuParams = rpuParams
+            self.isFEL = isFEL
+            self.isMEL = isMEL
+            self.success = success
+            self.usesPreviousMapping = usesPreviousMapping
+            self.disableResidual = disableResidual
+        }
+    }
+
+    /// Stream classification from one RPU (dolby-vision-fel.md §5.2, invariant I9): a property of the
+    /// encode, decided once. Only `el_type` feeds it — a per-frame `disable_residual_flag`
+    /// rides to the kernels in `DoviMetalParams.flags` (`.disableResidual`) and never
+    /// changes the classification.
+    enum StreamKind: Sendable, Equatable {
+        case undetermined
+        case fel
+        case mel
+    }
+
+    /// Classifies one `separateDualLayers` result. Pure over the result so the decoder's
+    /// one-shot latch and routing can share it.
+    static func classifyStream(_ result: DualLayerPacketResult) -> StreamKind {
+        if result.isMEL { return .mel }
+        if result.isFEL { return .fel }
+        return .undetermined
+    }
+
+    /// A piece of the rebuilt packet: points into the source packet (a NAL passed through) or into a
+    /// libdovi buffer (a rewritten RPU). Audit PERF-111: what survives is described, not copied, and the
+    /// one rebuild is the only copy.
+    private struct Piece {
+        let base: UnsafePointer<UInt8>
+        let count: Int
+    }
+
+    /// Writes `pieces` into a new padded buffer, each behind its start code or 4-byte length.
+    /// nil on an allocation failure. `total` is what `Self.framedSize` returned for the same pieces.
+    private static func buildPacketBuffer(
+        _ pieces: [Piece], total: Int, emitsStartCodes: Bool
+    ) -> UnsafeMutablePointer<AVBufferRef>? {
+        let pad = Int(AV_INPUT_BUFFER_PADDING_SIZE)
+        guard let ref = av_buffer_alloc(total + pad) else { return nil }
+        guard let dst = ref.pointee.data else {
+            var r: UnsafeMutablePointer<AVBufferRef>? = ref
+            av_buffer_unref(&r)
+            return nil
+        }
+        var w = 0
+        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 {
+                dst[w + 0] = UInt8((n >> 24) & 0xFF)
+                dst[w + 1] = UInt8((n >> 16) & 0xFF)
+                dst[w + 2] = UInt8((n >> 8) & 0xFF)
+                dst[w + 3] = UInt8(n & 0xFF)
+            }
+            w += lengthPrefixSize
+            if n > 0 {
+                memcpy(dst + w, piece.base, n)
+            }
+            w += n
+        }
+        memset(dst + total, 0, pad)   // decoders read past size
+        return ref
+    }
+
+    private static func framedSize(_ pieces: [Piece]) -> Int {
+        pieces.reduce(0) { $0 + lengthPrefixSize + $1.count }
+    }
+
     /// The Profile 8.1 form of a parsed RPU (`dovi_convert_rpu_with_mode`, mode 2) written back as an
     /// unspec62 NAL unit, or nil when libdovi refuses either step. The caller frees the result with
     /// `dovi_data_free`. This is the pair of calls the library can abort in, so everything that feeds it
     /// goes through `DoviRpuGuard.parse` first, and the tests drive it through this one entry point.
+    ///
+    /// Mode 2 and not 5, on the dual-layer route too: by the time a frame reaches the display layer the
+    /// Metal composer has already applied the RPU's luma/chroma reshaping and added the residual, so the
+    /// picture is finished. Mode 2 sets both curves to no-op (and drops the EL/NLQ part) while keeping
+    /// L1/L2 and the rest of the display metadata; an RPU that kept the mapping would make the display
+    /// side reshape a second time. `DoviComposedFrameRpuTests` pins this on the RPU attached to composed frames.
     static func convertedUnspec62(_ rpu: OpaquePointer) -> UnsafePointer<DoviData>? {
         guard dovi_convert_rpu_with_mode(rpu, 2) == 0 else { return nil }
         return dovi_write_unspec62_nalu(rpu)
     }
 
-    /// Returns `false` when a libdovi conversion fails (or on an internal allocation failure).
-    /// On a libdovi failure the offending RPU (and EL) are dropped so the frame degrades to the
-    /// clean HDR10 base, rather than shipping a P7 RPU inside a container already declared 8.1
-    /// (mixed-profile hazard, #135). Packets with no RPU/EL are left untouched and return `true`.
+    /// Splits a Profile 7 packet into its layers in one walk.
     ///
-    /// `framing` must be the framing of THIS packet, and the rewritten packet is emitted in the same
-    /// one: the mp4 muxer decides whether to convert samples from the extradata, so a packet that
-    /// changes framing under it is a second defect (#365). An Annex-B packet walked as length-
-    /// prefixed reads `00 00 01 40` as a 320-byte NAL and finds no RPU at all, which is how a P7
-    /// source shipped its RPU and EL untouched inside a container already rewritten to 8.1.
-    public static func convertPacketToProfile81(
+    /// The base-layer packet is rewritten in place to hold the base layer and the Profile 8.1 RPU (mode 2),
+    /// unless `useCustomBlockSource` leaves it untouched for a decoder that skips the unspec NALs itself.
+    /// With `extractEL` the enhancement layer comes back as a separate packet of its own (the 2-byte
+    /// unspec63 header stripped), stamped like the source; with `extractParams` the RPU is also parsed into
+    /// the composition parameters. This is the walk `convertPacketToProfile81` runs with both off.
+    ///
+    /// A libdovi failure drops the offending RPU, reports `success == false` and leaves the rest of the
+    /// packet usable (#135). The RPU is parsed through `DoviRpuGuard`, which refuses the CRC-valid inputs
+    /// that make libdovi abort.
+    static func separateDualLayers(
         _ packet: UnsafeMutablePointer<AVPacket>,
-        framing: VideoNALFraming = .lengthPrefixed(size: 4)
-    ) -> Bool {
-        guard let data = packet.pointee.data, packet.pointee.size > 0 else { return true }
-        guard packet.pointee.size > 4 else { return true }
-        guard Self.canRebuild(framing) else { return true }
+        framing: VideoNALFraming = .lengthPrefixed(size: 4),
+        extractEL: Bool = true,
+        useCustomBlockSource: Bool = false,
+        extractParams: Bool = true
+    ) -> DualLayerPacketResult {
+        let untouched = DualLayerPacketResult(elPacket: nil, rpuData: nil, isFEL: false, success: true)
+        guard let data = packet.pointee.data, packet.pointee.size > 4 else { return untouched }
+        guard Self.canRebuild(framing) else { return untouched }
         let size = Int(packet.pointee.size)
 
-        // 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
-        }
+        // The libdovi buffers a piece points into live until this function returns.
         var pieces: [Piece] = []
         pieces.reserveCapacity(16)
+        var elPieces: [Piece] = []
         var rewritten: [UnsafePointer<DoviData>] = []
         defer { for buffer in rewritten { dovi_data_free(buffer) } }
+        let keepRpuBytes = extractEL || extractParams
+        var rawRpuBytes: [UInt8]?
+        var convertedRpuBytes: [UInt8]?
+        var rpuParams: DoviMetalParams?
         var converted = false
-        var droppedEL = false
+        var isFEL = false
+        var isMEL = false
+        var hadEL = false
         var degraded = false
+        var usesPrevious = false
+        var disableResidual = false
 
         A53SEIParser.forEachNAL(data, size, framing) { nal, len in
             // HEVC NAL type: bits 1..6 of byte 0.
@@ -70,6 +177,10 @@ public enum DoviRpuConverter {
 
             switch nalType {
             case nalTypeRPU:
+                // Everything this RPU contributes is collected in locals and committed together once it has
+                // converted, so a packet with several RPUs never mixes bytes from one with parameters or
+                // a conversion from another: the outputs are those of the last RPU that fully succeeded.
+                let thisRaw: [UInt8]? = keepRpuBytes ? [UInt8](UnsafeBufferPointer(start: nal, count: len)) : nil
                 // Any libdovi failure drops the RPU (degraded) instead of muxing a stale P7 RPU
                 // inside a container already declared 8.1 (mixed-profile hazard, #135).
                 guard let rpu = DoviRpuGuard.parse(nal, len) else {
@@ -77,6 +188,23 @@ public enum DoviRpuConverter {
                     return
                 }
                 defer { dovi_rpu_free(rpu) }
+                let thisParams: DoviMetalParams? = extractParams ? DoviFelComposer.parseRpuParameters(rpu: rpu) : nil
+                var thisPrevious = false, thisDisableResidual = false, thisFEL = false, thisMEL = false
+                if let hdr = dovi_rpu_get_header(rpu) {
+                    if hdr.pointee.use_prev_vdr_rpu_flag { thisPrevious = true }
+                    thisDisableResidual = hdr.pointee.disable_residual_flag
+                    if let elTypePtr = hdr.pointee.el_type {
+                        switch String(cString: elTypePtr) {
+                        case "FEL": thisFEL = true
+                        case "MEL": thisMEL = true
+                        default: break
+                        }
+                    }
+                    // `disable_residual_flag` is per-RPU, not per-stream: it reaches the kernels as
+                    // `DoviComposerFlags.disableResidual` (set by `parseRpuParameters` above) and must
+                    // not flip the stream classification.
+                    dovi_rpu_free_header(hdr)
+                }
                 guard let out = Self.convertedUnspec62(rpu) else {
                     degraded = true
                     return
@@ -87,64 +215,107 @@ public enum DoviRpuConverter {
                     return
                 }
                 rewritten.append(out)
-                pieces.append(Piece(base: outData, count: out.pointee.len))
+                if !useCustomBlockSource {
+                    pieces.append(Piece(base: outData, count: out.pointee.len))
+                }
                 converted = true
 
+                rawRpuBytes = thisRaw
+                convertedRpuBytes = keepRpuBytes ? [UInt8](UnsafeBufferPointer(start: outData, count: out.pointee.len)) : nil
+                rpuParams = thisParams
+                usesPrevious = thisPrevious
+                disableResidual = thisDisableResidual
+                isFEL = thisFEL
+                isMEL = thisMEL
+
             case nalTypeEL:
-                droppedEL = true
+                hadEL = true
+                // Strip the 2-byte unspec63 NAL header (0x7E, 0x01) to reveal the raw HEVC NAL.
+                if extractEL && len > 2 {
+                    elPieces.append(Piece(base: nal + 2, count: len - 2))
+                }
 
             default:
-                pieces.append(Piece(base: nal, count: len))
+                if !useCustomBlockSource {
+                    pieces.append(Piece(base: nal, count: len))
+                }
             }
         }
 
-        if !converted && !droppedEL && !degraded {
-            return true
-        }
-
-        var total = 0
-        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 }
-
-        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 allocationFailed = false
 
-        let emitsStartCodes = framing == .annexB
-        var w = 0
-        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
+        // The EL packet is built BEFORE the base layer is rebuilt: its pieces point into the original buffer.
+        var producedElPacket: UnsafeMutablePointer<AVPacket>?
+        let elTotal = framedSize(elPieces)
+        if extractEL, elTotal > 0 {
+            var elPktOpt = trackedPacketAlloc()
+            if let elPkt = elPktOpt,
+               let elRef = buildPacketBuffer(elPieces, total: elTotal, emitsStartCodes: framing == .annexB) {
+                elPkt.pointee.pts = packet.pointee.pts
+                elPkt.pointee.dts = packet.pointee.dts
+                elPkt.pointee.duration = packet.pointee.duration
+                elPkt.pointee.flags = packet.pointee.flags
+                elPkt.pointee.stream_index = packet.pointee.stream_index
+                elPkt.pointee.buf = elRef
+                elPkt.pointee.data = elRef.pointee.data
+                elPkt.pointee.size = Int32(elTotal)
+                producedElPacket = elPkt
             } else {
-                dst[w + 0] = UInt8((n >> 24) & 0xFF)
-                dst[w + 1] = UInt8((n >> 16) & 0xFF)
-                dst[w + 2] = UInt8((n >> 8) & 0xFF)
-                dst[w + 3] = UInt8(n & 0xFF)
+                // The packet shell allocated but its buffer did not: free the shell.
+                if elPktOpt != nil { trackedPacketFree(&elPktOpt) }
+                allocationFailed = true
             }
-            w += lengthPrefixSize
-            if n > 0 {
-                memcpy(dst + w, piece.base, n)
+        }
+
+        // Rebuild the base layer (not with a custom block source: the FEL decoder needs the original
+        // packet untouched so VT can skip unspec62/63 NALs via the base-layer format description).
+        if (converted || hadEL || degraded), !useCustomBlockSource {
+            let total = framedSize(pieces)
+            // Degenerate: all NALs were RPU/EL. Leave the packet untouched rather than emit a zero-length video packet.
+            if total > 0 {
+                if let newRef = buildPacketBuffer(pieces, total: total, emitsStartCodes: framing == .annexB) {
+                    av_buffer_unref(&packet.pointee.buf)
+                    packet.pointee.buf = newRef
+                    packet.pointee.data = newRef.pointee.data
+                    packet.pointee.size = Int32(total)
+                } else {
+                    allocationFailed = true
+                }
             }
-            w += n
         }
-        memset(dst + total, 0, pad)   // decoders read past size
-        av_buffer_unref(&packet.pointee.buf)
-        packet.pointee.buf = newRef
-        packet.pointee.data = newRef.pointee.data
-        packet.pointee.size = Int32(total)
+
         // A dropped-RPU degrade still produces a valid HDR10 packet, but reports failure so callers
         // can log it and the probe can flag the source for dovi_tool inspection.
-        return !degraded
+        return DualLayerPacketResult(
+            elPacket: producedElPacket,
+            rpuData: rawRpuBytes,
+            convertedRpu: convertedRpuBytes,
+            rpuParams: rpuParams,
+            isFEL: isFEL && !isMEL,
+            isMEL: isMEL,
+            success: !degraded && !allocationFailed,
+            usesPreviousMapping: usesPrevious,
+            disableResidual: disableResidual
+        )
+    }
+
+    /// Returns `false` when a libdovi conversion fails (or on an internal allocation failure).
+    /// On a libdovi failure the offending RPU (and EL) are dropped so the frame degrades to the
+    /// clean HDR10 base, rather than shipping a P7 RPU inside a container already declared 8.1
+    /// (mixed-profile hazard, #135). Packets with no RPU/EL are left untouched and return `true`.
+    ///
+    /// `framing` must be the framing of THIS packet, and the rewritten packet is emitted in the same
+    /// one: the mp4 muxer decides whether to convert samples from the extradata, so a packet that
+    /// changes framing under it is a second defect (#365). An Annex-B packet walked as length-
+    /// prefixed reads `00 00 01 40` as a 320-byte NAL and finds no RPU at all, which is how a P7
+    /// source shipped its RPU and EL untouched inside a container already rewritten to 8.1.
+    ///
+    /// This is `separateDualLayers` with the enhancement layer dropped and no composition parameters.
+    public static func convertPacketToProfile81(
+        _ packet: UnsafeMutablePointer<AVPacket>,
+        framing: VideoNALFraming = .lengthPrefixed(size: 4)
+    ) -> Bool {
+        separateDualLayers(packet, framing: framing, extractEL: false, extractParams: false).success
     }
 
     /// Enhancement-layer type ("FEL" or "MEL") of the first unspec62 RPU in a P7 packet, or nil if
diff --git a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
new file mode 100644
index 000000000..18a5eae25
--- /dev/null
+++ b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
@@ -0,0 +1,1452 @@
+import Foundation
+import Metal
+import CoreVideo
+import CoreMedia
+import Dovi
+import os
+
+/// Hardware-accelerated Metal compute engine for Dolby Vision Profile 7 Full
+/// Enhancement Layer (FEL).
+///
+/// Reconstructs the VDR master from a 10-bit base layer and a 10-bit enhancement
+/// layer: each component's base-layer sample goes through its piecewise
+/// reshaping curve (polynomial or MMR), the inverse-NLQ residual decoded from the
+/// enhancement layer is added, and the result is quantised back down to a 10-bit
+/// video-range P010 CVPixelBuffer.
+final class DoviFelComposer: @unchecked Sendable {
+
+    /// `os_signpost` interval from "slot acquired, about to encode" to "GPU
+    /// retired, handing off to `OrderedDelivery`" (dolby-vision-fel.md §5.11), readable in
+    /// Instruments alongside `OrderedDelivery`'s own "Delivery" interval.
+    private static let signpostLog = OSLog(subsystem: EngineLog.subsystem, category: "dovi.compose")
+
+    private let device: MTLDevice
+    private let commandQueue: MTLCommandQueue
+    private var textureCache: CVMetalTextureCache?
+
+    /// Lazily compiled and process-shared compute pipelines (dolby-vision-fel.md §5.6).
+    private var pipelines: SharedPipelines?
+    /// Whether `dispatchThreads` is available. It needs non-uniform threadgroup
+    /// support (`MTLGPUFamily.apple4`, i.e. A11 and later; the first-generation
+    /// Apple TV 4K is A10X and is not); everything older has to dispatch whole
+    /// threadgroups and rely on the kernels' bounds guard.
+    private let supportsNonUniformThreadgroups: Bool
+
+    private var pixelBufferPool: CVPixelBufferPool?
+    private var poolWidth: Int = 0
+    private var poolHeight: Int = 0
+    private var poolBuffers: [WeakPoolBuffer] = []
+    private var poolBufferHighWaterMark = 0
+    /// Set by ``releaseOutputPool()``. A composition arriving after teardown (a VideoToolbox callback still in
+    /// flight when the decoder closed) is refused instead of quietly building a new pool nobody will release.
+    private var tornDown = false
+    private let lock = NSLock()
+
+    private final class WeakPoolBuffer {
+        weak var value: CVPixelBuffer?
+        init(_ value: CVPixelBuffer) { self.value = value }
+    }
+
+    /// Preallocated Metal parameter buffers (one per in-flight slot) to avoid per-frame allocations (dolby-vision-fel.md §5.6).
+    private let paramBuffers: [MTLBuffer]
+    /// Preallocated 1024-entry luma prediction LUT buffers (dolby-vision-fel.md §5.6).
+    private let lumaLutBuffers: [MTLBuffer]
+    private var freeParamSlotIndices: [Int]
+
+    /// Output pixel buffer pool status for 1 Hz summary diagnostics (dolby-vision-fel.md §5.11).
+    var allocatedPoolBuffers: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return poolBufferHighWaterMark
+    }
+
+    /// Number of `uint` slots `dovi_layout_probe` writes.
+    static let layoutProbeSlots = 36 + 3 * 20
+
+    /// Largest `coefficient_log2_denom` the fixed-point path accepts. The RPU
+    /// syntax caps it at 23 (0x17), so a
+    /// larger value means a misparse rather than an exotic stream.
+    private static let maxCoefLog2Denom = 23
+
+    /// One-shot latch for the `linear_deadzone_threshold != 0` diagnostic.
+    ///
+    /// The inverse NLQ adds the threshold to the scaled magnitude before the shift,
+    /// as the spec's pseudo-code and DoViBaker do; see `dovi_eval_inv_nlq`. Every
+    /// stream available to test against carries a zero threshold, so a non-zero one
+    /// is the first content to actually exercise that term and is worth saying so
+    /// out loud exactly once.
+    nonisolated(unsafe) private static var loggedNonZeroDeadzone = false
+    private static let deadzoneLogLock = NSLock()
+
+    /// Lines already logged by ``logOnce(_:)``. Bounded: a stream that varies the numbers in a message stops
+    /// being logged after `maxOnceLines` distinct lines instead of growing the set.
+    nonisolated(unsafe) private static var onceLines = Set<String>()
+    private static let onceLock = NSLock()
+    private static let maxOnceLines = 64
+
+    /// Logs a parse-time rejection once per distinct line. `parseRpuParameters` runs for every RPU, so a stream
+    /// that trips one of these would otherwise repeat it on every frame.
+    private static func logOnce(_ line: String, category: EngineLog.Category = .swPlayback) {
+        onceLock.lock()
+        let fresh = onceLines.count < maxOnceLines && onceLines.insert(line).inserted
+        onceLock.unlock()
+        if fresh { EngineLog.emit(line, category: category) }
+    }
+
+    /// Test seam: counts how many times `parseRpuParameters` has been called
+    /// (i.e., how many RPUs have been parsed). Reset with
+    /// `resetParseRpuCountForTesting()` between measurements.
+    /// Per thread, so concurrently running tests cannot disturb each other's count.
+    private static let parseCountKey = "DoviFelComposer.parseRpuCount"
+    private static var _parseRpuCount: Int {
+        get { Thread.current.threadDictionary[parseCountKey] as? Int ?? 0 }
+        set { Thread.current.threadDictionary[parseCountKey] = newValue }
+    }
+    static var parseRpuCountForTesting: Int { _parseRpuCount }
+    static func resetParseRpuCountForTesting() { _parseRpuCount = 0 }
+
+    enum ComposerError: Error, Sendable {
+        case missingKernelFunction
+    }
+
+    /// Process-shared compute pipelines compiled once per device (dolby-vision-fel.md §5.6).
+    final class SharedPipelines: @unchecked Sendable {
+        let lumaPipeline: MTLComputePipelineState
+        let chromaPipeline: MTLComputePipelineState
+        let layoutProbePipeline: MTLComputePipelineState?
+
+        init(
+            luma: MTLComputePipelineState,
+            chroma: MTLComputePipelineState,
+            probe: MTLComputePipelineState?
+        ) {
+            self.lumaPipeline = luma
+            self.chromaPipeline = chroma
+            self.layoutProbePipeline = probe
+        }
+
+        /// Per-device results, failures included: a shader that does not compile will not compile on the next
+        /// frame either, so the failure is kept and every later call fails fast instead of recompiling.
+        final class Cache: @unchecked Sendable {
+            private let lock = NSLock()
+            private var entries: [ObjectIdentifier: Result<SharedPipelines, Error>] = [:]
+
+            func resolve(device: MTLDevice, compile: () throws -> SharedPipelines) throws -> SharedPipelines {
+                lock.lock()
+                defer { lock.unlock() }
+                let key = ObjectIdentifier(device)
+                if let entry = entries[key] { return try entry.get() }
+                let result = Result { try compile() }
+                entries[key] = result
+                return try result.get()
+            }
+
+            func removeAll() {
+                lock.lock()
+                entries.removeAll()
+                lock.unlock()
+            }
+        }
+
+        private static let shared = Cache()
+
+        static func getOrCreate(device: MTLDevice) throws -> SharedPipelines {
+            try shared.resolve(device: device) {
+                do {
+                    return try compile(device: device, source: DoviShaderSource.source)
+                } catch {
+                    EngineLog.emit("[DoviFelComposer] Metal shader compilation error: \(error)", category: .swPlayback)
+                    throw error
+                }
+            }
+        }
+
+        static func compile(device: MTLDevice, source: String) throws -> SharedPipelines {
+            let library = try device.makeLibrary(source: source, options: nil)
+            guard let lumaFn = library.makeFunction(name: "dovi_compose_luma"),
+                  let chromaFn = library.makeFunction(name: "dovi_compose_chroma") else {
+                throw ComposerError.missingKernelFunction
+            }
+            let luma = try device.makeComputePipelineState(function: lumaFn)
+            let chroma = try device.makeComputePipelineState(function: chromaFn)
+            let probe: MTLComputePipelineState?
+            if let probeFn = library.makeFunction(name: "dovi_layout_probe") {
+                probe = try? device.makeComputePipelineState(function: probeFn)
+            } else {
+                probe = nil
+            }
+
+            return SharedPipelines(luma: luma, chroma: chroma, probe: probe)
+        }
+
+        #if DEBUG
+        static func resetCacheForTesting() {
+            shared.removeAll()
+        }
+        #endif
+    }
+
+    /// Lazily resolves or compiles the process-shared Metal compute pipelines (dolby-vision-fel.md §5.6).
+    private func ensurePipelines() -> SharedPipelines? {
+        // Under `lock` on every read: `pipelines` is written from whichever thread composes first, and a
+        // failed compile is cached by `SharedPipelines.Cache`, so a broken shader costs one compile, once.
+        lock.lock()
+        defer { lock.unlock() }
+        if let pipelines { return pipelines }
+        guard let p = try? SharedPipelines.getOrCreate(device: device) else { return nil }
+        self.pipelines = p
+        return p
+    }
+
+    #if DEBUG
+    var lumaPipelineForTesting: MTLComputePipelineState? {
+        ensurePipelines()?.lumaPipeline
+    }
+
+    var chromaPipelineForTesting: MTLComputePipelineState? {
+        ensurePipelines()?.chromaPipeline
+    }
+    #endif
+
+    init?() {
+        guard let dev = MTLCreateSystemDefaultDevice(),
+              let queue = dev.makeCommandQueue() else {
+            return nil
+        }
+        self.device = dev
+        self.commandQueue = queue
+        self.supportsNonUniformThreadgroups = dev.supportsFamily(.apple4) || dev.supportsFamily(.mac2)
+
+        var cache: CVMetalTextureCache?
+        guard CVMetalTextureCacheCreate(kCFAllocatorDefault, nil, dev, nil, &cache) == kCVReturnSuccess,
+              let createdCache = cache else {
+            return nil
+        }
+        self.textureCache = createdCache
+
+        var pBuffers: [MTLBuffer] = []
+        var lutBuffers: [MTLBuffer] = []
+        for _ in 0..<Self.maxFramesInFlight {
+            guard let buf = dev.makeBuffer(length: DoviMetalParams.serializedSize, options: .storageModeShared),
+                  let lut = dev.makeBuffer(length: 1024 * MemoryLayout<Float>.stride, options: .storageModeShared) else {
+                return nil
+            }
+            pBuffers.append(buf)
+            lutBuffers.append(lut)
+        }
+        self.paramBuffers = pBuffers
+        self.lumaLutBuffers = lutBuffers
+        self.freeParamSlotIndices = Array(0..<Self.maxFramesInFlight)
+    }
+
+    deinit {
+        if let cache = textureCache {
+            CVMetalTextureCacheFlush(cache, 0)
+        }
+    }
+
+    // MARK: - Pixel Buffer Pool Management
+
+    private func ensurePool(width: Int, height: Int) -> CVPixelBufferPool? {
+        lock.lock()
+        defer { lock.unlock() }
+
+        // Checked under the same lock `releaseOutputPool()` takes, so a teardown landing between a caller's
+        // earlier look and this point cannot leave a fresh pool behind that nothing will release.
+        guard !tornDown else { return nil }
+
+        if let pool = pixelBufferPool, poolWidth == width, poolHeight == height {
+            return pool
+        }
+
+        let poolAttributes: [CFString: Any] = [
+            kCVPixelBufferPoolMinimumBufferCountKey: 4,
+            kCVPixelBufferPoolMaximumBufferAgeKey: 1.0,
+            kCVPixelBufferPoolAllocationThresholdKey: DoviFelComposer.outputPoolAllocationThreshold
+        ]
+
+        let pixelBufferAttributes: [CFString: Any] = [
+            kCVPixelBufferPixelFormatTypeKey: kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+            kCVPixelBufferWidthKey: width,
+            kCVPixelBufferHeightKey: height,
+            kCVPixelBufferIOSurfacePropertiesKey: [:] as [String: Any],
+            kCVPixelBufferMetalCompatibilityKey: true
+        ]
+
+        var newPool: CVPixelBufferPool?
+        let status = CVPixelBufferPoolCreate(
+            kCFAllocatorDefault,
+            poolAttributes as CFDictionary,
+            pixelBufferAttributes as CFDictionary,
+            &newPool
+        )
+
+        guard status == kCVReturnSuccess, let pool = newPool else {
+            return nil
+        }
+
+        self.pixelBufferPool = pool
+        self.poolWidth = width
+        self.poolHeight = height
+        poolBuffers.removeAll()
+        poolBufferHighWaterMark = 0
+        return pool
+    }
+
+    private func recordPoolBuffer(_ buffer: CVPixelBuffer, pool: CVPixelBufferPool) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard pool === pixelBufferPool else { return }
+        poolBuffers.removeAll { $0.value == nil }
+        if !poolBuffers.contains(where: { $0.value === buffer }) {
+            poolBuffers.append(WeakPoolBuffer(buffer))
+        }
+        poolBufferHighWaterMark = max(poolBufferHighWaterMark, poolBuffers.count)
+    }
+
+    #if DEBUG
+    func ensurePoolForTesting(width: Int, height: Int) -> CVPixelBufferPool? {
+        ensurePool(width: width, height: height)
+    }
+
+    /// One allocation from the output pool: `reserve: false` stops at the threshold, `true` draws on the reserve
+    /// above it, as `encodeCompose` does once the threshold refuses.
+    func createOutputBufferForTesting(pool: CVPixelBufferPool, reserve: Bool = false) -> (status: CVReturn, buffer: CVPixelBuffer?) {
+        var buf: CVPixelBuffer?
+        let status = CVPixelBufferPoolCreatePixelBufferWithAuxAttributes(
+            kCFAllocatorDefault,
+            pool,
+            reserve ? Self.poolReserveAuxAttributes : Self.poolAuxAttributes,
+            &buf
+        )
+        if status == kCVReturnSuccess, let buf { recordPoolBuffer(buf, pool: pool) }
+        return (status, buf)
+    }
+    #endif
+
+    // MARK: - Texture Extraction
+
+    private func makeTexture(
+        from pixelBuffer: CVPixelBuffer,
+        plane: Int,
+        format: MTLPixelFormat,
+        width: Int,
+        height: Int,
+        keepAlive: inout [CVMetalTexture]
+    ) -> MTLTexture? {
+        guard let cache = textureCache else { return nil }
+        var cvTex: CVMetalTexture?
+        let status = CVMetalTextureCacheCreateTextureFromImage(
+            kCFAllocatorDefault,
+            cache,
+            pixelBuffer,
+            nil,
+            format,
+            width,
+            height,
+            plane,
+            &cvTex
+        )
+        guard status == kCVReturnSuccess, let validCvTex = cvTex else {
+            return nil
+        }
+        keepAlive.append(validCvTex)
+        return CVMetalTextureGetTexture(validCvTex)
+    }
+
+    // MARK: - Frame Composition
+
+    /// Reconstructs the VDR master from BL and EL pixel buffers, returning a
+    /// 10-bit video-range P010 CVPixelBuffer.
+    ///
+    /// Blocks the calling thread until the GPU is done. That is what an offline
+    /// caller wants — a probe, a unit test, `aetherctl` — but it is the wrong
+    /// shape for playback, where the wait lands on the decode thread and stops
+    /// decode(N+1) from overlapping GPU(N). Playback uses
+    /// ``composeAsync(baseBuffer:enhancementBuffer:params:frameIndex:completion:)``.
+    func compose(
+        baseBuffer: CVPixelBuffer,
+        enhancementBuffer: CVPixelBuffer,
+        params: DoviMetalParams,
+        frameIndex: UInt32 = 0
+    ) -> CVPixelBuffer? {
+        // Takes an in-flight slot like `composeAsync`, so a parameter slot is never taken outside the semaphore
+        // that bounds them. Only tests, `aetherctl` and probes call this; playback uses `composeAsync`.
+        acquireSlot()
+        defer { releaseInFlightSlot() }
+        guard let work = encodeCompose(baseBuffer: baseBuffer,
+                                       enhancementBuffer: enhancementBuffer,
+                                       params: params,
+                                       frameIndex: frameIndex) else {
+            return nil
+        }
+        defer { returnParamSlot(work.paramSlot) }
+        work.commandBuffer.commit()
+        work.commandBuffer.waitUntilCompleted()
+        if let failure = Self.commandBufferFailure(work.commandBuffer, forced: forcedCommandBufferFailure.withLock { $0 }) {
+            // The GPU did not finish writing the destination: it is not a frame, so no frame is returned.
+            EngineLog.emit("[DoviFelComposer] Command buffer error: \(failure)", category: .swPlayback)
+            return nil
+        }
+        _ = work.keepAlive
+        // Colour attachments are copied in `encodeCompose`, at encode time on
+        // this calling thread — nothing left to do here.
+        return work.destination
+    }
+
+    /// Test seam: makes every command buffer count as failed, so a test can drive the failure path without
+    /// a GPU fault. Read once per command buffer; a plain unfair lock, never held across anything.
+    let forcedCommandBufferFailure = OSAllocatedUnfairLock(initialState: false)
+
+    /// The command buffer's error, as text, or nil when it completed cleanly.
+    private static func commandBufferFailure(_ cb: MTLCommandBuffer, forced: Bool) -> String? {
+        forced ? "forced failure (test)" : cb.error?.localizedDescription
+    }
+
+    /// Same composition, without blocking the caller on the GPU.
+    ///
+    /// `completion` is invoked exactly once — off the calling thread once the
+    /// command buffer retires, or inline with nil if the frame could not be set
+    /// up at all. The GPU's writes are complete before it fires, so the buffer
+    /// it hands over is safe to enqueue for display.
+    ///
+    /// At most ``maxFramesInFlight`` compositions are outstanding on the GPU; a
+    /// caller that runs further ahead than that blocks here until one retires.
+    /// That is the backpressure that keeps the pixel buffer pool from growing
+    /// without bound, and it is deliberately the decode thread that absorbs it.
+    /// The slot is released when the command buffer retires rather than when
+    /// `completion` returns, so a slow consumer can leave at most
+    /// ``maxFramesInFlight`` further frames queued for delivery behind it. That
+    /// asymmetry is required, not incidental: releasing the slot from the
+    /// delivery side would put the signal behind the caller's own lock.
+    func composeAsync(
+        baseBuffer: CVPixelBuffer,
+        enhancementBuffer: CVPixelBuffer,
+        params: DoviMetalParams,
+        frameIndex: UInt32 = 0,
+        completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+    ) {
+        acquireSlot()
+        composeAsyncWithAcquiredSlot(
+            baseBuffer: baseBuffer,
+            enhancementBuffer: enhancementBuffer,
+            params: params,
+            frameIndex: frameIndex,
+            completion: completion
+        )
+    }
+
+    /// Blocks until one of ``maxFramesInFlight`` compositions is free.
+    ///
+    /// dolby-vision-fel.md §5.6: the decoder calls this with no lock held, on the
+    /// VideoToolbox output thread that produced the `compose` action, so the
+    /// backpressure lands on that thread instead of stalling `deliver`, the
+    /// other layer's callback, `flush()` and `close()` behind the decoder lock.
+    func acquireSlot() {
+        inFlight.wait()
+        slotLock.lock()
+        activeSlotsInUse += 1
+        if activeSlotsInUse > peakSlotsInUse {
+            peakSlotsInUse = activeSlotsInUse
+        }
+        slotLock.unlock()
+    }
+
+    /// Releases one in-flight slot. Only for callers that acquired with
+    /// ``acquireSlot()`` and then failed before reaching
+    /// ``composeAsyncWithAcquiredSlot(baseBuffer:enhancementBuffer:params:frameIndex:completion:)``.
+    func releaseSlot() {
+        releaseInFlightSlot()
+    }
+
+    private func releaseInFlightSlot() {
+        slotLock.lock()
+        if activeSlotsInUse > 0 {
+            activeSlotsInUse -= 1
+        }
+        slotLock.unlock()
+        inFlight.signal()
+    }
+
+    /// Reads and resets the peak slot count for the 1 Hz summary (dolby-vision-fel.md §5.11).
+    func takePeakSlotsInUse() -> Int {
+        slotLock.lock()
+        defer { slotLock.unlock() }
+        let peak = peakSlotsInUse
+        peakSlotsInUse = activeSlotsInUse
+        return peak
+    }
+
+    private func takeParamSlot() -> Int? {
+        slotLock.lock()
+        defer { slotLock.unlock() }
+        guard !freeParamSlotIndices.isEmpty else { return nil }
+        return freeParamSlotIndices.removeLast()
+    }
+
+    private func returnParamSlot(_ slot: Int) {
+        slotLock.lock()
+        freeParamSlotIndices.append(slot)
+        slotLock.unlock()
+    }
+
+    /// Same composition, assuming the caller already holds a slot from
+    /// ``acquireSlot()``. The slot is released when the command buffer retires
+    /// (or inline with `completion(nil)` when the frame cannot be set up).
+    func composeAsyncWithAcquiredSlot(
+        baseBuffer: CVPixelBuffer,
+        enhancementBuffer: CVPixelBuffer,
+        params: DoviMetalParams,
+        frameIndex: UInt32 = 0,
+        completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+    ) {
+        let signpostID = OSSignpostID(log: Self.signpostLog)
+        os_signpost(.begin, log: Self.signpostLog, name: "Compose", signpostID: signpostID,
+                    "frame=%{public}u", frameIndex)
+        guard let work = encodeCompose(baseBuffer: baseBuffer,
+                                       enhancementBuffer: enhancementBuffer,
+                                       params: params,
+                                       frameIndex: frameIndex) else {
+            os_signpost(.end, log: Self.signpostLog, name: "Compose", signpostID: signpostID, "encode-failed")
+            releaseInFlightSlot()
+            completion(nil)
+            return
+        }
+        // `textures` holds the CVMetalTextures; the source buffers are held
+        // alongside them because a CVMetalTexture is not documented to keep the
+        // pixel buffer it was made from alive, and the GPU reads both until the
+        // command buffer retires. Boxed because CoreVideo's types are not
+        // `Sendable` and this crosses two queues: CoreVideo buffers are
+        // themselves thread-safe, and only one queue touches the box at a time.
+        let frame = ComposedFrame(destination: work.destination,
+                                  source: baseBuffer,
+                                  enhancement: enhancementBuffer,
+                                  textures: work.keepAlive,
+                                  cache: textureCache)
+        // Captured as a value, not through `self?.`, before the handler below is
+        // even built: the whole point of `deliveryQueue` is that calling
+        // `completion` never depends on the composer still being alive, so there
+        // is no `self?.deliveryQueue ?? .global()`-shaped fallback to reach for
+        // if it were. `DispatchQueue` is a plain `Sendable`
+        // reference, so this costs nothing.
+        let deliveryQueue = self.deliveryQueue
+        let paramSlot = work.paramSlot
+        // Held strongly so it outlives a composer that is released mid-flight: libdispatch traps
+        // if a semaphore is destroyed below its initial count, and `self` is weak in the handler.
+        let inFlightSemaphore = self.inFlight
+        let forcedFailure = self.forcedCommandBufferFailure
+        work.commandBuffer.addCompletedHandler { [weak self] cb in
+            // Metal runs these handlers on ONE serial queue per command queue, so
+            // this block must never take a lock the caller above might be holding
+            // and must never block (dolby-vision-fel.md §4.3). The caller is inside
+            // `inFlight.wait()` while it holds the decoder's lock, and a `completion`
+            // that reached for that same lock would block here, which would
+            // stop every LATER handler from running, and one of those is the
+            // signal the caller is waiting for. Signalling first only defers that
+            // by a frame - it deadlocked on device after ~10s of playback.
+            //
+            // So: release the slot inline — nothing below this line can block —
+            // then hop to `deliveryQueue` for everything else, `completion`
+            // included, so Metal's shared queue never waits on it no matter what
+            // it does. In production `completion` is `DualLayerVideoDecoder.
+            // runCompose`'s closure, itself just a `queue.async` into
+            // `OrderedDelivery.fulfil`, so this hop is normally a hand-off from
+            // one non-blocking queue to another; `DoviComposeAsyncTests.
+            // doesNotDeadlockAgainstTheCallersLock` is what this hop exists for —
+            // it hands `composeAsync` a `completion` that deliberately blocks on
+            // a lock the caller holds, and only survives because that block runs
+            // off Metal's queue.
+            //
+            // This event marks the instant
+            // Metal actually invoked this handler — i.e. "GPU retired" —
+            // distinct from the "Compose" interval's `.end`, which only
+            // fires later, after the hop below has run. Without it, nothing
+            // in the signposts brackets the hand-off from Metal's queue to
+            // `deliveryQueue` on its own: Instruments could see "Compose"
+            // ran long but not whether that was GPU time or queueing delay
+            // hopping to the relay. It has to be the very first thing here,
+            // ahead of even `inFlight.signal()`, so it costs nothing on the
+            // must-never-block path (`os_signpost` does not block) and is
+            // not itself delayed by anything below it.
+            os_signpost(.event, log: Self.signpostLog, name: "Compose", signpostID: signpostID, "metal-completion-fired")
+            if let strongSelf = self {
+                strongSelf.returnParamSlot(paramSlot)
+                strongSelf.releaseInFlightSlot()
+            } else {
+                inFlightSemaphore.signal()
+            }
+            // Everything the hop needs pulled out of `cb` here, as plain
+            // Sendable values: `cb` itself is `any MTLCommandBuffer`, not
+            // Sendable, so it cannot cross into `deliveryQueue.async`'s
+            // closure directly, and `self` is captured once, strongly, into a
+            // fresh local rather than referenced from inside the nested
+            // closure (which is what the "captured var 'self' in
+            // concurrently-executing code" warning was about).
+            let errorDescription = Self.commandBufferFailure(cb, forced: forcedFailure.withLock { $0 })
+            let gpuMs = (cb.gpuEndTime - cb.gpuStartTime) * 1000
+            let composer = self
+            deliveryQueue.async {
+                if let errorDescription {
+                    EngineLog.emit("[DoviFelComposer] Command buffer error: \(errorDescription)", category: .swPlayback)
+                }
+                composer?.recordGPUTime(ms: gpuMs)
+                os_signpost(.end, log: Self.signpostLog, name: "Compose", signpostID: signpostID)
+                // A command buffer that errored leaves the destination partly written: deliver a failure,
+                // so the caller falls back to the base layer instead of showing garbage.
+                completion(errorDescription == nil ? frame.destination : nil)
+                frame.release()
+            }
+        }
+        work.commandBuffer.commit()
+    }
+
+    /// Compositions allowed to be outstanding at once. Sized against the pool's
+    /// `kCVPixelBufferPoolMinimumBufferCountKey` so a full pipeline still draws
+    /// from the preallocated set rather than growing the pool.
+    static let maxFramesInFlight = 3
+    /// Buffers the output pool allocates in normal running; past it `encodeCompose` draws on
+    /// `outputPoolReserve`, and only with that spent too does a frame bypass to the base layer
+    /// (dolby-vision-fel.md §5.6, §5.10).
+    ///
+    /// Derived from the renderer's look-ahead cap, not a second constant to keep in step: when decode
+    /// outruns the clock the gate holds the look-ahead at its limit, and the pool then holds that many
+    /// frames plus the one on screen, the one the display layer retains, and the compositions in flight.
+    ///
+    /// The margin is built from those holders: the one on screen, the one the layer retains,
+    /// `maxFramesInFlight` compositions, and one spare. A smaller margin let a burst of in-flight compositions
+    /// on top of a full look-ahead exhaust the pool (CoreVideo -6689) and fall back to the base layer.
+    /// A 4K P010 buffer is about 25 MB, so the threshold is about 375 MB.
+    private static let residualSwitch = OSAllocatedUnfairLock(initialState: true)
+
+    /// Whether the enhancement-layer residual (EL fetch + NLQ) is applied. Off, the composer still maps the
+    /// base layer through the RPU curves, which is what a minimal enhancement layer (MEL) stream decodes
+    /// to; on, it is the full FEL result. Exists for A/B viewing (`aetherctl play --cycle-el`); it takes
+    /// effect from the next composed frame and applies to every composer in the process. Default on.
+    static var residualEnabled: Bool {
+        get { residualSwitch.withLock { $0 } }
+        set { residualSwitch.withLock { $0 = newValue } }
+    }
+
+    static let outputPoolAllocationThreshold = SampleBufferRenderer.felVideoLookaheadFrames + 2 + maxFramesInFlight + 1
+    nonisolated(unsafe) private static let poolAuxAttributes: CFDictionary = [
+        kCVPixelBufferPoolAllocationThresholdKey: outputPoolAllocationThreshold
+    ] as CFDictionary
+    /// Buffers the pool may grow by when the threshold refuses one. A refused buffer means a base-layer
+    /// frame, a visible brightness step on real titles (`fallbackFrameDelta`); a burst composes into one of
+    /// these instead. They return to the pool like any other and `kCVPixelBufferPoolMaximumBufferAgeKey`
+    /// frees them after a second unused, so the extra memory (about 25 MB each at 4K) lasts only as long as the
+    /// burst. Sized like the in-flight limit, the holder a burst's shortfall came from on the titles measured.
+    static let outputPoolReserve = maxFramesInFlight
+    /// With the pool and its reserve both refused, the composer retries this many times, sleeping
+    /// `outputPoolRetryInterval` between attempts (never after the last): at most 9 x 4 ms, about 36 ms.
+    static let outputPoolAttempts = 10
+    static let outputPoolRetryInterval: TimeInterval = 0.004
+    nonisolated(unsafe) private static let poolReserveAuxAttributes: CFDictionary = [
+        kCVPixelBufferPoolAllocationThresholdKey: outputPoolAllocationThreshold + outputPoolReserve
+    ] as CFDictionary
+    private let inFlight = DispatchSemaphore(value: DoviFelComposer.maxFramesInFlight)
+    private let slotLock = NSLock()
+    private var activeSlotsInUse: Int = 0
+    private var peakSlotsInUse: Int = 0
+
+    /// Exists for exactly one reason (dolby-vision-fel.md §4.3): Metal runs every
+    /// `addCompletedHandler` block for a command queue on **one serial queue**,
+    /// so a `completion` closure that blocks — on a caller's lock, or on
+    /// anything else — would stall every later handler too, including the
+    /// `inFlight.signal()` a different, currently-blocked caller is waiting on.
+    /// `DoviComposeAsyncTests.doesNotDeadlockAgainstTheCallersLock` reproduces
+    /// that shape directly against `composeAsync`, independent of anything
+    /// `DualLayerVideoDecoder`/`OrderedDelivery` promise about their own
+    /// callback never blocking — this queue is what makes the composer safe
+    /// against a slow or badly-behaved `completion` on its own terms.
+    ///
+    /// This is not a second ordering mechanism: this queue carries no
+    /// ordering responsibility at all (`OrderedDelivery` reorders by ticket
+    /// regardless of which thread calls `fulfil`), it only gets `completion`
+    /// off Metal's queue. It runs at `qos: .userInteractive`, and it is
+    /// captured as a plain value below, never through `self?.`, so there is
+    /// no unordered `.global()` fallback to reach for.
+    private let deliveryQueue = DispatchQueue(label: "de.superuser404.dovi.compose-delivery", qos: .userInteractive)
+
+    /// One composition's CoreVideo objects, kept alive from encode until the
+    /// completion has run. `@unchecked Sendable` for the reason given at its
+    /// construction site in `composeAsync`.
+    private final class ComposedFrame: @unchecked Sendable {
+        let destination: CVPixelBuffer
+        private var source_: CVPixelBuffer?
+        private var enhancement_: CVPixelBuffer?
+        private var textures_: [CVMetalTexture]?
+        /// A `CVMetalTexture` calls back into its cache when it finalizes and does not
+        /// retain it, so the cache has to outlive the textures. Without this a composer
+        /// released while a command buffer was in flight crashed in
+        /// `CVMetalTextureCache::bufferBackingNotInUse`.
+        private var cache_: CVMetalTextureCache?
+
+        var source: CVPixelBuffer { source_! }
+
+        init(destination: CVPixelBuffer, source: CVPixelBuffer,
+             enhancement: CVPixelBuffer, textures: [CVMetalTexture],
+             cache: CVMetalTextureCache?) {
+            self.destination = destination
+            self.cache_ = cache
+            self.source_ = source
+            self.enhancement_ = enhancement
+            self.textures_ = textures
+        }
+
+        /// Drops the inputs once the consumer has the output. Explicit so the
+        /// lifetime is a statement rather than a `_ =` that a later edit can
+        /// delete without noticing what it was holding up.
+        func release() {
+            source_ = nil
+            enhancement_ = nil
+            textures_ = nil
+            cache_ = nil
+        }
+    }
+
+    private struct EncodedFrame {
+        let commandBuffer: MTLCommandBuffer
+        let destination: CVPixelBuffer
+        let keepAlive: [CVMetalTexture]
+        let paramSlot: Int
+    }
+
+    /// Everything up to (not including) `commit`: pool rental, texture binding,
+    /// parameter upload and the two dispatches.
+    private func encodeCompose(
+        baseBuffer: CVPixelBuffer,
+        enhancementBuffer: CVPixelBuffer,
+        params: DoviMetalParams,
+        frameIndex: UInt32
+    ) -> EncodedFrame? {
+        let blW = CVPixelBufferGetWidth(baseBuffer)
+        let blH = CVPixelBufferGetHeight(baseBuffer)
+        let elW = CVPixelBufferGetWidth(enhancementBuffer)
+        let elH = CVPixelBufferGetHeight(enhancementBuffer)
+
+        guard blW > 0, blH > 0, elW > 0, elH > 0 else { return nil }
+        guard let pool = ensurePool(width: blW, height: blH) else { return nil }
+
+        // A base-layer frame is NOT close to the composed one on real titles: measured on the three
+        // real FEL files its 10-bit luma differs by a mean of ~8 codes (p99 up to 230) on two and ~79
+        // on clip C (`fallbackFrameDelta`), a visible brightness step. So when the threshold
+        // refuses, take a buffer from the reserve above it rather than wait. Only with the reserve
+        // spent too, wait briefly, but never long: on device a 300 ms wait stalled the
+        // VideoToolbox callback, then the demux loop, starving audio into 7 rebuffers in a minute.
+        var outBuffer: CVPixelBuffer?
+        var poolStatus = kCVReturnError
+        for attempt in 0..<Self.outputPoolAttempts {
+            for aux in [Self.poolAuxAttributes, Self.poolReserveAuxAttributes] {
+                poolStatus = CVPixelBufferPoolCreatePixelBufferWithAuxAttributes(kCFAllocatorDefault, pool, aux, &outBuffer)
+                if poolStatus != kCVReturnWouldExceedAllocationThreshold { break }
+            }
+            if poolStatus != kCVReturnWouldExceedAllocationThreshold { break }
+            if attempt < Self.outputPoolAttempts - 1 { Thread.sleep(forTimeInterval: Self.outputPoolRetryInterval) }
+        }
+        guard poolStatus == kCVReturnSuccess, let dst = outBuffer else {
+            EngineLog.emit("[DoviFelComposer] output pool refused a buffer (status \(poolStatus)); frame falls back to the base layer", category: .swPlayback, level: .verbose)
+            return nil
+        }
+
+        recordPoolBuffer(dst, pool: pool)
+
+        // Colour attachments are metadata, not pixels: copying them now, on
+        // this calling thread, rather than from Metal's completion handler
+        // (dolby-vision-fel.md §5.6) is safe because `dst` is not handed to anyone
+        // until the command buffer this function's caller commits has
+        // retired — nothing reads `dst` early just because its attachments
+        // are set before the GPU has written its pixels.
+        propagateColorAttachments(from: baseBuffer, to: dst)
+
+        var keepAliveTextures: [CVMetalTexture] = []
+
+        // Plane 0 is luma, plane 1 is interleaved chroma. The integer planes are
+        // bound as Uint so the kernels see raw code values; the enhancement layer
+        // is bound as Unorm because it is upsampled by the hardware bilinear sampler.
+        guard let blYTex = makeTexture(from: baseBuffer, plane: 0, format: .r16Uint, width: blW, height: blH, keepAlive: &keepAliveTextures),
+              let blUvTex = makeTexture(from: baseBuffer, plane: 1, format: .rg16Uint, width: blW / 2, height: blH / 2, keepAlive: &keepAliveTextures),
+              let elYTex = makeTexture(from: enhancementBuffer, plane: 0, format: .r16Unorm, width: elW, height: elH, keepAlive: &keepAliveTextures),
+              let elUvTex = makeTexture(from: enhancementBuffer, plane: 1, format: .rg16Unorm, width: elW / 2, height: elH / 2, keepAlive: &keepAliveTextures),
+              let outYTex = makeTexture(from: dst, plane: 0, format: .r16Uint, width: blW, height: blH, keepAlive: &keepAliveTextures),
+              let outUvTex = makeTexture(from: dst, plane: 1, format: .rg16Uint, width: blW / 2, height: blH / 2, keepAlive: &keepAliveTextures) else {
+            return nil
+        }
+
+        var metalParams = params
+        metalParams.blWidth = UInt32(blW)
+        metalParams.blHeight = UInt32(blH)
+        metalParams.elWidth = UInt32(elW)
+        metalParams.elHeight = UInt32(elH)
+        metalParams.frameIndex = frameIndex
+        metalParams.polyY.clampToCapacity()
+        metalParams.polyCb.clampToCapacity()
+        metalParams.polyCr.clampToCapacity()
+
+        guard let pipelines = ensurePipelines() else { return nil }
+
+        guard let paramSlot = takeParamSlot() else { return nil }
+        let paramBuffer = paramBuffers[paramSlot]
+        let rawBuffer = UnsafeMutableRawBufferPointer(start: paramBuffer.contents(), count: DoviMetalParams.serializedSize)
+        var serialized = metalParams
+        if !Self.residualEnabled { serialized.flags.insert(.disableResidual) }
+        serialized.serialize(into: rawBuffer)
+
+        let lutBuffer = lumaLutBuffers[paramSlot]
+        populateLumaLut(into: lutBuffer.contents().assumingMemoryBound(to: Float.self), params: metalParams)
+
+        guard let commandBuffer = commandQueue.makeCommandBuffer() else {
+            returnParamSlot(paramSlot)
+            return nil
+        }
+
+        // Both passes go in one concurrent encoder. Luma reads BL luma + BL
+        // chroma (a luma MMR curve would need it) and the EL luma; chroma reads
+        // BL luma + BL chroma and the EL chroma. Neither reads what the other
+        // writes — `outYTex` and `outUvTex` are separate planes — so the barrier
+        // Metal puts between two serial encoders buys nothing and costs a full
+        // GPU sync point per frame.
+        guard let encoder = commandBuffer.makeComputeCommandEncoder(dispatchType: .concurrent) else {
+            returnParamSlot(paramSlot)
+            return nil
+        }
+
+        encoder.setComputePipelineState(pipelines.lumaPipeline)
+        encoder.setTexture(blYTex, index: 0)
+        encoder.setTexture(blUvTex, index: 1)
+        encoder.setTexture(elYTex, index: 2)
+        encoder.setTexture(outYTex, index: 3)
+        encoder.setBuffer(paramBuffer, offset: 0, index: 0)
+        encoder.setBuffer(lutBuffer, offset: 0, index: 1)
+        dispatch(encoder, width: blW, height: blH,
+                 threadgroup: threadgroupSize(for: pipelines.lumaPipeline))
+
+        encoder.setComputePipelineState(pipelines.chromaPipeline)
+        encoder.setTexture(blYTex, index: 0)
+        encoder.setTexture(blUvTex, index: 1)
+        encoder.setTexture(elUvTex, index: 2)
+        encoder.setTexture(outUvTex, index: 3)
+        encoder.setBuffer(paramBuffer, offset: 0, index: 0)
+        dispatch(encoder, width: blW / 2, height: blH / 2,
+                 threadgroup: threadgroupSize(for: pipelines.chromaPipeline))
+
+        encoder.endEncoding()
+
+        return EncodedFrame(commandBuffer: commandBuffer, destination: dst, keepAlive: keepAliveTextures, paramSlot: paramSlot)
+    }
+
+    /// Precomputes the 1024-entry luma prediction table when luma is polynomial (dolby-vision-fel.md §5.6).
+    private func populateLumaLut(into ptr: UnsafeMutablePointer<Float>, params: DoviMetalParams) {
+        let poly = params.polyY
+        let blMax = Float(params.blMax) + 1   // normalise by 2^bits, as the kernels do
+        guard poly.numPivots >= 2 else {
+            for code in 0..<1024 {
+                ptr[code] = Float(code) / blMax
+            }
+            return
+        }
+
+        let numPivots = Int(poly.numPivots)
+        let lastPiece = numPivots - 2
+        let lo = Int(poly.pivots[0])
+        let hi = Int(poly.pivots[numPivots - 1])
+
+        for code in 0..<1024 {
+            var piece = 0
+            for i in 0...lastPiece {
+                if code >= Int(poly.pivots[i]) {
+                    piece = i
+                }
+            }
+            let p = max(0, min(piece, lastPiece))
+            let method = (p < DoviPolynomialParams.maxPieces && p < poly.method.count) ? poly.method[p] : DoviMapping.polynomial.rawValue
+            if method != DoviMapping.polynomial.rawValue {
+                ptr[code] = Float(code) / blMax
+                continue
+            }
+
+            let clamped = min(max(code, lo), hi)
+            let x = Float(clamped) / blMax
+            let shift = (p < poly.coefShift.count) ? Int32(poly.coefShift[p]) : 0
+            let inv = ldexpf(1.0, -shift)
+            let coefs = (p < poly.coef.count) ? poly.coef[p] : [0, 0, 0]
+            let c0 = (coefs.count > 0) ? Float(coefs[0]) : 0
+            let c1 = (coefs.count > 1) ? Float(coefs[1]) : 0
+            let c2 = (coefs.count > 2) ? Float(coefs[2]) : 0
+
+            var pred = c0 * inv
+            let order = (p < poly.order.count) ? poly.order[p] : 0
+            if order >= 1 {
+                pred = fmaf(c1 * inv, x, pred)
+            }
+            if order >= 2 {
+                pred = fmaf(c2 * inv, x * x, pred)
+            }
+            ptr[code] = pred
+        }
+    }
+
+    /// Sizes threadgroups using the pipeline's execution width (dolby-vision-fel.md §5.6).
+    private func threadgroupSize(for pipeline: MTLComputePipelineState) -> MTLSize {
+        let w = pipeline.threadExecutionWidth
+        let maxThreads = pipeline.maxTotalThreadsPerThreadgroup
+        if w >= 32 {
+            let h = max(1, min(maxThreads / w, 8))
+            return MTLSize(width: w, height: h, depth: 1)
+        } else {
+            return MTLSize(width: 16, height: 16, depth: 1)
+        }
+    }
+
+    private func propagateColorAttachments(from baseBuffer: CVPixelBuffer, to dst: CVPixelBuffer) {
+        CVBufferPropagateAttachments(baseBuffer, dst)
+    }
+
+    // MARK: - GPU Timing
+
+    /// Mean GPU time per composition over the last `gpuTimeWindow` frames, in
+    /// milliseconds, or nil before the first window closes.
+    ///
+    /// The wall-clock cost of a frame is GPU time plus texture binding, pool
+    /// rental and encode; only this separates them, which is what says whether
+    /// the shaders need work or the CPU side does.
+    var meanGPUTimeMs: Double? {
+        gpuTimeLock.lock(); defer { gpuTimeLock.unlock() }
+        if let gpuTimeMean { return gpuTimeMean }
+        if gpuTimeCount > 0 { return gpuTimeAccum / Double(gpuTimeCount) }
+        return nil
+    }
+
+    private static let gpuTimeWindow = 120
+    private let gpuTimeLock = NSLock()
+    private var gpuTimeAccum: Double = 0
+    private var gpuTimeCount: Int = 0
+    private var gpuTimeMean: Double?
+
+    private func recordGPUTime(ms: Double) {
+        guard ms.isFinite, ms >= 0 else { return }
+        gpuTimeLock.lock()
+        gpuTimeAccum += ms
+        gpuTimeCount += 1
+        var closed: Double?
+        if gpuTimeCount >= Self.gpuTimeWindow {
+            closed = gpuTimeAccum / Double(gpuTimeCount)
+            gpuTimeMean = closed
+            gpuTimeAccum = 0
+            gpuTimeCount = 0
+        }
+        gpuTimeLock.unlock()
+        if let closed {
+            EngineLog.emit(String(format: "[DoviFelComposer] gpu %.1fms/frame over %d frames",
+                                  closed, Self.gpuTimeWindow), category: .swPlayback)
+        }
+    }
+
+    // MARK: - Flush & Invalidation
+
+    /// Flushes the texture cache, releasing cached IOSurface-backed Metal textures (dolby-vision-fel.md §5.6).
+    func flushTextureCache() {
+        lock.lock()
+        defer { lock.unlock() }
+        if let cache = textureCache {
+            CVMetalTextureCacheFlush(cache, 0)
+        }
+    }
+
+    /// Seek/flush: keeps the output pool. Dropping it here made the next frames allocate a second pool while
+    /// the renderer still held the old one's buffers (the displayed image and the look-ahead the display layer
+    /// had not yet let go of), so the footprint doubled for the half second a seek took to settle (about
+    /// +260 MB at 4K, where the pool holds up to 15 buffers of 25 MB). The same pool is capped by the allocation threshold,
+    /// so the old buffers return to it as the renderer releases them and the new frames reuse them. Idle
+    /// buffers beyond the minimum are released at once.
+    func flush() {
+        lock.lock()
+        defer { lock.unlock() }
+        if let cache = textureCache {
+            CVMetalTextureCacheFlush(cache, 0)
+        }
+        if let pool = pixelBufferPool {
+            CVPixelBufferPoolFlush(pool, .excessBuffers)
+        }
+    }
+
+    /// Teardown: drops the pool so its idle buffers go with it, and marks the composer as torn down: every
+    /// later composition is refused (`compose` returns nil, `composeAsync` completes with nil and gives its
+    /// slot back), so no pool is rebuilt after this. One composer serves one decoder, which is closed once.
+    func releaseOutputPool() {
+        lock.lock()
+        defer { lock.unlock() }
+        tornDown = true
+        pixelBufferPool = nil
+        poolBuffers.removeAll()
+        poolBufferHighWaterMark = 0
+        poolWidth = 0
+        poolHeight = 0
+    }
+
+    // MARK: - ABI Layout Probe
+
+    /// Uploads `params` exactly the way ``compose(baseBuffer:enhancementBuffer:params:frameIndex:)``
+    /// does and returns the sentinels `dovi_layout_probe` reads back out of it.
+    ///
+    /// Metal has no `static_assert` and the offline `metal` compiler is not always
+    /// installed, so this is how the shader's view of the parameter block gets
+    /// checked against ``DoviMetalParams/serialize()`` rather than by hand.
+    /// Returns nil when the probe kernel is unavailable.
+    func probeLayout(params: DoviMetalParams) -> [UInt32]? {
+        guard let pipelines = ensurePipelines(), let pipeline = pipelines.layoutProbePipeline else { return nil }
+
+        let slots = Self.layoutProbeSlots
+        guard let outBuffer = device.makeBuffer(length: slots * 4, options: .storageModeShared) else {
+            return nil
+        }
+        memset(outBuffer.contents(), 0, slots * 4)
+
+        guard let commandBuffer = commandQueue.makeCommandBuffer(),
+              let encoder = commandBuffer.makeComputeCommandEncoder() else {
+            return nil
+        }
+        encoder.setComputePipelineState(pipeline)
+        let paramData = params.serialize()
+        paramData.withUnsafeBytes { raw in
+            if let ptr = raw.baseAddress {
+                encoder.setBytes(ptr, length: raw.count, index: 0)
+            }
+        }
+        encoder.setBuffer(outBuffer, offset: 0, index: 1)
+        dispatch(encoder, width: 1, height: 1,
+                 threadgroup: MTLSize(width: 1, height: 1, depth: 1))
+        encoder.endEncoding()
+        commandBuffer.commit()
+        commandBuffer.waitUntilCompleted()
+        guard commandBuffer.error == nil else { return nil }
+
+        let ptr = outBuffer.contents().bindMemory(to: UInt32.self, capacity: slots)
+        return Array(UnsafeBufferPointer(start: ptr, count: slots))
+    }
+
+    /// Covers exactly `width` x `height` threads.
+    ///
+    /// `dispatchThreads` takes the thread count and splits the edge threadgroups
+    /// itself, so the grid is the plane. Rounding the grid up to a multiple of the
+    /// threadgroup is the `dispatchThreadgroups` convention, and that is the path
+    /// taken where non-uniform threadgroups are unavailable: there the extra
+    /// threads are real and the kernels' `gid >= bl_width` guard is what discards
+    /// them.
+    private func dispatch(
+        _ encoder: MTLComputeCommandEncoder,
+        width: Int,
+        height: Int,
+        threadgroup: MTLSize
+    ) {
+        guard width > 0, height > 0 else { return }
+        if supportsNonUniformThreadgroups {
+            encoder.dispatchThreads(
+                MTLSize(width: width, height: height, depth: 1),
+                threadsPerThreadgroup: threadgroup
+            )
+        } else {
+            encoder.dispatchThreadgroups(
+                MTLSize(
+                    width: (width + threadgroup.width - 1) / threadgroup.width,
+                    height: (height + threadgroup.height - 1) / threadgroup.height,
+                    depth: 1
+                ),
+                threadsPerThreadgroup: threadgroup
+            )
+        }
+    }
+
+    // MARK: - RPU Parsing via libdovi
+
+    /// Whether the base and enhancement layers are the 10-bit codes the kernels assume. The kernels read and
+    /// write 10-in-16 P010 planes, so a base layer of any other depth would need different texture formats, not
+    /// just a new divisor; the enhancement layer is bound as a 10-in-16 plane and the NLQ constants assume a
+    /// 10-bit code, so an EL of any other depth would be read at the wrong scale. libdovi 3.4 already rejects
+    /// both at parse time, which is why this is separate from the parse and tested directly: the check keeps the
+    /// composer safe if a later libdovi stops enforcing it.
+    static func layerBitDepthsSupported(bl: Int, el: Int) -> Bool {
+        guard bl == 10 else {
+            logOnce("[DoviFelComposer] bl_bit_depth \(bl) unsupported; refusing to compose", category: .swPlayback)
+            return false
+        }
+        guard el == 10 else {
+            logOnce("[DoviFelComposer] el_bit_depth \(el) unsupported; refusing to compose", category: .swPlayback)
+            return false
+        }
+        return true
+    }
+
+    /// Parses an unspec62 RPU NAL into composer parameters.
+    ///
+    /// Returns nil when the RPU cannot be trusted at all (no header, a
+    /// coefficient encoding the kernels do not implement, a bit depth they cannot
+    /// address), so the caller presents the base layer rather than a guess. A
+    /// single unusable component instead degrades to an identity curve for that
+    /// component, which is visually the base layer for that channel and never
+    /// flat mid-grey.
+    static func parseRpuParameters(rpu: OpaquePointer) -> DoviMetalParams? {
+        _parseRpuCount += 1
+
+        if let err = dovi_rpu_get_error(rpu) {
+            logOnce("[DoviFelComposer] libdovi error: \(String(cString: err))", category: .swPlayback)
+        }
+
+        guard let mapping = dovi_rpu_get_data_mapping(rpu) else {
+            logOnce("[DoviFelComposer] dovi_rpu_get_data_mapping returned nil", category: .swPlayback)
+            return nil
+        }
+        defer { dovi_rpu_free_data_mapping(mapping) }
+
+        guard let header = dovi_rpu_get_header(rpu) else {
+            logOnce("[DoviFelComposer] dovi_rpu_get_header returned nil; refusing to guess bit depths", category: .swPlayback)
+            return nil
+        }
+        defer { dovi_rpu_free_header(header) }
+
+        var params = DoviMetalParams()
+
+        // coefficient_data_type selects fixed point (0) or 32-bit float (1). Every
+        // coefficient below is decoded as (int << denom) + frac, which is only the
+        // fixed-point reading, so refuse the float form instead of misreading it.
+        let coefDataType = header.pointee.coefficient_data_type
+        guard coefDataType == 0 else {
+            logOnce("[DoviFelComposer] coefficient_data_type \(coefDataType) is not fixed point; refusing to compose", category: .swPlayback)
+            return nil
+        }
+
+        let coefLog2DenomRaw = header.pointee.coefficient_log2_denom
+        guard coefLog2DenomRaw <= UInt64(maxCoefLog2Denom) else {
+            logOnce("[DoviFelComposer] coefficient_log2_denom \(coefLog2DenomRaw) out of range; refusing to compose", category: .swPlayback)
+            return nil
+        }
+        let coefLog2Denom = Int(coefLog2DenomRaw)
+
+        let blBitDepth = Int(header.pointee.bl_bit_depth_minus8) + 8
+        let vdrBitDepth = Int(header.pointee.vdr_bit_depth_minus8) + 8
+        let elBitDepth = Int(header.pointee.el_bit_depth_minus8) + 8
+        guard layerBitDepthsSupported(bl: blBitDepth, el: elBitDepth) else { return nil }
+        guard params.setBitDepths(bl: blBitDepth, vdr: vdrBitDepth) else {
+            logOnce("[DoviFelComposer] bit depth pair bl=\(blBitDepth) vdr=\(vdrBitDepth) unsupported; refusing to compose", category: .swPlayback)
+            return nil
+        }
+
+        if header.pointee.disable_residual_flag {
+            params.flags.insert(.disableResidual)
+        }
+        if let elType = header.pointee.el_type, strcmp(elType, "MEL") == 0 {
+            // MEL carries no residual by construction: the enhancement layer is a
+            // constant mid-grey and only the RPU matters.
+            params.flags.insert(.disableResidual)
+        }
+
+        // The inverse NLQ product is Q(coefficient_log2_denom) of a normalised
+        // residual; this shift brings it into VDR code units. A denominator below
+        // the VDR depth would make the shift negative and the whole derivation
+        // meaningless, so that disables the residual rather than shifting the
+        // other way.
+        let nlqShift = UInt32(max(0, coefLog2Denom - vdrBitDepth))
+        let nlqMethodIdc = mapping.pointee.nlq_method_idc
+        var nlqMethod: DoviNlqMethod = .none
+        if coefLog2Denom < vdrBitDepth {
+            logOnce("[DoviFelComposer] coefficient_log2_denom \(coefLog2Denom) below vdr_bit_depth \(vdrBitDepth); dropping residual", category: .swPlayback)
+        } else if nlqMethodIdc == 0 {
+            nlqMethod = .linear
+        } else if nlqMethodIdc > 0 {
+            logOnce("[DoviFelComposer] nlq_method_idc \(nlqMethodIdc) not implemented; dropping residual", category: .swPlayback)
+        }
+
+        // Predicted NLQ pivots are delta-coded like the reshaping pivots.
+        var nlqPivots: [UInt32] = [0, params.blMax]
+        if mapping.pointee.nlq_pred_pivot_value.len >= 2,
+           let pivotData = mapping.pointee.nlq_pred_pivot_value.data {
+            let p0 = UInt32(pivotData[0])
+            let p1 = p0 + UInt32(pivotData[1])
+            nlqPivots = [p0, p1]
+        }
+
+        let curves = [mapping.pointee.curves.0, mapping.pointee.curves.1, mapping.pointee.curves.2]
+        let labels = ["Y", "Cb", "Cr"]
+
+        for c in 0..<3 {
+            var poly = DoviPolynomialParams()
+            var mmr = DoviMmrParams()
+            if !parseReshapingCurve(
+                curves[c],
+                coefLog2Denom: coefLog2Denom,
+                blMax: params.blMax,
+                polyOut: &poly,
+                mmrOut: &mmr
+            ) {
+                // Identity for this component: the base layer passes through
+                // unreshaped, which is wrong but recognisable, where a partially
+                // filled curve would put a flat value across the plane.
+                logOnce("[DoviFelComposer] \(labels[c]) reshaping curve rejected; falling back to identity", category: .swPlayback)
+                poly = .identity
+                mmr = DoviMmrParams()
+            }
+
+            let nlq = parseNlqParams(
+                nlq: mapping.pointee.nlq,
+                component: c,
+                label: labels[c],
+                method: nlqMethod,
+                coefLog2Denom: coefLog2Denom,
+                nlqShift: nlqShift,
+                pivots: nlqPivots
+            )
+
+            switch c {
+            case 0:
+                params.polyY = poly
+                params.mmrY = mmr
+                params.nlqY = nlq
+            case 1:
+                params.polyCb = poly
+                params.mmrCb = mmr
+                params.nlqCb = nlq
+            default:
+                params.polyCr = poly
+                params.mmrCr = mmr
+                params.nlqCr = nlq
+            }
+        }
+
+        if params.polyY.usesMmr {
+            // Tells the luma kernel to fetch the base-layer chroma planes it
+            // otherwise skips. No observed profile 7 stream does this (libdovi would
+            // report mapping_idc = 1 for component 0), so it is worth a log.
+            logOnce("[DoviFelComposer] luma curve uses MMR; enabling cross-component luma path", category: .swPlayback)
+            params.flags.insert(.lumaMmr)
+        }
+
+        return params
+    }
+
+    /// Combines an RPU coefficient's signed integer part and unsigned fraction
+    /// into one Q(denom) value, the way FFmpeg's `get_se_coef` does.
+    ///
+    /// Returns nil rather than saturating: a value that does not fit is a misparse
+    /// or an unsupported stream, and clamping it would quietly install a curve
+    /// that is wrong in a way nothing downstream can detect.
+    private static func fixedPoint(int intPart: Int64, frac: UInt64, denom: Int) -> Int32? {
+        guard let wide = fixedPointWide(int: intPart, frac: frac, denom: denom) else { return nil }
+        guard wide >= Int64(Int32.min), wide <= Int64(Int32.max) else { return nil }
+        return Int32(wide)
+    }
+
+    /// As ``fixedPoint(int:frac:denom:)`` but keeps the full 64-bit result, for
+    /// values that are shifted down again before they have to fit in 32 bits.
+    private static func fixedPointWide(int intPart: Int64, frac: UInt64, denom: Int) -> Int64? {
+        guard denom >= 0, denom <= maxCoefLog2Denom else { return nil }
+        let scale = Int64(1) << Int64(denom)
+        guard frac < UInt64(scale) else { return nil }
+        let (shifted, shiftOverflow) = intPart.multipliedReportingOverflow(by: scale)
+        guard !shiftOverflow else { return nil }
+        let (sum, addOverflow) = shifted.addingReportingOverflow(Int64(frac))
+        guard !addOverflow else { return nil }
+        return sum
+    }
+
+    /// Fills `polyOut` (and `mmrOut` for MMR pieces) from one component's
+    /// reshaping curve. Returns false if anything about the curve is inconsistent,
+    /// leaving the outputs partially written for the caller to discard.
+    private static func parseReshapingCurve(
+        _ curve: DoviReshapingCurve,
+        coefLog2Denom: Int,
+        blMax: UInt32,
+        polyOut: inout DoviPolynomialParams,
+        mmrOut: inout DoviMmrParams
+    ) -> Bool {
+        let numPivots = Int(curve.num_pivots_minus2) + 2
+        guard numPivots >= 2, numPivots <= DoviPolynomialParams.maxPivots else { return false }
+        guard let pivotsData = curve.pivots.data, curve.pivots.len >= numPivots else { return false }
+
+        // Pivots are delta-coded; prefix-sum them into absolute BL code values.
+        var running: UInt64 = 0
+        for i in 0..<numPivots {
+            running += UInt64(pivotsData[i])
+            guard running <= UInt64(blMax) else { return false }
+            polyOut.pivots[i] = UInt32(running)
+        }
+        guard polyOut.pivots[numPivots - 1] > polyOut.pivots[0] else { return false }
+        polyOut.numPivots = UInt32(numPivots)
+
+        let pieces = numPivots - 1
+        guard pieces >= 1, pieces <= DoviPolynomialParams.maxPieces else { return false }
+
+        switch curve.mapping_idc {
+        case 0:
+            guard let poly = curve.polynomial else { return false }
+            guard let orderData = poly.pointee.poly_order_minus1.data,
+                  poly.pointee.poly_order_minus1.len >= pieces else { return false }
+            guard let intPieces = poly.pointee.poly_coef_int.list,
+                  poly.pointee.poly_coef_int.len >= pieces,
+                  let fracPieces = poly.pointee.poly_coef.list,
+                  poly.pointee.poly_coef.len >= pieces else { return false }
+
+            for p in 0..<pieces {
+                let order = Int(orderData[p]) + 1
+                // The syntax allows linear and quadratic pieces only.
+                guard order >= 1, order <= 2 else { return false }
+                polyOut.method[p] = DoviMapping.polynomial.rawValue
+                polyOut.order[p] = UInt32(order)
+                polyOut.coefShift[p] = UInt32(coefLog2Denom)
+
+                guard let intData = intPieces[p]?.pointee, let intValues = intData.data,
+                      let fracData = fracPieces[p]?.pointee, let fracValues = fracData.data else { return false }
+                let count = order + 1
+                guard intData.len >= count, fracData.len >= count else { return false }
+                for j in 0..<count {
+                    guard let coef = fixedPoint(int: intValues[j], frac: fracValues[j], denom: coefLog2Denom) else {
+                        return false
+                    }
+                    polyOut.coef[p][j] = coef
+                }
+            }
+            return true
+
+        case 1:
+            guard let mmr = curve.mmr else { return false }
+            guard let orderData = mmr.pointee.mmr_order_minus1.data,
+                  mmr.pointee.mmr_order_minus1.len >= pieces else { return false }
+            guard let constInt = mmr.pointee.mmr_constant_int.data,
+                  mmr.pointee.mmr_constant_int.len >= pieces,
+                  let constFrac = mmr.pointee.mmr_constant.data,
+                  mmr.pointee.mmr_constant.len >= pieces else { return false }
+            guard let intPieces = mmr.pointee.mmr_coef_int.list,
+                  mmr.pointee.mmr_coef_int.len >= pieces,
+                  let fracPieces = mmr.pointee.mmr_coef.list,
+                  mmr.pointee.mmr_coef.len >= pieces else { return false }
+
+            for p in 0..<pieces {
+                let order = Int(orderData[p]) + 1
+                guard order >= 1, order <= 3 else { return false }
+                polyOut.method[p] = DoviMapping.mmr.rawValue
+                polyOut.order[p] = UInt32(order)
+
+                guard let constant = fixedPoint(int: constInt[p], frac: constFrac[p], denom: coefLog2Denom) else {
+                    return false
+                }
+                mmrOut.constant[p] = constant
+
+                guard let intOrders = intPieces[p]?.pointee, let intOrderList = intOrders.list,
+                      let fracOrders = fracPieces[p]?.pointee, let fracOrderList = fracOrders.list,
+                      intOrders.len >= order, fracOrders.len >= order else { return false }
+
+                for o in 0..<order {
+                    guard let intTerms = intOrderList[o]?.pointee, let intValues = intTerms.data,
+                          let fracTerms = fracOrderList[o]?.pointee, let fracValues = fracTerms.data,
+                          intTerms.len >= 7, fracTerms.len >= 7 else { return false }
+                    for k in 0..<7 {
+                        guard let coef = fixedPoint(int: intValues[k], frac: fracValues[k], denom: coefLog2Denom) else {
+                            return false
+                        }
+                        mmrOut.coef[p][o * 7 + k] = coef
+                    }
+                }
+            }
+            mmrOut.coefShift = UInt32(coefLog2Denom)
+            return true
+
+        default:
+            return false
+        }
+    }
+
+    /// Reads one component's inverse-NLQ parameters. Any value that does not fit
+    /// the fixed-point ABI disables the residual for that component instead of
+    /// being clamped, while keeping the decoded shift and pivots so a probe can
+    /// still report what the RPU said.
+    private static func parseNlqParams(
+        nlq: UnsafePointer<DoviRpuDataNlq>?,
+        component c: Int,
+        label: String,
+        method: DoviNlqMethod,
+        coefLog2Denom: Int,
+        nlqShift: UInt32,
+        pivots: [UInt32]
+    ) -> DoviNlqParams {
+        var disabled = DoviNlqParams.disabled
+        disabled.nlqPivots = pivots
+        disabled.nlqShift = nlqShift
+
+        guard method == .linear, let nlq = nlq else { return disabled }
+
+        let offset: UInt16
+        let slopeInt: UInt64
+        let slopeFrac: UInt64
+        let thrInt: UInt64
+        let thrFrac: UInt64
+        let maxInt: UInt64
+        let maxFrac: UInt64
+
+        switch c {
+        case 0:
+            offset = nlq.pointee.nlq_offset.0
+            slopeInt = nlq.pointee.linear_deadzone_slope_int.0
+            slopeFrac = nlq.pointee.linear_deadzone_slope.0
+            thrInt = nlq.pointee.linear_deadzone_threshold_int.0
+            thrFrac = nlq.pointee.linear_deadzone_threshold.0
+            maxInt = nlq.pointee.vdr_in_max_int.0
+            maxFrac = nlq.pointee.vdr_in_max.0
+        case 1:
+            offset = nlq.pointee.nlq_offset.1
+            slopeInt = nlq.pointee.linear_deadzone_slope_int.1
+            slopeFrac = nlq.pointee.linear_deadzone_slope.1
+            thrInt = nlq.pointee.linear_deadzone_threshold_int.1
+            thrFrac = nlq.pointee.linear_deadzone_threshold.1
+            maxInt = nlq.pointee.vdr_in_max_int.1
+            maxFrac = nlq.pointee.vdr_in_max.1
+        default:
+            offset = nlq.pointee.nlq_offset.2
+            slopeInt = nlq.pointee.linear_deadzone_slope_int.2
+            slopeFrac = nlq.pointee.linear_deadzone_slope.2
+            thrInt = nlq.pointee.linear_deadzone_threshold_int.2
+            thrFrac = nlq.pointee.linear_deadzone_threshold.2
+            maxInt = nlq.pointee.vdr_in_max_int.2
+            maxFrac = nlq.pointee.vdr_in_max.2
+        }
+
+        guard let slopeIntSigned = Int64(exactly: slopeInt),
+              let thrIntSigned = Int64(exactly: thrInt),
+              let maxIntSigned = Int64(exactly: maxInt),
+              let scale = fixedPoint(int: slopeIntSigned, frac: slopeFrac, denom: coefLog2Denom),
+              let threshold = fixedPoint(int: thrIntSigned, frac: thrFrac, denom: coefLog2Denom),
+              let maxFp = fixedPointWide(int: maxIntSigned, frac: maxFrac, denom: coefLog2Denom) else {
+            logOnce("[DoviFelComposer] \(label) NLQ parameters do not fit the fixed-point ABI; dropping residual", category: .swPlayback)
+            return disabled
+        }
+
+        // vdr_in_max is a normalised ceiling in Q(coefficient_log2_denom); the
+        // same shift that converts the residual converts the ceiling.
+        let scaledMax = maxFp >> Int64(nlqShift)
+        guard scaledMax >= 0, scaledMax <= Int64(Int32.max) else {
+            logOnce("[DoviFelComposer] \(label) vdr_in_max \(scaledMax) out of range; dropping residual", category: .swPlayback)
+            return disabled
+        }
+
+        if threshold != 0 {
+            deadzoneLogLock.lock()
+            let first = !loggedNonZeroDeadzone
+            loggedNonZeroDeadzone = true
+            deadzoneLogLock.unlock()
+            if first {
+                EngineLog.emit("[DoviFelComposer] \(label) linear_deadzone_threshold = \(threshold) (non-zero); "
+                    + "the inverse NLQ adds it to the scaled magnitude, as the spec's pseudo-code "
+                    + "does, but no surveyed stream carries a non-zero threshold. If highlights look "
+                    + "crushed or lifted, this is the first thing to question.", category: .swPlayback)
+            }
+        }
+
+        var params = DoviNlqParams()
+        params.nlqMethod = .linear
+        params.nlqPivots = pivots
+        params.nlqShift = nlqShift
+        params.nlqOffset = Int32(offset)
+        params.nlqScale = scale
+        params.nlqThreshold = threshold
+        params.vdrInMax = Int32(scaledMax)
+        return params
+    }
+}
diff --git a/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift b/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift
new file mode 100644
index 000000000..04287391f
--- /dev/null
+++ b/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift
@@ -0,0 +1,315 @@
+import Foundation
+
+/// How one reshaping piece is evaluated (`mapping_idc`).
+enum DoviMapping: UInt32, Sendable {
+    case polynomial = 0
+    case mmr = 1
+}
+
+/// `nlq_method_idc`. Anything the composer cannot invert maps to ``none``,
+/// which yields no residual rather than a wrong one.
+enum DoviNlqMethod: UInt32, Sendable {
+    case linear = 0
+    case none = 0xFFFF_FFFF
+}
+
+/// Output quantisation mode.
+enum DoviDither: UInt32, Sendable {
+    case none = 0
+    case bayer8x8 = 1
+    /// Test only: planes hold the un-quantised 12-bit VDR code shifted left 4, not P010.
+    case debugRawVDR = 2
+    /// Undithered, but the VDR bits below the 10-bit code are kept in P010's unused low 6 bits,
+    /// so a consumer that reads the full 16-bit word sees 12-bit (or finer) precision while one
+    /// that reads the top 10 bits sees the truncated code. Not validated on a display path yet.
+    case fullPrecision = 3
+}
+
+/// `DoviMetalParams.flags` bits.
+struct DoviComposerFlags: OptionSet, Sendable {
+    let rawValue: UInt32
+    init(rawValue: UInt32) { self.rawValue = rawValue }
+
+    /// `disable_residual_flag`, or the RPU declares `el_type == MEL`.
+    static let disableResidual = DoviComposerFlags(rawValue: 0x1)
+    /// The luma curve carries at least one MMR piece, so the luma kernel has to
+    /// read the base-layer chroma planes as well.
+    static let lumaMmr = DoviComposerFlags(rawValue: 0x2)
+}
+
+/// Piecewise reshaping curve for one component; mirrors
+/// `struct DoviPolynomialParams` in `DoviShaderSource`.
+///
+/// `numPivots < 2` means identity passthrough, which is the fail-safe the parser
+/// installs whenever a curve cannot be trusted.
+struct DoviPolynomialParams: Sendable {
+    static let maxPivots = 9
+    static let maxPieces = 8
+    /// Serialized size in bytes, asserted against the C struct by `_Static_assert`.
+    /// num_pivots + pivots + method + order + coef + coef_shift.
+    static let stride = 4 * (1 + maxPivots + maxPieces + maxPieces + maxPieces * 3 + maxPieces)
+
+    var numPivots: UInt32 = 0
+    var pivots: [UInt32] = Array(repeating: 0, count: DoviPolynomialParams.maxPivots)
+    var method: [UInt32] = Array(repeating: 0, count: DoviPolynomialParams.maxPieces)
+    var order: [UInt32] = Array(repeating: 0, count: DoviPolynomialParams.maxPieces)
+    var coef: [[Int32]] = Array(repeating: [0, 0, 0], count: DoviPolynomialParams.maxPieces)
+    var coefShift: [UInt32] = Array(repeating: 0, count: DoviPolynomialParams.maxPieces)
+
+    init() {}
+
+    /// Identity passthrough: the base layer reaches the output unreshaped.
+    static var identity: DoviPolynomialParams { DoviPolynomialParams() }
+
+    var isIdentity: Bool { numPivots < 2 }
+
+    /// A pivot count the fixed-size arrays and the kernels cannot hold is a corrupt curve; it takes the
+    /// same identity fail-safe as a curve the parser could not trust, instead of indexing past `pivots`.
+    mutating func clampToCapacity() {
+        if numPivots > UInt32(Self.maxPivots) { numPivots = 0 }
+        for i in coefShift.indices where coefShift[i] > 31 { coefShift[i] = 31 }
+        if pivots.count < Self.maxPivots { pivots += Array(repeating: 0, count: Self.maxPivots - pivots.count) }
+    }
+
+    /// True when any live piece is evaluated as MMR, which is what decides
+    /// whether the kernel needs the cross-component inputs.
+    var usesMmr: Bool {
+        guard numPivots >= 2 else { return false }
+        let pieces = min(Int(numPivots) - 1, Self.maxPieces)
+        for p in 0..<pieces where p < method.count {
+            if method[p] == DoviMapping.mmr.rawValue { return true }
+        }
+        return false
+    }
+}
+
+/// Multiple-model regression coefficients, one set per reshaping piece; mirrors
+/// `struct DoviMmrParams`.
+///
+/// Piece count, per-piece order and piece selection live in the matching
+/// ``DoviPolynomialParams``; this block carries only the coefficients, as
+/// `coef[piece][order * 7 + term]` over `[y, u, v, yu, yv, uv, yuv]`.
+struct DoviMmrParams: Sendable {
+    static let maxPieces = DoviPolynomialParams.maxPieces
+    static let coefficientsPerPiece = 21
+    static let stride = 4 * (maxPieces + maxPieces * coefficientsPerPiece + 1)
+
+    var constant: [Int32] = Array(repeating: 0, count: DoviMmrParams.maxPieces)
+    var coef: [[Int32]] = Array(
+        repeating: Array(repeating: 0, count: DoviMmrParams.coefficientsPerPiece),
+        count: DoviMmrParams.maxPieces
+    )
+    var coefShift: UInt32 = 0
+
+    init() {}
+}
+
+/// Inverse non-linear quantisation for one component; mirrors
+/// `struct DoviNlqParams`.
+///
+/// A zeroed value is the same neutral the C side gets from `memset`: method
+/// ``DoviNlqMethod/linear`` with a zero slope, which produces no residual.
+struct DoviNlqParams: Sendable {
+    static let stride = 4 * 8
+
+    var nlqMethod: DoviNlqMethod = .linear
+    var nlqOffset: Int32 = 0
+    var nlqScale: Int32 = 0
+    var nlqThreshold: Int32 = 0
+    var vdrInMax: Int32 = 0
+    var nlqShift: UInt32 = 0
+    /// Decoded (prefix-summed) `nlq_pred_pivot_value`. Carried for diagnostics;
+    /// the linear inverse has a single segment and does not consult them.
+    var nlqPivots: [UInt32] = [0, 1023]
+
+    init() {}
+
+    /// No residual at all, while preserving the shift and pivots already decoded
+    /// so a probe can still report what the RPU said.
+    static var disabled: DoviNlqParams {
+        var nlq = DoviNlqParams()
+        nlq.nlqMethod = .none
+        return nlq
+    }
+}
+
+/// Parameter block uploaded to the composition kernels; mirrors
+/// `struct DoviMetalParams` in `DoviShaderSource`.
+///
+/// ``serialize()`` writes the fields in declaration order and asserts each
+/// sub-block's size, and `dovi_layout_probe` reads sentinels back out of the
+/// uploaded bytes on the GPU, so a field added on one side of the ABI cannot go
+/// unnoticed on the other.
+struct DoviMetalParams: Sendable {
+    var blWidth: UInt32 = 3840
+    var blHeight: UInt32 = 2160
+    var elWidth: UInt32 = 1920
+    var elHeight: UInt32 = 1080
+
+    /// Informational: the output pool is always video-range 10-bit P010.
+    var targetMode: UInt32 = 0
+    var ditherMode: DoviDither = .bayer8x8
+    var frameIndex: UInt32 = 0
+    var flags: DoviComposerFlags = []
+
+    var polyY = DoviPolynomialParams()
+    var mmrY = DoviMmrParams()
+    var nlqY = DoviNlqParams()
+
+    var polyCb = DoviPolynomialParams()
+    var mmrCb = DoviMmrParams()
+    var nlqCb = DoviNlqParams()
+
+    var polyCr = DoviPolynomialParams()
+    var mmrCr = DoviMmrParams()
+    var nlqCr = DoviNlqParams()
+
+    var minPq: UInt32 = 0
+    var maxPq: UInt32 = 3079 // ~1000 nits
+    var avgPq: UInt32 = 1500
+
+    /// `(1 << bl_bit_depth) - 1`; the normalisation divisor for curve inputs.
+    var blMax: UInt32 = 1023
+    /// `(1 << vdr_bit_depth) - 1`; the reconstruction clamp.
+    var vdrMax: UInt32 = 4095
+    /// `1 << (vdr_bit_depth - bl_bit_depth)`; residual and denormalisation scale.
+    var vdrScale: UInt32 = 4
+
+    init() {}
+
+    /// Byte size of the serialized block, matching `sizeof(struct DoviMetalParams)`.
+    static let serializedSize =
+        4 * 8
+        + 3 * (DoviPolynomialParams.stride + DoviMmrParams.stride + DoviNlqParams.stride)
+        + 4 * 6
+
+    /// Derives ``blMax``, ``vdrMax`` and ``vdrScale`` from the RPU's declared bit
+    /// depths. Returns false, leaving the values untouched, for a combination the
+    /// kernels cannot express.
+    mutating func setBitDepths(bl: Int, vdr: Int) -> Bool {
+        guard bl >= 8, bl <= 16, vdr >= bl, vdr <= 16 else { return false }
+        blMax = UInt32((1 << bl) - 1)
+        vdrMax = UInt32((1 << vdr) - 1)
+        vdrScale = UInt32(1 << (vdr - bl))
+        return true
+    }
+
+    /// Little-endian sequential writer to a raw buffer pointer. Appending in declaration order and
+    /// checking each sub-block's length is what keeps the layout honest; writes directly into
+    /// preallocated Metal buffers without intermediate Data or array allocations.
+    private struct BufferWriter {
+        let buffer: UnsafeMutableRawBufferPointer
+        var offset: Int = 0
+
+        init(buffer: UnsafeMutableRawBufferPointer) {
+            precondition(buffer.count >= DoviMetalParams.serializedSize,
+                         "Buffer too small for serialized DoviMetalParams")
+            self.buffer = buffer
+        }
+
+        mutating func u32(_ value: UInt32) {
+            let v = value.littleEndian
+            buffer.storeBytes(of: v, toByteOffset: offset, as: UInt32.self)
+            offset += 4
+        }
+
+        mutating func i32(_ value: Int32) {
+            let v = value.littleEndian
+            buffer.storeBytes(of: v, toByteOffset: offset, as: Int32.self)
+            offset += 4
+        }
+
+        mutating func u32s(_ values: [UInt32], count: Int) {
+            for i in 0..<count { u32(i < values.count ? values[i] : 0) }
+        }
+
+        mutating func i32s(_ values: [Int32], count: Int) {
+            for i in 0..<count { i32(i < values.count ? values[i] : 0) }
+        }
+
+        mutating func append(_ poly: DoviPolynomialParams) {
+            let start = offset
+            u32(poly.numPivots)
+            u32s(poly.pivots, count: DoviPolynomialParams.maxPivots)
+            u32s(poly.method, count: DoviPolynomialParams.maxPieces)
+            u32s(poly.order, count: DoviPolynomialParams.maxPieces)
+            for p in 0..<DoviPolynomialParams.maxPieces {
+                i32s(p < poly.coef.count ? poly.coef[p] : [], count: 3)
+            }
+            u32s(poly.coefShift, count: DoviPolynomialParams.maxPieces)
+            precondition(offset - start == DoviPolynomialParams.stride,
+                         "DoviPolynomialParams serialization is not stride bytes")
+        }
+
+        mutating func append(_ mmr: DoviMmrParams) {
+            let start = offset
+            i32s(mmr.constant, count: DoviMmrParams.maxPieces)
+            for p in 0..<DoviMmrParams.maxPieces {
+                i32s(p < mmr.coef.count ? mmr.coef[p] : [],
+                     count: DoviMmrParams.coefficientsPerPiece)
+            }
+            u32(mmr.coefShift)
+            precondition(offset - start == DoviMmrParams.stride,
+                         "DoviMmrParams serialization is not stride bytes")
+        }
+
+        mutating func append(_ nlq: DoviNlqParams) {
+            let start = offset
+            u32(nlq.nlqMethod.rawValue)
+            i32(nlq.nlqOffset)
+            i32(nlq.nlqScale)
+            i32(nlq.nlqThreshold)
+            i32(nlq.vdrInMax)
+            u32(nlq.nlqShift)
+            u32(nlq.nlqPivots.count > 0 ? nlq.nlqPivots[0] : 0)
+            u32(nlq.nlqPivots.count > 1 ? nlq.nlqPivots[1] : 0)
+            precondition(offset - start == DoviNlqParams.stride,
+                         "DoviNlqParams serialization is not stride bytes")
+        }
+    }
+
+    /// Serializes directly into a preallocated raw buffer pointer without allocating Data (dolby-vision-fel.md §5.6).
+    func serialize(into buffer: UnsafeMutableRawBufferPointer) {
+        var w = BufferWriter(buffer: buffer)
+
+        w.u32(blWidth)
+        w.u32(blHeight)
+        w.u32(elWidth)
+        w.u32(elHeight)
+        w.u32(targetMode)
+        w.u32(ditherMode.rawValue)
+        w.u32(frameIndex)
+        w.u32(flags.rawValue)
+
+        w.append(polyY)
+        w.append(mmrY)
+        w.append(nlqY)
+
+        w.append(polyCb)
+        w.append(mmrCb)
+        w.append(nlqCb)
+
+        w.append(polyCr)
+        w.append(mmrCr)
+        w.append(nlqCr)
+
+        w.u32(minPq)
+        w.u32(maxPq)
+        w.u32(avgPq)
+        w.u32(blMax)
+        w.u32(vdrMax)
+        w.u32(vdrScale)
+
+        precondition(w.offset == Self.serializedSize,
+                     "DoviMetalParams serialization is not serializedSize bytes")
+    }
+
+    /// Serializes to the exact C/Metal memory layout.
+    func serialize() -> Data {
+        var data = Data(count: Self.serializedSize)
+        data.withUnsafeMutableBytes { raw in
+            serialize(into: raw)
+        }
+        return data
+    }
+}
diff --git a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
new file mode 100644
index 000000000..ededc06ef
--- /dev/null
+++ b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
@@ -0,0 +1,722 @@
+import Foundation
+
+/// Canonical Metal source for the Dolby Vision FEL composer.
+///
+/// `DoviFelComposer` compiles ``source`` at runtime with
+/// `MTLDevice.makeLibrary(source:)` on demand.
+enum DoviShaderSource {
+
+    /// Metal-side spelling of the fixed-width typedefs the shared block uses.
+    static let preamble = """
+#include <metal_stdlib>
+using namespace metal;
+
+typedef uint dovi_u32;
+typedef int  dovi_i32;
+"""
+
+    /// Definitions of the parameters and structs consumed by the Metal kernels.
+    static let sharedStructs = """
+/* DOVI_SHARED_STRUCTS_BEGIN */
+/* ---- Target output modes (informational; the composer always emits
+   video-range 10-bit P010, so this does not currently switch clamping) ---- */
+#define DOVI_TARGET_MODE_PROFILE_8_1  0 /* Rec.2020 YCbCr PQ 10-bit limited range */
+#define DOVI_TARGET_MODE_PROFILE_5    1 /* Dolby IPTPQc2 10-bit full range */
+
+/* ---- Dither modes ---- */
+#define DOVI_DITHER_NONE              0 /* round to nearest */
+#define DOVI_DITHER_BAYER_8X8         1 /* ordered dither, inverted on odd frames */
+#define DOVI_DITHER_FULL_PRECISION    3 /* keep the VDR bits below the 10-bit code in P010's low 6 bits */
+#define DOVI_DEBUG_RAW_VDR            2 /* test only: write the un-quantised VDR code << 4 (12-bit in 16) */
+
+/* ---- nlq_method_idc (ETSI GS CCM 001). Anything other than LINEAR yields no
+   residual rather than a wrong inverse, degrading to base-layer output. ---- */
+#define DOVI_NLQ_METHOD_LINEAR        0
+#define DOVI_NLQ_METHOD_NONE          0xFFFFFFFFu
+
+/* ---- mapping_idc, per reshaping piece ---- */
+#define DOVI_MAPPING_POLYNOMIAL       0
+#define DOVI_MAPPING_MMR              1
+
+/* ---- flags ---- */
+#define DOVI_FLAG_DISABLE_RESIDUAL    0x1u /* disable_residual_flag, or el_type == MEL */
+#define DOVI_FLAG_LUMA_MMR            0x2u /* luma curve has at least one MMR piece */
+
+/* Piecewise reshaping curve for one component.
+ *
+ * num_pivots < 2 means "identity passthrough"; the parser installs that as the
+ * fail-safe whenever a curve cannot be trusted, so a malformed RPU degrades to
+ * the base layer instead of to black.
+ *
+ * pivots are absolute (prefix-summed) BL code values, ascending, and pivots[0]
+ * / pivots[num_pivots - 1] bound the evaluation domain. method[i] selects how
+ * piece i is evaluated. The syntax lets a component mix polynomial and MMR
+ * pieces, but libdovi keeps one mapping_idc per component (the last piece's) and
+ * one coefficient list per method, so a mixed curve cannot be read back
+ * through its C API, and DoviRpuGuard refuses it before it gets here: in
+ * practice every piece of a component has the same method. order[i] is
+ * the polynomial order for a polynomial piece and the MMR order for an MMR
+ * piece. coef[i][j] is Q(coef_shift[i]) and is evaluated against inputs
+ * normalised by dividing the BL code value by 2^bl_bit_depth (bl_max + 1), the
+ * fixed-point convention of the spec's pseudo-code. */
+struct DoviPolynomialParams {
+    dovi_u32 num_pivots;
+    dovi_u32 pivots[9];
+    dovi_u32 method[8];
+    dovi_u32 order[8];
+    dovi_i32 coef[8][3];
+    dovi_u32 coef_shift[8];
+};
+
+/* Multiple-model regression coefficients, one set per reshaping piece.
+ *
+ * The piece count, the per-piece MMR order and the piece selection all live in
+ * the matching DoviPolynomialParams; this block only carries the coefficients,
+ * laid out as coef[piece][order * 7 + term] over the seven cross terms
+ * [y, u, v, yu, yv, uv, yuv]. Order o contributes those terms raised to the
+ * power o + 1. Every coefficient is Q(coef_shift) against normalised inputs. */
+struct DoviMmrParams {
+    dovi_i32 mmr_constant[8];
+    dovi_i32 coef[8][21];
+    dovi_u32 coef_shift;
+};
+
+/* Inverse non-linear quantisation for one component.
+ *
+ * nlq_scale and nlq_threshold are Q(coefficient_log2_denom) in the normalised
+ * residual domain; nlq_shift = coefficient_log2_denom - vdr_bit_depth converts
+ * that product into VDR code units. vdr_in_max is the ceiling already reduced
+ * to VDR code units by the parser. */
+struct DoviNlqParams {
+    dovi_u32 nlq_method;
+    dovi_i32 nlq_offset;
+    dovi_i32 nlq_scale;
+    dovi_i32 nlq_threshold;
+    dovi_i32 vdr_in_max;
+    dovi_u32 nlq_shift;
+    dovi_u32 nlq_pivots[2];
+};
+
+struct DoviMetalParams {
+    dovi_u32 bl_width;
+    dovi_u32 bl_height;
+    dovi_u32 el_width;
+    dovi_u32 el_height;
+
+    dovi_u32 target_mode;
+    dovi_u32 dither_mode;
+    dovi_u32 frame_index;
+    dovi_u32 flags;
+
+    struct DoviPolynomialParams poly_y;
+    struct DoviMmrParams        mmr_y;
+    struct DoviNlqParams        nlq_y;
+
+    struct DoviPolynomialParams poly_cb;
+    struct DoviMmrParams        mmr_cb;
+    struct DoviNlqParams        nlq_cb;
+
+    struct DoviPolynomialParams poly_cr;
+    struct DoviMmrParams        mmr_cr;
+    struct DoviNlqParams        nlq_cr;
+
+    dovi_u32 min_pq;
+    dovi_u32 max_pq;
+    dovi_u32 avg_pq;
+
+    /* Bit-depth derived constants, so the kernels carry no literal 1023/4095.
+       bl_max   = (1 << bl_bit_depth) - 1
+       vdr_max  = (1 << vdr_bit_depth) - 1
+       vdr_scale = 1 << (vdr_bit_depth - bl_bit_depth)
+       Curve inputs are normalised by 2^bl_bit_depth (bl_max + 1) and a normalised
+       prediction is denormalised by (bl_max + 1) * vdr_scale = 2^vdr_bit_depth, the
+       same scale both ways, so an identity curve is bit-exact and a neutral chroma
+       (code 512) maps to exactly 2048 (DoViBaker agrees; scaling by bl_max instead
+       puts it at 2049, and up to 2041 through an MMR constant). */
+    dovi_u32 bl_max;
+    dovi_u32 vdr_max;
+    dovi_u32 vdr_scale;
+};
+/* DOVI_SHARED_STRUCTS_END */
+"""
+
+    /// Kernel bodies and their helpers: the only place the composition math is
+    /// written down, shared by both consumers unchanged.
+    static let kernels = """
+
+/* ============================================================================
+   Ordered dither
+   ========================================================================= */
+
+constant float dovi_bayer_8x8[64] = {
+     0.0f/64.0f, 32.0f/64.0f,  8.0f/64.0f, 40.0f/64.0f,  2.0f/64.0f, 34.0f/64.0f, 10.0f/64.0f, 42.0f/64.0f,
+    48.0f/64.0f, 16.0f/64.0f, 56.0f/64.0f, 24.0f/64.0f, 50.0f/64.0f, 18.0f/64.0f, 58.0f/64.0f, 26.0f/64.0f,
+    12.0f/64.0f, 44.0f/64.0f,  4.0f/64.0f, 36.0f/64.0f, 14.0f/64.0f, 46.0f/64.0f,  6.0f/64.0f, 38.0f/64.0f,
+    60.0f/64.0f, 28.0f/64.0f, 52.0f/64.0f, 20.0f/64.0f, 62.0f/64.0f, 30.0f/64.0f, 54.0f/64.0f, 22.0f/64.0f,
+     3.0f/64.0f, 35.0f/64.0f, 11.0f/64.0f, 43.0f/64.0f,  1.0f/64.0f, 33.0f/64.0f,  9.0f/64.0f, 41.0f/64.0f,
+    51.0f/64.0f, 19.0f/64.0f, 59.0f/64.0f, 27.0f/64.0f, 49.0f/64.0f, 17.0f/64.0f, 57.0f/64.0f, 25.0f/64.0f,
+    15.0f/64.0f, 47.0f/64.0f,  7.0f/64.0f, 39.0f/64.0f, 13.0f/64.0f, 45.0f/64.0f,  5.0f/64.0f, 37.0f/64.0f,
+    63.0f/64.0f, 31.0f/64.0f, 55.0f/64.0f, 23.0f/64.0f, 61.0f/64.0f, 29.0f/64.0f, 53.0f/64.0f, 21.0f/64.0f
+};
+
+// Ordered dither offset in [0.5/64, 63.5/64], whose mean over the cell is
+// exactly 0.5 -- the same rounding bias the undithered branch applies.
+//
+// The raw Bayer table holds k/64 for k in 0..63 and averages 31.5/64 = 0.4921875,
+// 1/128 of a code low. That bias is invisible at any bit depth a Dolby Vision
+// stream can ask for: the value reaching the rounding step has a fraction of
+// j/vdr_scale, and for vdr_scale <= 64 the raw and centred tables select exactly
+// the same cells at every j, so 10-bit BL into 12-bit VDR (vdr_scale = 4) is
+// bit-identical either way. It becomes visible only at the vdr_scale >= 128 that
+// setBitDepths still accepts, where the raw table's worst per-level error is
+// 0.0117 codes against the centred table's 0.0078. Centring costs one add, makes
+// the mean exactly 0.5 as claimed, and removes the case where it would matter.
+//
+// phase translates the cell so that two components written from the same value do
+// not receive the same pattern. Not every translation does that: this matrix
+// satisfies M[(y + 4) % 8][(x + 4) % 8] == M[y][x] +/- 1, so the (4, 4) diagonal
+// is its own near-symmetry (a Cr phase there leaves Cb and Cr disagreeing on
+// an average of 1 pixel in 64 -- at the 50% level, where the selected set is a
+// checkerboard in (x + y) parity and a (4, 4) shift preserves parity, on zero
+// pixels). Translations of odd parity are the ones that decorrelate, averaging 32
+// pixels in 64. Parity is additive, so three mutually odd offsets do not exist;
+// (0, 0) / (1, 0) / (1, 1) makes the two chroma components and the luma-Cb pair
+// odd and leaves luma-Cr, which is also the pair that differs in plane and in
+// resolution, at 16 in 64.
+static inline float dovi_dither(uint2 gid, uint frame_index, uint2 phase) {
+    uint dx = (gid.x + phase.x) % 8u;
+    uint dy = (gid.y + phase.y) % 8u;
+    float d = dovi_bayer_8x8[dy * 8u + dx];
+    if (frame_index & 1u) {
+        // Inversion is over the raw table, so the frame pair still covers every
+        // cell exactly once; the half-step is added to both frames afterwards.
+        d = (63.0f / 64.0f) - d;
+    }
+    return d + (0.5f / 64.0f);
+}
+
+/* ============================================================================
+   Reshaping curve evaluation
+   ========================================================================= */
+
+// Index of the piece owning bl_val: the last pivot that bl_val reaches.
+// Deliberately last-match-wins rather than first, because adjacent pivots can
+// repeat (a zero-width piece) and the spec assigns the sample to the later one.
+static inline int dovi_select_piece(constant struct DoviPolynomialParams &curve, int bl_val) {
+    int last_piece = int(curve.num_pivots) - 2;
+    int piece = 0;
+    for (int i = 0; i <= last_piece; ++i) {
+        if (bl_val >= int(curve.pivots[i])) {
+            piece = i;
+        }
+    }
+    return clamp(piece, 0, max(last_piece, 0));
+}
+
+// Polynomial piece, evaluated on the input normalised by `bl_max`. Callers pass
+// bl_max + 1 (= 2^bl_bit_depth), the same normaliser as the y/u/v inputs.
+// Returns the prediction in normalised units; dovi_denormalize floors it at 0 before the residual is
+// added (DoViBaker clamps `vv`/`rr` at 0 there), and the sum is clamped again afterwards.
+static inline float dovi_eval_poly(
+    constant struct DoviPolynomialParams &curve,
+    int piece,
+    int bl_val,
+    uint bl_max)
+{
+    int lo = int(curve.pivots[0]);
+    int hi = int(curve.pivots[curve.num_pivots - 1]);
+    float x = float(clamp(bl_val, lo, hi)) / float(bl_max);
+
+    float inv = ldexp(1.0f, -int(curve.coef_shift[piece]));
+    float pred = float(curve.coef[piece][0]) * inv;
+    uint order = curve.order[piece];
+    if (order >= 1u) {
+        pred = fma(float(curve.coef[piece][1]) * inv, x, pred);
+    }
+    if (order >= 2u) {
+        pred = fma(float(curve.coef[piece][2]) * inv, x * x, pred);
+    }
+    return pred;
+}
+
+// An MMR input clamped to the pivot range of its own component (luma to poly_y's, Cb to poly_cb's,
+// Cr to poly_cr's), as DoViBaker's `mmrMapping` does before it forms the cross terms. A component with
+// no usable curve (num_pivots < 2) has no range and is left as is.
+static inline float dovi_clamp_mmr_input(constant struct DoviPolynomialParams &curve, float norm, float scale) {
+    if (curve.num_pivots < 2u) {
+        return norm;
+    }
+    float lo = float(curve.pivots[0]) / scale;
+    float hi = float(curve.pivots[curve.num_pivots - 1u]) / scale;
+    return clamp(norm, lo, hi);
+}
+
+// MMR piece: a regression over the seven cross terms of all three normalised
+// base-layer components, with order o contributing those terms raised to o + 1.
+static inline float dovi_eval_mmr(
+    constant struct DoviPolynomialParams &curve,
+    constant struct DoviMmrParams &mmr,
+    int piece,
+    float y_norm, float u_norm, float v_norm)
+{
+    // y_norm, u_norm and v_norm are already clamped to their components' pivot ranges.
+    float inv = ldexp(1.0f, -int(mmr.coef_shift));
+    float s = float(mmr.mmr_constant[piece]) * inv;
+
+    float base[7] = {
+        y_norm,
+        u_norm,
+        v_norm,
+        y_norm * u_norm,
+        y_norm * v_norm,
+        u_norm * v_norm,
+        y_norm * u_norm * v_norm
+    };
+    float t[7];
+    for (int k = 0; k < 7; ++k) {
+        t[k] = base[k];
+    }
+
+    uint order = min(curve.order[piece], 3u);
+    for (uint o = 0u; o < order; ++o) {
+        for (int k = 0; k < 7; ++k) {
+            s = fma(float(mmr.coef[piece][o * 7u + uint(k)]) * inv, t[k], s);
+        }
+        if (o + 1u < order) {
+            for (int k = 0; k < 7; ++k) {
+                t[k] *= base[k];
+            }
+        }
+    }
+    return s;
+}
+
+// One component's reshaping prediction, in normalised [0, 1] units.
+// num_pivots < 2 is the parser's fail-safe for a curve it could not trust, and
+// means identity: the base layer passes through untouched.
+static inline float dovi_eval_curve(
+    constant struct DoviPolynomialParams &curve,
+    constant struct DoviMmrParams &mmr,
+    constant struct DoviPolynomialParams &poly_y,
+    constant struct DoviPolynomialParams &poly_cb,
+    constant struct DoviPolynomialParams &poly_cr,
+    int bl_val,
+    float y_norm, float u_norm, float v_norm,
+    uint bl_max)
+{
+    if (curve.num_pivots < 2u) {
+        return float(bl_val) / float(bl_max);
+    }
+    int piece = dovi_select_piece(curve, bl_val);
+    if (curve.method[piece] == DOVI_MAPPING_MMR) {
+        float scale = float(bl_max);
+        return dovi_eval_mmr(curve, mmr, piece,
+                             dovi_clamp_mmr_input(poly_y, y_norm, scale),
+                             dovi_clamp_mmr_input(poly_cb, u_norm, scale),
+                             dovi_clamp_mmr_input(poly_cr, v_norm, scale));
+    }
+    return dovi_eval_poly(curve, piece, bl_val, bl_max);
+}
+
+// Normalised prediction back into VDR code units. Callers pass bl_max + 1, so the
+// scale is (bl_max + 1) * vdr_scale = 2^vdr_bit_depth rather than vdr_max, which is
+// what makes an identity curve bit-exact end to end.
+static inline int dovi_denormalize(float pred_norm, uint bl_max, uint vdr_scale) {
+    // The prediction is floored at 0 before the residual is added, as DoViBaker does for both the
+    // polynomial and the MMR result, so a negative prediction cannot be pulled back up by the residual.
+    return max(int(rint(pred_norm * float(bl_max) * float(vdr_scale))), 0);
+}
+
+/* ============================================================================
+   Inverse NLQ
+   ========================================================================= */
+
+// Inverse linear-deadzone quantiser, in VDR code units.
+//
+// mag_fp is Q(coefficient_log2_denom) of the normalised residual, so the shift
+// by nlq_shift = coefficient_log2_denom - vdr_bit_depth lands it in VDR code
+// units. That reading is corroborated by the RPUs themselves: both test streams
+// carry linear_deadzone_slope = 2048 and vdr_in_max = 0.125 at denom 23, and
+// 512 * 2048 >> 11 is exactly 512, i.e. the slope is tuned so the enhancement
+// layer's full +/-512 swing lands precisely on vdr_in_max. Shifting by denom
+// instead (the convention the vc4 composer uses) collapses every residual to
+// zero, and no other shift makes the two fields agree.
+//
+// The threshold is ADDED to the magnitude, in the same Q(coefficient_log2_denom) domain as
+// (|r| - 1/2) * slope, and there is no early zero: that is the spec's pseudo-code, and DoViBaker
+// implements it (`dq += T * sign`). Every real stream carries linear_deadzone_threshold == 0 (RPU
+// survey, 9,816 RPUs), where all readings agree. Subtracting it, or zeroing anything inside the
+// deadzone, would be a different reading and does not match a second implementation.
+static inline int dovi_eval_inv_nlq(constant struct DoviNlqParams &nlq, int el_val) {
+    if (nlq.nlq_method != DOVI_NLQ_METHOD_LINEAR || nlq.nlq_scale == 0) {
+        return 0;
+    }
+    int r = el_val - nlq.nlq_offset;
+    if (r == 0) {
+        return 0;
+    }
+    // Reconstruction at the middle of the quantisation step, (|r| - 1/2) * scale, in doubled fixed
+    // point so the half step stays exact.
+    long mag_fp = (2L * long(abs(r)) - 1L) * long(nlq.nlq_scale);
+    long threshold2 = 2L * long(nlq.nlq_threshold);
+    long mag = (mag_fp + threshold2) >> (nlq.nlq_shift + 1u);
+    if (nlq.vdr_in_max > 0 && mag > long(nlq.vdr_in_max)) {
+        mag = long(nlq.vdr_in_max);
+    }
+    return (r < 0) ? -int(mag) : int(mag);
+}
+
+/* ============================================================================
+   Output quantisation
+   ========================================================================= */
+
+// Full-precision sample: v/vdr_scale in 10-bit codes with 6 fractional bits, clamped to the
+// video-range limits. The top 10 bits are the truncated code; the rest is what P010 leaves unused.
+static inline int dovi_full_precision(int vdr_val, uint vdr_scale, int lo, int hi) {
+    int v = (vdr_val * 64 + int(vdr_scale >> 1)) / int(vdr_scale);
+    return clamp(v, lo << 6, hi << 6);
+}
+
+// VDR code value down to the 10-bit output plane, dithered or rounded.
+static inline int dovi_quantize(
+    int vdr_val,
+    uint vdr_scale,
+    uint dither_mode,
+    float dither,
+    int lo,
+    int hi)
+{
+    float v = float(vdr_val) / float(vdr_scale);
+    // Both branches have mean 0.5, so enabling dither redistributes the rounding
+    // error without moving the average level.
+    float bias = (dither_mode == DOVI_DITHER_NONE) ? 0.5f : dither;
+    return clamp(int(floor(v + bias)), lo, hi);
+}
+
+/* ============================================================================
+   Enhancement layer upsampling
+   ========================================================================= */
+
+// EL upsampling: one hardware bilinear fetch.
+//
+// el_spatial_resampling_filter_flag advertises that the encoder used its own
+// separable filter, whose taps the RPU does not carry, so no bit-exact inverse
+// is available from the stream. Against the DoViBaker oracle on a fine-detail set (gratings, zone plate,
+// band-limited noise) a 4-fetch Catmull-Rom bought about 0.7% of per-pixel error sd over bilinear, with chroma
+// unchanged, for four times the EL reads. `tex_size` is unused by bilinear; it is
+// kept so a wider filter can replace this one without touching the callers.
+static inline float dovi_sample_el_1d(
+    texture2d<float, access::sample> tex,
+    sampler s,
+    float2 uv,
+    float2 tex_size)
+{
+    return tex.sample(s, uv).r;
+}
+
+static inline float2 dovi_sample_el_2d(
+    texture2d<float, access::sample> tex,
+    sampler s,
+    float2 uv,
+    float2 tex_size)
+{
+    return tex.sample(s, uv).rg;
+}
+
+// UNORM [0, 1] from a 10-in-16 MSB-aligned P010 plane back to a code value.
+// 65535 / 64 is exact: the hardware divides the stored ushort by 65535, and the
+// code value is that ushort >> 6.
+constant float dovi_unorm_to_code = 65535.0f / 64.0f;
+
+/* ============================================================================
+   Composition kernels
+   ========================================================================= */
+
+// Luma: BL luma + reshaping curve + inverse-NLQ residual -> 10-bit P010 plane.
+//
+// bl_uv_tex is bound only because a luma curve may carry MMR pieces, which need
+// all three components. No observed profile 7 stream has an MMR luma curve (libdovi
+// would report it as mapping_idc = 1 for component 0), so the DOVI_FLAG_LUMA_MMR gate
+// normally skips the fetch entirely. When it does fire, the chroma pair is taken
+// nearest-neighbour from the 4:2:0 plane: the reshaping model is defined on 4:4:4
+// input, and reconstructing chroma to full resolution here would cost a separate
+// pass for a case that does not occur in practice.
+kernel void dovi_compose_luma(
+    texture2d<ushort, access::read>        bl_y_tex      [[texture(0)]],
+    texture2d<ushort, access::read>        bl_uv_tex     [[texture(1)]],
+    texture2d<float, access::sample>       el_y_tex      [[texture(2)]],
+    texture2d<ushort, access::write>       out_y_tex     [[texture(3)]],
+    constant struct DoviMetalParams&       params        [[buffer(0)]],
+    constant float*                        luma_lut      [[buffer(1)]],
+    uint2                                  gid           [[thread_position_in_grid]])
+{
+    if (gid.x >= params.bl_width || gid.y >= params.bl_height) {
+        return;
+    }
+
+    int bl_y = int(bl_y_tex.read(gid).r >> 6);
+
+    float pred;
+    if ((params.flags & DOVI_FLAG_LUMA_MMR) == 0u) {
+        pred = luma_lut[bl_y];
+    } else {
+        float y_norm = float(bl_y) / float(params.bl_max + 1u);
+        ushort4 bl_uv = bl_uv_tex.read(uint2(gid.x >> 1, gid.y >> 1));
+        float u_norm = float(int(bl_uv.r >> 6)) / float(params.bl_max + 1u);
+        float v_norm = float(int(bl_uv.g >> 6)) / float(params.bl_max + 1u);
+        pred = dovi_eval_curve(params.poly_y, params.mmr_y,
+                               params.poly_y, params.poly_cb, params.poly_cr, bl_y,
+                               y_norm, u_norm, v_norm, params.bl_max + 1u);
+    }
+    int vdr_y = dovi_denormalize(pred, params.bl_max + 1u, params.vdr_scale);
+
+    if ((params.flags & DOVI_FLAG_DISABLE_RESIDUAL) == 0u &&
+        params.nlq_y.nlq_method == DOVI_NLQ_METHOD_LINEAR &&
+        params.nlq_y.nlq_scale != 0) {
+        constexpr sampler s(coord::normalized, filter::linear, address::clamp_to_edge);
+        float2 uv = (float2(gid) + 0.5f) / float2(params.bl_width, params.bl_height);
+        float el = dovi_sample_el_1d(el_y_tex, s, uv,
+                                     float2(params.el_width, params.el_height)) * dovi_unorm_to_code;
+        vdr_y += dovi_eval_inv_nlq(params.nlq_y, int(rint(el)));
+    }
+
+    vdr_y = clamp(vdr_y, 0, int(params.vdr_max));
+
+    int out_y = dovi_quantize(vdr_y, params.vdr_scale, params.dither_mode,
+                              dovi_dither(gid, params.frame_index, uint2(0u, 0u)), 64, 940);
+    if (params.dither_mode == DOVI_DEBUG_RAW_VDR) {
+        out_y_tex.write(ushort4(ushort(vdr_y << 4), 0, 0, 0), gid);
+        return;
+    }
+    if (params.dither_mode == DOVI_DITHER_FULL_PRECISION) {
+        out_y_tex.write(ushort4(ushort(dovi_full_precision(vdr_y, params.vdr_scale, 64, 940)), 0, 0, 0), gid);
+        return;
+    }
+    out_y_tex.write(ushort4(ushort(out_y << 6), 0, 0, 0), gid);
+}
+
+// Chroma: both chroma planes in one pass, since an MMR curve for Cb and for Cr
+// reads the same three base-layer components.
+kernel void dovi_compose_chroma(
+    texture2d<ushort, access::read>        bl_y_tex      [[texture(0)]],
+    texture2d<ushort, access::read>        bl_uv_tex     [[texture(1)]],
+    texture2d<float, access::sample>       el_uv_tex     [[texture(2)]],
+    texture2d<ushort, access::write>       out_uv_tex    [[texture(3)]],
+    constant struct DoviMetalParams&       params        [[buffer(0)]],
+    uint2                                  gid           [[thread_position_in_grid]])
+{
+    uint uv_width = params.bl_width / 2u;
+    uint uv_height = params.bl_height / 2u;
+
+    if (gid.x >= uv_width || gid.y >= uv_height) {
+        return;
+    }
+
+    // Base-layer luma at the chroma site, for the cross-component terms: [1 2 1]
+    // around the even column in each of the cell's two rows, then the rows
+    // averaged, in integers, edges clamped. This is DoViBaker's reading, and
+    // Dolby-encoded streams agree with it: on one with order-3 MMR chroma the
+    // coded residual matches it at about half the error of the plain vertical
+    // 2-tap this kernel used before.
+    uint lx = min(gid.x * 2u, params.bl_width - 1u);
+    uint lxl = lx > 0u ? lx - 1u : 0u;
+    uint lxr = min(lx + 1u, params.bl_width - 1u);
+    int bl_y = 0;
+    for (uint r = 0u; r < 2u; ++r) {
+        uint ly = min(gid.y * 2u + r, params.bl_height - 1u);
+        int row = int(bl_y_tex.read(uint2(lxl, ly)).r >> 6)
+                + 2 * int(bl_y_tex.read(uint2(lx, ly)).r >> 6)
+                + int(bl_y_tex.read(uint2(lxr, ly)).r >> 6);
+        bl_y += (row + 2) >> 2;
+    }
+    bl_y = (bl_y + 1) >> 1;
+
+    ushort4 bl_uv = bl_uv_tex.read(gid);
+    int bl_cb = int(bl_uv.r >> 6);
+    int bl_cr = int(bl_uv.g >> 6);
+
+    float y_norm = float(bl_y) / float(params.bl_max + 1u);
+    float u_norm = float(bl_cb) / float(params.bl_max + 1u);
+    float v_norm = float(bl_cr) / float(params.bl_max + 1u);
+
+    float pred_cb = dovi_eval_curve(params.poly_cb, params.mmr_cb,
+                                    params.poly_y, params.poly_cb, params.poly_cr, bl_cb,
+                                    y_norm, u_norm, v_norm, params.bl_max + 1u);
+    float pred_cr = dovi_eval_curve(params.poly_cr, params.mmr_cr,
+                                    params.poly_y, params.poly_cb, params.poly_cr, bl_cr,
+                                    y_norm, u_norm, v_norm, params.bl_max + 1u);
+
+    int vdr_cb = dovi_denormalize(pred_cb, params.bl_max + 1u, params.vdr_scale);
+    int vdr_cr = dovi_denormalize(pred_cr, params.bl_max + 1u, params.vdr_scale);
+
+    if ((params.flags & DOVI_FLAG_DISABLE_RESIDUAL) == 0u) {
+        bool cb_active = (params.nlq_cb.nlq_method == DOVI_NLQ_METHOD_LINEAR && params.nlq_cb.nlq_scale != 0);
+        bool cr_active = (params.nlq_cr.nlq_method == DOVI_NLQ_METHOD_LINEAR && params.nlq_cr.nlq_scale != 0);
+        if (cb_active || cr_active) {
+            constexpr sampler s(coord::normalized, filter::linear, address::clamp_to_edge);
+            float2 uv = (float2(gid) + 0.5f) / float2(uv_width, uv_height);
+            float2 el = dovi_sample_el_2d(el_uv_tex, s, uv,
+                                          float2(params.el_width / 2u, params.el_height / 2u)) * dovi_unorm_to_code;
+            if (cb_active) {
+                vdr_cb += dovi_eval_inv_nlq(params.nlq_cb, int(rint(el.r)));
+            }
+            if (cr_active) {
+                vdr_cr += dovi_eval_inv_nlq(params.nlq_cr, int(rint(el.g)));
+            }
+        }
+    }
+
+    vdr_cb = clamp(vdr_cb, 0, int(params.vdr_max));
+    vdr_cr = clamp(vdr_cr, 0, int(params.vdr_max));
+
+    int out_cb = dovi_quantize(vdr_cb, params.vdr_scale, params.dither_mode,
+                               dovi_dither(gid, params.frame_index, uint2(1u, 0u)), 64, 960);
+    int out_cr = dovi_quantize(vdr_cr, params.vdr_scale, params.dither_mode,
+                               dovi_dither(gid, params.frame_index, uint2(1u, 1u)), 64, 960);
+
+    if (params.dither_mode == DOVI_DEBUG_RAW_VDR) {
+        out_uv_tex.write(ushort4(ushort(vdr_cb << 4), ushort(vdr_cr << 4), 0, 0), gid);
+        return;
+    }
+    if (params.dither_mode == DOVI_DITHER_FULL_PRECISION) {
+        out_uv_tex.write(ushort4(ushort(dovi_full_precision(vdr_cb, params.vdr_scale, 64, 960)),
+                                 ushort(dovi_full_precision(vdr_cr, params.vdr_scale, 64, 960)), 0, 0), gid);
+        return;
+    }
+    out_uv_tex.write(ushort4(ushort(out_cb << 6), ushort(out_cr << 6), 0, 0), gid);
+}
+
+/* ============================================================================
+   Layout probe
+   ========================================================================= */
+
+// Reads sentinels back out of the parameter block the host actually uploaded,
+// so the Swift serialiser and this shader's struct definitions are checked
+// against each other on the GPU rather than by hand. Metal has no static_assert
+// and the offline metal compiler is not always installed, so slot 0 carries
+// sizeof(DoviMetalParams), slots 1-35 the scalars and the last element of each
+// sub-block, and slots 36 onwards, per component, the first element of every array
+// and every NLQ scalar: any offset drift or swapped neighbours moves a sentinel
+// and the test fails.
+kernel void dovi_layout_probe(
+    constant struct DoviMetalParams& params [[buffer(0)]],
+    device uint*                     out    [[buffer(1)]],
+    uint                             tid    [[thread_position_in_grid]])
+{
+    if (tid != 0u) {
+        return;
+    }
+
+    out[0] = uint(sizeof(struct DoviMetalParams));
+
+    out[1] = params.bl_width;
+    out[2] = params.bl_height;
+    out[3] = params.el_width;
+    out[4] = params.el_height;
+    out[5] = params.target_mode;
+    out[6] = params.dither_mode;
+    out[7] = params.frame_index;
+    out[8] = params.flags;
+
+    out[9]  = params.poly_y.num_pivots;
+    out[10] = params.poly_y.pivots[8];
+    out[11] = params.poly_y.method[7];
+    out[12] = params.poly_y.order[7];
+    out[13] = uint(params.poly_y.coef[7][2]);
+    out[14] = params.poly_y.coef_shift[7];
+    out[15] = uint(params.mmr_y.mmr_constant[7]);
+    out[16] = uint(params.mmr_y.coef[7][20]);
+    out[17] = params.mmr_y.coef_shift;
+    out[18] = uint(params.nlq_y.vdr_in_max);
+    out[19] = params.nlq_y.nlq_pivots[1];
+
+    out[20] = params.poly_cb.num_pivots;
+    out[21] = params.poly_cb.coef_shift[7];
+    out[22] = uint(params.mmr_cb.coef[7][20]);
+    out[23] = params.mmr_cb.coef_shift;
+    out[24] = params.nlq_cb.nlq_pivots[1];
+
+    out[25] = params.poly_cr.num_pivots;
+    out[26] = params.poly_cr.coef_shift[7];
+    out[27] = uint(params.mmr_cr.coef[7][20]);
+    out[28] = params.mmr_cr.coef_shift;
+    out[29] = params.nlq_cr.nlq_pivots[1];
+
+    out[30] = params.min_pq;
+    out[31] = params.max_pq;
+    out[32] = params.avg_pq;
+    out[33] = params.bl_max;
+    out[34] = params.vdr_max;
+    out[35] = params.vdr_scale;
+
+    // --- y: first element of every array and every NLQ scalar ---
+    out[36] = params.poly_y.pivots[0];
+    out[37] = params.poly_y.pivots[1];
+    out[38] = params.poly_y.method[0];
+    out[39] = params.poly_y.order[0];
+    out[40] = uint(params.poly_y.coef[0][0]);
+    out[41] = uint(params.poly_y.coef[0][1]);
+    out[42] = uint(params.poly_y.coef[1][0]);
+    out[43] = params.poly_y.coef_shift[0];
+    out[44] = uint(params.mmr_y.mmr_constant[0]);
+    out[45] = uint(params.mmr_y.coef[0][0]);
+    out[46] = uint(params.mmr_y.coef[0][1]);
+    out[47] = uint(params.mmr_y.coef[1][0]);
+    out[48] = params.nlq_y.nlq_method;
+    out[49] = uint(params.nlq_y.nlq_offset);
+    out[50] = uint(params.nlq_y.nlq_scale);
+    out[51] = uint(params.nlq_y.nlq_threshold);
+    out[52] = params.nlq_y.nlq_shift;
+    out[53] = uint(params.nlq_y.vdr_in_max);
+    out[54] = params.nlq_y.nlq_pivots[0];
+    out[55] = params.nlq_y.nlq_pivots[1];
+    // --- cb: first element of every array and every NLQ scalar ---
+    out[56] = params.poly_cb.pivots[0];
+    out[57] = params.poly_cb.pivots[1];
+    out[58] = params.poly_cb.method[0];
+    out[59] = params.poly_cb.order[0];
+    out[60] = uint(params.poly_cb.coef[0][0]);
+    out[61] = uint(params.poly_cb.coef[0][1]);
+    out[62] = uint(params.poly_cb.coef[1][0]);
+    out[63] = params.poly_cb.coef_shift[0];
+    out[64] = uint(params.mmr_cb.mmr_constant[0]);
+    out[65] = uint(params.mmr_cb.coef[0][0]);
+    out[66] = uint(params.mmr_cb.coef[0][1]);
+    out[67] = uint(params.mmr_cb.coef[1][0]);
+    out[68] = params.nlq_cb.nlq_method;
+    out[69] = uint(params.nlq_cb.nlq_offset);
+    out[70] = uint(params.nlq_cb.nlq_scale);
+    out[71] = uint(params.nlq_cb.nlq_threshold);
+    out[72] = params.nlq_cb.nlq_shift;
+    out[73] = uint(params.nlq_cb.vdr_in_max);
+    out[74] = params.nlq_cb.nlq_pivots[0];
+    out[75] = params.nlq_cb.nlq_pivots[1];
+    // --- cr: first element of every array and every NLQ scalar ---
+    out[76] = params.poly_cr.pivots[0];
+    out[77] = params.poly_cr.pivots[1];
+    out[78] = params.poly_cr.method[0];
+    out[79] = params.poly_cr.order[0];
+    out[80] = uint(params.poly_cr.coef[0][0]);
+    out[81] = uint(params.poly_cr.coef[0][1]);
+    out[82] = uint(params.poly_cr.coef[1][0]);
+    out[83] = params.poly_cr.coef_shift[0];
+    out[84] = uint(params.mmr_cr.mmr_constant[0]);
+    out[85] = uint(params.mmr_cr.coef[0][0]);
+    out[86] = uint(params.mmr_cr.coef[0][1]);
+    out[87] = uint(params.mmr_cr.coef[1][0]);
+    out[88] = params.nlq_cr.nlq_method;
+    out[89] = uint(params.nlq_cr.nlq_offset);
+    out[90] = uint(params.nlq_cr.nlq_scale);
+    out[91] = uint(params.nlq_cr.nlq_threshold);
+    out[92] = params.nlq_cr.nlq_shift;
+    out[93] = uint(params.nlq_cr.vdr_in_max);
+    out[94] = params.nlq_cr.nlq_pivots[0];
+    out[95] = params.nlq_cr.nlq_pivots[1];
+}
+"""
+
+    /// Runtime-compiled form: typedefs, struct block and kernels in one string.
+    static var source: String {
+        preamble + "\n" + sharedStructs + "\n" + kernels + "\n"
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
new file mode 100644
index 000000000..8d0a4e194
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
@@ -0,0 +1,283 @@
+import Testing
+import CoreVideo
+import Foundation
+import Metal
+@testable import AetherEngine
+
+/// `composeAsync` is the playback path: it must produce exactly what the blocking
+/// `compose` produces, fire its completion exactly once per call, and never let
+/// more than `maxFramesInFlight` compositions be outstanding.
+@Suite(.enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
+struct DoviComposeAsyncTests {
+
+    private static func makeBuffer(width: Int, height: Int, fill: UInt16) -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [kCVPixelBufferMetalCompatibilityKey: true,
+                                          kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary,
+                                         &out)
+        guard status == kCVReturnSuccess, let buf = out else { return nil }
+        CVPixelBufferLockBaseAddress(buf, [])
+        defer { CVPixelBufferUnlockBaseAddress(buf, []) }
+        for plane in 0..<CVPixelBufferGetPlaneCount(buf) {
+            guard let base = CVPixelBufferGetBaseAddressOfPlane(buf, plane) else { continue }
+            let rows = CVPixelBufferGetHeightOfPlane(buf, plane)
+            let stride = CVPixelBufferGetBytesPerRowOfPlane(buf, plane)
+            for r in 0..<rows {
+                let row = base.advanced(by: r * stride).assumingMemoryBound(to: UInt16.self)
+                for c in 0..<(stride / 2) { row[c] = fill }
+            }
+        }
+        return buf
+    }
+
+    /// P010 carries the 10 bits in the high end of each 16-bit sample, so compare
+    /// the words themselves rather than any derived value.
+    private static func lumaWords(_ buffer: CVPixelBuffer) -> [UInt16] {
+        CVPixelBufferLockBaseAddress(buffer, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(buffer, .readOnly) }
+        guard let base = CVPixelBufferGetBaseAddressOfPlane(buffer, 0) else { return [] }
+        let rows = CVPixelBufferGetHeightOfPlane(buffer, 0)
+        let stride = CVPixelBufferGetBytesPerRowOfPlane(buffer, 0)
+        var out: [UInt16] = []
+        out.reserveCapacity(rows * (stride / 2))
+        for r in 0..<rows {
+            let row = base.advanced(by: r * stride).assumingMemoryBound(to: UInt16.self)
+            for c in 0..<(stride / 2) { out.append(row[c]) }
+        }
+        return out
+    }
+
+    /// Defaults, resized to the small test planes. Only the dimensions matter
+    /// here — the question is the plumbing, not the curve.
+    private static func identityParams(blW: Int, blH: Int, elW: Int, elH: Int) -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.blWidth = UInt32(blW)
+        p.blHeight = UInt32(blH)
+        p.elWidth = UInt32(elW)
+        p.elHeight = UInt32(elH)
+        return p
+    }
+
+    @Test("a command buffer that fails delivers a failure, not the half-written destination")
+    func gpuErrorIsAFailure() async throws {
+        let composer = try #require(DoviFelComposer())
+        guard let bl = Self.makeBuffer(width: 256, height: 256, fill: 0x8000),
+              let el = Self.makeBuffer(width: 128, height: 128, fill: 0x4000) else { return }
+        let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
+        composer.forcedCommandBufferFailure.withLock { $0 = true }
+
+        #expect(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 1) == nil)
+        let delivered: Bool = await withCheckedContinuation { cont in
+            composer.composeAsync(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 1) { out in
+                cont.resume(returning: out != nil)
+            }
+        }
+        #expect(!delivered)
+
+        // The slot and the pool were given back: composing works again once the fault is gone.
+        composer.forcedCommandBufferFailure.withLock { $0 = false }
+        #expect(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 2) != nil)
+    }
+
+    @Test("after releaseOutputPool a composition is refused, its slot is returned and no pool is rebuilt",
+          .timeLimit(.minutes(1)))
+    func composeAfterTeardownIsRefused() async throws {
+        let composer = try #require(DoviFelComposer())
+        let bl = try #require(Self.makeBuffer(width: 256, height: 256, fill: 0x8000))
+        let el = try #require(Self.makeBuffer(width: 128, height: 128, fill: 0x4000))
+        let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
+        #expect(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 1) != nil)
+
+        composer.releaseOutputPool()
+        #expect(composer.allocatedPoolBuffers == 0)
+
+        #expect(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 2) == nil)
+        // More refusals than there are in-flight slots: a leaked slot would block here for good.
+        for frame in 0..<(DoviFelComposer.maxFramesInFlight + 3) {
+            let delivered: Bool = await withCheckedContinuation { cont in
+                composer.composeAsync(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: UInt32(frame)) { out in
+                    cont.resume(returning: out != nil)
+                }
+            }
+            #expect(!delivered)
+        }
+        #expect(composer.allocatedPoolBuffers == 0, "a pool was rebuilt after teardown")
+    }
+
+    @Test("pool creation is refused once torn down, whatever the caller saw before", .timeLimit(.minutes(1)))
+    func poolCreationAfterTeardownIsRefused() throws {
+        let composer = try #require(DoviFelComposer())
+        #expect(composer.ensurePoolForTesting(width: 256, height: 256) != nil)
+        composer.releaseOutputPool()
+        // The state a racing compose is in when teardown lands after its own look and before its pool request.
+        #expect(composer.ensurePoolForTesting(width: 256, height: 256) == nil)
+        #expect(composer.ensurePoolForTesting(width: 512, height: 512) == nil)
+        #expect(composer.allocatedPoolBuffers == 0)
+    }
+
+    @Test("the blocking compose waits for an in-flight slot like composeAsync does", .timeLimit(.minutes(1)))
+    func blockingComposeTakesAnInFlightSlot() throws {
+        final class Box: @unchecked Sendable { let done = DispatchSemaphore(value: 0); var result: Bool? }
+        let composer = try #require(DoviFelComposer())
+        let bl = try #require(Self.makeBuffer(width: 256, height: 256, fill: 0x8000))
+        let el = try #require(Self.makeBuffer(width: 128, height: 128, fill: 0x4000))
+        let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
+        for _ in 0..<DoviFelComposer.maxFramesInFlight { composer.acquireSlot() }
+
+        let box = Box()
+        Thread.detachNewThread {
+            box.result = composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 1) != nil
+            box.done.signal()
+        }
+        #expect(box.done.wait(timeout: .now() + 0.3) == .timedOut, "compose ran without holding an in-flight slot")
+        composer.releaseSlot()
+        #expect(box.done.wait(timeout: .now() + 10) == .success)
+        #expect(box.result == true)
+        for _ in 1..<DoviFelComposer.maxFramesInFlight { composer.releaseSlot() }
+    }
+
+    @Test("composeAsync matches the blocking compose bit for bit")
+    func asyncMatchesSync() async throws {
+        let composer = try #require(DoviFelComposer())
+        guard let bl = Self.makeBuffer(width: 256, height: 256, fill: 0x8000),
+              let el = Self.makeBuffer(width: 128, height: 128, fill: 0x4000) else { return }
+        let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
+
+        guard let syncOut = composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 7) else {
+            Issue.record("blocking compose returned nil")
+            return
+        }
+        let expected = Self.lumaWords(syncOut)
+
+        let got: [UInt16] = await withCheckedContinuation { cont in
+            composer.composeAsync(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 7) { out in
+                cont.resume(returning: out.map { Self.lumaWords($0) } ?? [])
+            }
+        }
+
+        #expect(!expected.isEmpty)
+        #expect(got == expected)
+    }
+
+    @Test("every composeAsync call completes exactly once, and no more than maxFramesInFlight are outstanding",
+          .timeLimit(.minutes(1)))
+    func completionsAreExactlyOnceAndBounded() async throws {
+        let composer = try #require(DoviFelComposer())
+        guard let bl = Self.makeBuffer(width: 256, height: 256, fill: 0x8000),
+              let el = Self.makeBuffer(width: 128, height: 128, fill: 0x4000) else { return }
+        let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
+
+        let frames = 40
+        let counter = Counter()
+        // Issued from this thread the way the decoder issues them: the semaphore
+        // inside composeAsync is what stops the loop from running away, so a
+        // deadlock or a lost completion hangs here rather than passing quietly.
+        //
+        // The semaphore bounds compositions on the GPU, and the slot is released
+        // when the command buffer retires rather than when the completion has
+        // run, so "issued minus completed" is looser than the semaphore's value:
+        // it also covers the call entering `wait` and the retired frames sitting
+        // on the delivery queue. What this asserts is that backpressure exists at
+        // all - without it the loop runs to `frames` before anything completes.
+        //
+        // The loop runs on a thread of its own: `composeAsync` parks in a semaphore, which the
+        // `.timeLimit` trait cannot interrupt on the test's own thread.
+        let bound = DoviFelComposer.maxFramesInFlight * 2 + 1
+        let buffers = Buffers(bl: bl, el: el)
+        Thread.detachNewThread {
+            for i in 0..<frames {
+                counter.issue()
+                composer.composeAsync(baseBuffer: buffers.bl, enhancementBuffer: buffers.el, params: params, frameIndex: UInt32(i)) { out in
+                    counter.record(nonNil: out != nil)
+                }
+            }
+        }
+
+        try await waitFor { counter.completed == frames }
+        #expect(counter.completed == frames)
+        #expect(counter.nonNil == frames)
+        #expect(counter.peakOutstanding <= bound)
+    }
+
+    /// The decoder calls `composeAsync` with its own recursive lock held, and the
+    /// completion takes that same lock to deliver in order. Metal runs completion
+    /// handlers on ONE serial queue, so a handler that blocks on the caller's lock
+    /// also stops every later handler - including the `inFlight.signal()` the
+    /// blocked caller is waiting for. On device that deadlocked after about ten
+    /// seconds of playback: the demux thread parked inside the decoder, packets
+    /// pinned, `enq=+0`, and the session still reporting `rendering`.
+    ///
+    /// The completion takes the same lock the issuing side holds across the call.
+    /// That is what the real one does (it hands the frame to the display layer),
+    /// and a `composeAsync` that waits for its completion while the caller holds
+    /// the lock deadlocks regardless of timing.
+    @Test("composeAsync makes progress while the caller holds a lock the completion also needs",
+          .timeLimit(.minutes(1)))
+    func doesNotDeadlockAgainstTheCallersLock() async throws {
+        let composer = try #require(DoviFelComposer())
+        guard let bl = Self.makeBuffer(width: 256, height: 256, fill: 0x8000),
+              let el = Self.makeBuffer(width: 128, height: 128, fill: 0x4000) else { return }
+        let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
+
+        let lock = NSRecursiveLock()
+        let counter = Counter()
+        let frames = 24
+        // Synchronous, on a thread of its own: `NSRecursiveLock.lock()` is unavailable from an
+        // async context, a lock held across the call is the whole point here, and a deadlock must
+        // park that thread rather than the test's, so the `.timeLimit` trait can report it.
+        let buffers = Buffers(bl: bl, el: el)
+        // At most three compositions outstanding, as the decoder's own in-flight limit does: it keeps
+        // the output pool from running dry (a nil output) without pacing by the wall clock.
+        let inFlight = DispatchSemaphore(value: 3)
+        @Sendable func issueUnderLock() {
+            for i in 0..<frames {
+                inFlight.wait()
+                lock.lock()
+                counter.issue()
+                composer.composeAsync(baseBuffer: buffers.bl, enhancementBuffer: buffers.el,
+                                      params: params, frameIndex: UInt32(i)) { out in
+                    lock.lock()
+                    counter.record(nonNil: out != nil)
+                    lock.unlock()
+                    inFlight.signal()
+                }
+                lock.unlock()
+            }
+        }
+        Thread.detachNewThread { issueUnderLock() }
+
+        try await waitFor { counter.completed == frames }
+        #expect(counter.completed == frames)
+        #expect(counter.nonNil == frames)
+    }
+
+    /// Hands the test's two buffers to the issuing thread; nothing else touches them meanwhile.
+    private struct Buffers: @unchecked Sendable {
+        let bl: CVPixelBuffer
+        let el: CVPixelBuffer
+    }
+
+    /// Tracks completions and, from the issuing side's point of view, how many
+    /// compositions were in flight at once.
+    private final class Counter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _completed = 0
+        private var _nonNil = 0
+        private var _issued = 0
+        private var _peak = 0
+
+        var completed: Int { lock.lock(); defer { lock.unlock() }; return _completed }
+        var nonNil: Int { lock.lock(); defer { lock.unlock() }; return _nonNil }
+        var peakOutstanding: Int { lock.lock(); defer { lock.unlock() }; return _peak }
+
+        func issue() {
+            lock.lock(); _issued += 1; _peak = max(_peak, _issued - _completed); lock.unlock()
+        }
+
+        func record(nonNil: Bool) {
+            lock.lock(); _completed += 1; if nonNil { _nonNil += 1 }; lock.unlock()
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift b/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
new file mode 100644
index 000000000..412b635c0
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
@@ -0,0 +1,305 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+import Dovi
+@testable import AetherEngine
+
+/// Pins the RPU that rides on every composed frame of the dual-layer (FEL) route to libdovi mode 2.
+///
+/// The Metal composer has already applied the RPU's luma/chroma reshaping and added the residual, so the
+/// frame that reaches the display layer is the finished picture. The attached RPU therefore has to carry
+/// no mapping (mode 2 sets both curves to no-op, drops the EL/NLQ part) and keep the display metadata
+/// (L1/L2 and, on CM v4.0 sources, L3/L8/L9/L11/L254). Were it to keep the mapping (mode 5), the display
+/// side would reshape a second time on top of an already reshaped picture.
+///
+/// The path under test is `DoviRpuConverter.separateDualLayers` with a custom block source, whose
+/// `convertedRpu` is the RPU a composed frame carries (what `DoviDisplayMetadata.attach` takes).
+@Suite(.serialized)
+struct DoviComposedFrameRpuTests {
+
+    // MARK: - Fixture
+
+    /// dovi_tool's `fel_orig.bin` (MIT licence, Copyright quietvoid), a 384-byte Profile 7 FEL RPU: the
+    /// bytes after its 4-byte Annex-B start code, i.e. the unspec62 payload (0x19 prefix) in escaped form.
+    /// Embedded as hex; the 2-byte unspec62 NAL header (0x7C 0x01) is put back in `felNAL`.
+    /// Its luma curve is a 9-piece polynomial, chroma is MMR, and it carries NLQ parameters, so unlike a
+    /// Profile 8.1 RPU its mapping is not a no-op and mode 2 has something to neutralise.
+    static let felHex: String =
+        "1908090840613650ae20002008020080200802007f801ffc00ffc001fffa0000030100000300d0000008000006800000" +
+        "400000340000030200000301a000001000000d0000030080000068000004000003034000002000000a86d9e67b2f863e" +
+        "fc189e6029e98c06b8c566a7cd5f8dffcb6d8c39e38a9981b86ca6790f405f434cb7d80e9e04c349fd3bb77ec2cd5de3" +
+        "a147d44c0a2e8062164a029b5d59500ed38f58c46c4ec13a14582cff3023536d57bbb6e411483b92966413698fce6bc3" +
+        "1bd620fadd405bbef4643160b1f01bf2eefbf2a5e2f3ccb4abf3cc3983779e7568311b00480000400400400000401200" +
+        "0010010010000010048000040040040000072566000035ea2566f9fceb1c256644ca0000030100000300080000030008" +
+        "000003001c36224301860a5e308e051400000301a63e5affff000003000003000003000060200f80e1518030080059ca" +
+        "1200c028218df82580080061400002022a512088050000030002281150120c07d000020d60015eb8f29d8280"
+
+    static let felNAL: [UInt8] = {
+        var out: [UInt8] = [0x7C, 0x01]
+        var i = felHex.startIndex
+        while i < felHex.endIndex {
+            let j = felHex.index(i, offsetBy: 2)
+            out.append(UInt8(felHex[i..<j], radix: 16)!)
+            i = j
+        }
+        return out
+    }()
+
+    // MARK: - Production path
+
+    private static func hevcNAL(type: UInt8, payload: [UInt8]) -> [UInt8] { [UInt8(type << 1), 0x01] + payload }
+
+    private static func avcc(_ nals: [[UInt8]]) -> UnsafeMutablePointer<AVPacket> {
+        var bytes: [UInt8] = []
+        for n in nals {
+            let c = n.count
+            bytes += [UInt8((c >> 24) & 0xFF), UInt8((c >> 16) & 0xFF), UInt8((c >> 8) & 0xFF), UInt8(c & 0xFF)]
+            bytes += n
+        }
+        let pkt = av_packet_alloc()!
+        _ = av_new_packet(pkt, Int32(bytes.count))
+        bytes.withUnsafeBytes { _ = memcpy(pkt.pointee.data, $0.baseAddress, bytes.count) }
+        return pkt
+    }
+
+    /// What `separateDualLayers` does with one packet, flags included, and what it returns: the raw RPU
+    /// NAL and the converted one that a composed frame carries.
+    static func composedFrameRpu(source nal: [UInt8]) -> (raw: [UInt8], attached: [UInt8])? {
+        let pkt = avcc([hevcNAL(type: 1, payload: [0xAA, 0xBB]), nal, hevcNAL(type: 63, payload: [0xCC, 0xDD])])
+        defer { var p: UnsafeMutablePointer<AVPacket>? = pkt; av_packet_free(&p) }
+        return composedFrameRpu(packet: pkt)
+    }
+
+    static func composedFrameRpu(packet: UnsafeMutablePointer<AVPacket>) -> (raw: [UInt8], attached: [UInt8])? {
+        let r = DoviRpuConverter.separateDualLayers(packet, extractEL: true, useCustomBlockSource: true, extractParams: true)
+        var el = r.elPacket
+        trackedPacketFree(&el)
+        guard let raw = r.rpuData, let attached = r.convertedRpu else { return nil }
+        return (raw, attached)
+    }
+
+    /// The same conversion with another libdovi mode, for the guard test.
+    static func converted(_ nal: [UInt8], mode: UInt8) -> [UInt8]? {
+        nal.withUnsafeBufferPointer { buf -> [UInt8]? in
+            guard let rpu = DoviRpuGuard.parse(buf.baseAddress!, buf.count) else { return nil }
+            defer { dovi_rpu_free(rpu) }
+            guard dovi_convert_rpu_with_mode(rpu, mode) == 0, let out = dovi_write_unspec62_nalu(rpu) else { return nil }
+            defer { dovi_data_free(out) }
+            return [UInt8](UnsafeBufferPointer(start: out.pointee.data, count: out.pointee.len))
+        }
+    }
+
+    // MARK: - Snapshot of what libdovi reads back
+
+    struct Curve: Equatable {
+        var mappingIdc: UInt8
+        var pivots: [UInt16]
+        var hasPolynomial: Bool
+        var hasMMR: Bool
+        var polyOrderMinus1: [UInt64]
+        var polyCoefInt: [[Int64]]
+        var polyCoef: [[UInt64]]
+    }
+
+    struct Snapshot: Equatable {
+        var profile: UInt8
+        var elType: String?
+        var rpuFormat: UInt16
+        var disableResidual: Bool
+        var curves: [Curve]
+        var nlqMethodIdc: Int32
+        var hasNLQ: Bool
+        /// Scalar fields of the VDR DM data (everything but the extension blocks).
+        var dmScalars: [String]
+        /// Extension blocks by level, every field of every block.
+        var blocks: [String: [String]]
+
+        /// Both reshaping curves of every component are the identity polynomial: order 1, y = x.
+        var isIdentityMapping: Bool {
+            curves.count == 3 && curves.allSatisfy { c in
+                c.mappingIdc == 0 && c.hasPolynomial && !c.hasMMR
+                    && c.polyOrderMinus1.allSatisfy { $0 == 0 }
+                    && c.polyCoefInt.allSatisfy { $0 == [0, 1] }
+                    && c.polyCoef.allSatisfy { $0 == [0, 0] }
+            }
+        }
+
+        /// No residual: not a dual-layer RPU any more.
+        var carriesNoEnhancementLayer: Bool { !hasNLQ && elType == nil }
+    }
+
+    private static func dump<T>(_ v: T, skip: Set<String> = []) -> [String] {
+        Mirror(reflecting: v).children.compactMap { c in
+            guard let l = c.label, !skip.contains(l) else { return nil }
+            return "\(l)=\(c.value)"
+        }
+    }
+
+    private static func list<T>(_ list: UnsafePointer<UnsafePointer<T>?>?, _ n: Int) -> [[String]] {
+        guard let list else { return [] }
+        return (0..<n).compactMap { list[$0].map { dump($0.pointee) } }
+    }
+
+    static func snapshot(ofNAL nal: [UInt8]) -> Snapshot? {
+        nal.withUnsafeBufferPointer { buf -> Snapshot? in
+            guard let rpu = DoviRpuGuard.parse(buf.baseAddress!, buf.count) else { return nil }
+            defer { dovi_rpu_free(rpu) }
+            guard let hdr = dovi_rpu_get_header(rpu), let map = dovi_rpu_get_data_mapping(rpu),
+                  let dm = dovi_rpu_get_vdr_dm_data(rpu) else { return nil }
+            defer { dovi_rpu_free_header(hdr); dovi_rpu_free_data_mapping(map); dovi_rpu_free_vdr_dm_data(dm) }
+
+            var curves: [Curve] = []
+            for c in [map.pointee.curves.0, map.pointee.curves.1, map.pointee.curves.2] {
+                var poly = Curve(mappingIdc: c.mapping_idc,
+                                 pivots: c.pivots.data.map { Array(UnsafeBufferPointer(start: $0, count: c.pivots.len)) } ?? [],
+                                 hasPolynomial: c.polynomial != nil, hasMMR: c.mmr != nil,
+                                 polyOrderMinus1: [], polyCoefInt: [], polyCoef: [])
+                if let p = c.polynomial?.pointee {
+                    poly.polyOrderMinus1 = p.poly_order_minus1.data.map { Array(UnsafeBufferPointer(start: $0, count: p.poly_order_minus1.len)) } ?? []
+                    if let l = p.poly_coef_int.list {
+                        poly.polyCoefInt = (0..<p.poly_coef_int.len).map { i in
+                            l[i].flatMap { d in d.pointee.data.map { Array(UnsafeBufferPointer(start: $0, count: d.pointee.len)) } } ?? []
+                        }
+                    }
+                    if let l = p.poly_coef.list {
+                        poly.polyCoef = (0..<p.poly_coef.len).map { i in
+                            l[i].flatMap { d in d.pointee.data.map { Array(UnsafeBufferPointer(start: $0, count: d.pointee.len)) } } ?? []
+                        }
+                    }
+                }
+                curves.append(poly)
+            }
+
+            let d = dm.pointee.dm_data
+            var blocks: [String: [String]] = [:]
+            if let b = d.level1 { blocks["L1"] = dump(b.pointee) }
+            if d.level2.len > 0 { blocks["L2"] = list(d.level2.list, d.level2.len).flatMap { $0 } }
+            if let b = d.level3 { blocks["L3"] = dump(b.pointee) }
+            if let b = d.level4 { blocks["L4"] = dump(b.pointee) }
+            if let b = d.level5 { blocks["L5"] = dump(b.pointee) }
+            if let b = d.level6 { blocks["L6"] = dump(b.pointee) }
+            if d.level8.len > 0 { blocks["L8"] = list(d.level8.list, d.level8.len).flatMap { $0 } }
+            if let b = d.level9 { blocks["L9"] = dump(b.pointee) }
+            if d.level10.len > 0 { blocks["L10"] = list(d.level10.list, d.level10.len).flatMap { $0 } }
+            if let b = d.level11 { blocks["L11"] = dump(b.pointee) }
+            if let b = d.level254 { blocks["L254"] = dump(b.pointee) }
+            if let b = d.level255 { blocks["L255"] = dump(b.pointee) }
+
+            return Snapshot(profile: hdr.pointee.guessed_profile,
+                            elType: hdr.pointee.el_type.map { String(cString: $0) },
+                            rpuFormat: hdr.pointee.rpu_format,
+                            disableResidual: hdr.pointee.disable_residual_flag,
+                            curves: curves, nlqMethodIdc: map.pointee.nlq_method_idc,
+                            hasNLQ: map.pointee.nlq != nil,
+                            dmScalars: dump(dm.pointee, skip: ["dm_data"]), blocks: blocks)
+        }
+    }
+
+    /// The assertions every composed-frame RPU has to satisfy against the source it came from.
+    static func expectPinned(source: Snapshot, attached: Snapshot, label: String,
+                             sourceLocation: SourceLocation = #_sourceLocation) {
+        #expect(attached.profile == 8, "\(label): attached RPU is not Profile 8", sourceLocation: sourceLocation)
+        #expect(attached.carriesNoEnhancementLayer, "\(label): attached RPU still carries an EL/NLQ part", sourceLocation: sourceLocation)
+        #expect(attached.isIdentityMapping, "\(label): attached RPU keeps a non-identity mapping (a second reshape on the display side)", sourceLocation: sourceLocation)
+        #expect(Set(attached.blocks.keys) == Set(source.blocks.keys),
+                "\(label): extension levels changed, source \(source.blocks.keys.sorted()) attached \(attached.blocks.keys.sorted())", sourceLocation: sourceLocation)
+        for (level, fields) in source.blocks {
+            #expect(attached.blocks[level] == fields, "\(label): \(level) differs after conversion", sourceLocation: sourceLocation)
+        }
+        #expect(attached.dmScalars == source.dmScalars, "\(label): VDR DM scalars differ after conversion", sourceLocation: sourceLocation)
+    }
+
+    // MARK: - Synthetic
+
+    @Test("The fixture is a Profile 7 FEL RPU with L1/L2 display metadata")
+    func fixtureIsFel() throws {
+        let s = try #require(Self.snapshot(ofNAL: Self.felNAL))
+        #expect(s.profile == 7)
+        #expect(s.elType == "FEL")
+        #expect(s.hasNLQ)
+        #expect(!s.isIdentityMapping)
+        #expect(s.blocks["L1"] != nil)
+        #expect(s.blocks["L2"] != nil)
+    }
+
+    @Test("The RPU attached to a composed frame has no-op curves, no EL, and the source's display metadata")
+    func attachedRpuIsMode2() throws {
+        let source = try #require(Self.snapshot(ofNAL: Self.felNAL))
+        let (raw, attached) = try #require(Self.composedFrameRpu(source: Self.felNAL))
+        #expect(raw == Self.felNAL)
+        #expect(attached.prefix(2).elementsEqual([0x7C, 0x01]), "complete unspec62 NAL, as DoviDisplayMetadata.attach expects")
+        let out = try #require(Self.snapshot(ofNAL: attached))
+        Self.expectPinned(source: source, attached: out, label: "fel_orig")
+    }
+
+    // MARK: - Real file (CM v4.0)
+
+    static let cmv40Clip = DoviFelRealFileTests.fixtures[2]
+    static let packetsToCheck = 240
+
+    /// The mapping of this clip's RPUs is already the identity polynomial, so it proves the display metadata
+    /// survives (CM v4.0 L3/L8/L9/L254 included) but not the mode-2-vs-5 difference; the fixture above does.
+    /// The RPUs of the first `packetsToCheck` video packets of the clip, through the production path.
+    @Test("Real CM v4.0 clip: every composed-frame RPU is no-op mapped and keeps L1/L2/L3/L8/L9/L254 (and every level the source has)",
+          .enabled(if: DoviFelRealFileTests.available(DoviComposedFrameRpuTests.cmv40Clip), DoviFelRealFileTests.needsClips))
+    func realClipKeepsCmv40() throws {
+        let demuxer = Demuxer()
+        try demuxer.open(url: DoviFelRealFileTests.url(Self.cmv40Clip))
+        defer { demuxer.close() }
+        let idx = Int32(demuxer.videoStreamIndex)
+
+        var checked = 0, nonIdentitySources = 0
+        var levelsBefore = Set<String>(), levelsAfter = Set<String>()
+        var packets = 0
+        while packets < Self.packetsToCheck, let pkt = try demuxer.readPacket() {
+            defer {
+                av_packet_unref(pkt)
+                var o: UnsafeMutablePointer<AVPacket>? = pkt
+                trackedPacketFree(&o)
+            }
+            guard pkt.pointee.stream_index == idx else { continue }
+            packets += 1
+            guard let (raw, attached) = Self.composedFrameRpu(packet: pkt) else { continue }
+            let source = try #require(Self.snapshot(ofNAL: raw))
+            let out = try #require(Self.snapshot(ofNAL: attached))
+            Self.expectPinned(source: source, attached: out, label: "packet \(packets)")
+            levelsBefore.formUnion(source.blocks.keys)
+            levelsAfter.formUnion(out.blocks.keys)
+            if !source.isIdentityMapping { nonIdentitySources += 1 }
+            checked += 1
+        }
+        print("DOVI-REAL packets=\(packets) rpus=\(checked) sourceNonIdentity=\(nonIdentitySources) levelsBefore=\(levelsBefore.sorted()) levelsAfter=\(levelsAfter.sorted())")
+        #expect(checked > 0)
+        // `expectPinned` already compares every level the source has. This pins that the clip really is
+        // CM v4.0 (so the check is not vacuous) and that those levels came out the other side. The clip
+        // has no L10/L11 (nothing to drop); `levelsAfter == levelsBefore` is asserted for whatever it has.
+        for level in ["L1", "L2", "L3", "L8", "L9", "L254"] {
+            #expect(levelsBefore.contains(level), "clip no longer carries \(level); the check would be vacuous")
+            #expect(levelsAfter.contains(level), "\(level) did not survive")
+        }
+        #expect(levelsAfter == levelsBefore)
+    }
+
+    // MARK: - Guard: the assertions can tell mode 2 from modes that keep the mapping
+
+    @Test("Mode 5 keeps the mapping and the EL, so the pinned assertions would catch a regression to it")
+    func mode5FailsThePin() throws {
+        let source = try #require(Self.snapshot(ofNAL: Self.felNAL))
+        let m5 = try #require(Self.converted(Self.felNAL, mode: 5))
+        let kept = try #require(Self.snapshot(ofNAL: m5))
+        #expect(kept.profile == 7)
+        #expect(!kept.carriesNoEnhancementLayer)
+        #expect(!kept.isIdentityMapping, "mode 5 must not satisfy the identity-mapping assertion, or the pin proves nothing")
+        // The DM survives mode 5 as well, so the mapping assertions are what separate the two modes.
+        #expect(kept.blocks == source.blocks)
+    }
+
+    @Test("Mode 0 (no conversion) fails the pin too")
+    func mode0FailsThePin() throws {
+        let m0 = try #require(Self.converted(Self.felNAL, mode: 0))
+        let kept = try #require(Self.snapshot(ofNAL: m0))
+        #expect(!kept.isIdentityMapping)
+        #expect(!kept.carriesNoEnhancementLayer)
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
new file mode 100644
index 000000000..47396bdce
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
@@ -0,0 +1,150 @@
+import Testing
+import Foundation
+import Dovi
+@testable import AetherEngine
+
+/// The existing RPU fuzz mostly dies at the CRC check. This one repairs the CRC after mutating the
+/// payload (and re-applies emulation prevention), so the mutated RPU actually reaches libdovi's
+/// parser, which is built panic=abort: any upstream panic here would kill the process.
+struct DoviCrcValidFuzzTests {
+
+    private static let crcTable: [UInt32] = (0..<256).map { i in
+        var c = UInt32(i) << 24
+        for _ in 0..<8 { c = c & 0x8000_0000 != 0 ? (c << 1) ^ 0x04C1_1DB7 : c << 1 }
+        return c
+    }
+
+    static func escape(_ u: [UInt8]) -> [UInt8] {
+        var out = [UInt8](), zeros = 0
+        for (i, b) in u.enumerated() {
+            if zeros >= 2 && b <= 3 && i >= 2 { out.append(3); zeros = 0 }
+            out.append(b)
+            zeros = b == 0 ? zeros + 1 : 0
+        }
+        return out
+    }
+
+    /// Mutates payload bytes of an unescaped RPU and fixes up the CRC.
+    static func mutateValid(_ u: [UInt8], _ rng: inout DoviFelFuzzTests.RNG) -> [UInt8] {
+        var b = u
+        let tailAt = b.count - 5
+        guard tailAt > 4 else { return b }
+        switch rng.below(4) {
+        case 0: for _ in 0..<(1 + rng.below(4)) { b[3 + rng.below(tailAt - 3)] ^= UInt8(1 << rng.below(8)) }
+        case 1: b[3 + rng.below(tailAt - 3)] = UInt8(truncatingIfNeeded: rng.next())
+        case 2:  // concentrate on the header/mapping region, where the syntax branches
+            for _ in 0..<(1 + rng.below(3)) { b[3 + rng.below(min(40, tailAt - 3))] ^= UInt8(1 << rng.below(8)) }
+        default:
+            let start = 3 + rng.below(tailAt - 3), len = 1 + rng.below(8)
+            for i in start..<min(tailAt, start + len) { b[i] = rng.below(2) == 0 ? 0xFF : 0x00 }
+        }
+        var crc: UInt32 = 0xFFFF_FFFF
+        for i in 3..<tailAt { crc = (crc << 8) ^ crcTable[Int((crc >> 24) ^ UInt32(b[i]))] }
+        b[tailAt] = UInt8(crc >> 24); b[tailAt + 1] = UInt8((crc >> 16) & 0xFF)
+        b[tailAt + 2] = UInt8((crc >> 8) & 0xFF); b[tailAt + 3] = UInt8(crc & 0xFF)
+        return b
+    }
+
+    /// Found by `crcValidMutations` (fixture 1): a CRC-valid RPU whose partition count is a 41-zero exp-Golomb
+    /// code. libdovi parses it and then reads a linear-interp flag (abort); the guard must follow the code past 32 zeros.
+    static let crcBytesReachLinearFlag = "7c011908090840613650ae20002008020080200802007f801ffc00ffc000ff00ff00000300000300d012811f6bf799ff6bf740000033fed7ee80000067fdafdd00000300cffb5fba000003019ff6bf74000003033fed7ee8000003029cdbf713e290d652833715954c126341284d15cc741520f02a42e5370f5ae1a762d5a57ca0430473c965dc73e4d29f0f297d65394bee5e94a7d40d35adc59e1a36d3f34ee2eb989b55a704d10a2f93177b914f4592097648f189d4419cd595ec49e0ecb7c041984ff7b4f97998e4d1ef509fe7b00ee182b2675ba33e73521f46cfaf3860d29087e92b30b43b2437b1006000004010004000004018000010040010000010060000040100040000072566000035ea2566f9fceb1c256644ca0000030100000300080000030008000003001c36224301860a5e308e051400000301a63e5affff000003000003000003000060207dce0151c030080002300e80c028217c58006d48008351000180580f0010010011a73442000404044129100a000003000460230024183e8000c828340ab0b02e561a80"
+
+    @Test("the guard reads exp-Golomb codes as long as libdovi does")
+    func guardCoversCrcBytes() throws {
+        let bytes = stride(from: 0, to: Self.crcBytesReachLinearFlag.count, by: 2).map {
+            UInt8(Self.crcBytesReachLinearFlag.dropFirst($0).prefix(2), radix: 16)!
+        }
+        #expect(bytes.withUnsafeBufferPointer { DoviRpuGuard.crcIsValid($0.baseAddress!, $0.count) })
+        #expect(bytes.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) } == nil)
+    }
+
+    /// RPUs built in the test source (`DoviRpuGuardTests.craft`), so the fuzz runs wherever the suite does:
+    /// a Profile 7 FEL RPU with a two-piece luma curve and MMR chroma, a MEL one whose curves are all
+    /// polynomial, and a MEL one with MMR chroma. A MEL RPU keeps its mapping through the mode 2
+    /// conversion, so these reach the writer's curve code; an FEL RPU's mapping is dropped there.
+    static let syntheticSeeds: [(name: String, nal: [UInt8])] = [
+        ("synthetic FEL", DoviRpuGuardTests.craft(pieces: [[.polynomial, .polynomial], [.mmr], [.mmr]], residual: .fel)),
+        ("synthetic MEL, polynomial", DoviRpuGuardTests.craft(pieces: [[.polynomial], [.polynomial], [.polynomial]], residual: .mel)),
+        ("synthetic MEL, MMR chroma", DoviRpuGuardTests.craft(pieces: [[.polynomial], [.mmr], [.mmr]], residual: .mel)),
+    ]
+
+    /// `AETHER_FUZZ_N` overrides the iteration count; the default is what a CI run can afford per seed
+    /// for the synthetic seeds and what an unattended soak is worth for a clip.
+    static func iterations(default fallback: Int) -> Int {
+        Int(ProcessInfo.processInfo.environment["AETHER_FUZZ_N"] ?? "") ?? fallback
+    }
+
+    /// Mutates `nal` with the CRC repaired every time, and pushes whatever the guard lets through the
+    /// way production does: parse, the composer's parameter walk, then the mode 2 conversion and the
+    /// write (`DoviRpuConverter.convertedUnspec62`). libdovi aborts the process on a panic, so
+    /// getting to the end is the assertion.
+    static func fuzz(seed nal: [UInt8], label: String, rngSeed: UInt64, iterations: Int) throws {
+        try DoviFelFuzzTests.expectLibdoviAccepts(nal)
+        let u = try #require(nal.withUnsafeBufferPointer { DoviRpuGuard.verifiedUnescaped($0.baseAddress!, $0.count) })
+        let env = ProcessInfo.processInfo.environment
+        var rng = DoviFelFuzzTests.RNG(state: rngSeed + (UInt64(env["AETHER_FUZZ_SEED"] ?? "") ?? 0) << 16)
+        var reached = 0, guarded = 0, parsed = 0, written = 0
+        for _ in 0..<iterations {
+            let m = Self.escape(Self.mutateValid(u, &rng))
+            guard m.withUnsafeBufferPointer({ DoviRpuGuard.crcIsValid($0.baseAddress!, $0.count) }) else { continue }
+            reached += 1
+            if let dump = env["AETHER_FUZZ_DUMP"] { try? Data(m).write(to: URL(fileURLWithPath: dump + label)) }
+            guard let rpu = m.withUnsafeBufferPointer({ DoviRpuGuard.parse($0.baseAddress!, $0.count) }) else { guarded += 1; continue }
+            defer { dovi_rpu_free(rpu) }
+            if let p = DoviFelComposer.parseRpuParameters(rpu: rpu) {
+                parsed += 1
+                for poly in [p.polyY, p.polyCb, p.polyCr] {
+                    var q = poly; q.clampToCapacity()
+                    #expect(q.numPivots <= UInt32(DoviPolynomialParams.maxPivots))
+                }
+            }
+            if let out = DoviRpuConverter.convertedUnspec62(rpu) {
+                written += 1
+                dovi_data_free(out)
+            }
+        }
+        print("[fuzz-crc] \(label): \(reached) CRC-valid mutants, \(guarded) rejected by guard/libdovi, \(parsed) parsed, \(written) converted and written")
+        #expect(reached > iterations * 3 / 4)
+        #expect(written > 0, "no mutant survived to the writer: the seed is not exercising it")
+    }
+
+    @Test("a CRC-valid mutated synthetic RPU never aborts libdovi in parse, convert or write",
+          .timeLimit(.minutes(5)), arguments: DoviCrcValidFuzzTests.syntheticSeeds.indices)
+    func crcValidMutationsOfSyntheticSeeds(index: Int) throws {
+        let seed = Self.syntheticSeeds[index]
+        try Self.fuzz(seed: seed.nal, label: seed.name, rngSeed: 0x5E0 + UInt64(index),
+                      iterations: Self.iterations(default: 20000))
+    }
+
+    static func fuzzClip(_ fixture: Int) throws {
+        let seed = try #require(try DoviFelFuzzTests.seed(index: fixture))
+        try fuzz(seed: seed.rpu, label: "fixture \(fixture)", rngSeed: 0xC4C + UInt64(fixture),
+                 iterations: iterations(default: 20000))
+    }
+
+    @Test("a CRC-valid mutated RPU from the first clip never aborts libdovi in parse, convert or write",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(30)))
+    func crcValidMutationsClip0() throws { try Self.fuzzClip(0) }
+
+    @Test("a CRC-valid mutated RPU from the second clip never aborts libdovi in parse, convert or write",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[1]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(30)))
+    func crcValidMutationsClip1() throws { try Self.fuzzClip(1) }
+
+    @Test("a CRC-valid mutated RPU from the third clip never aborts libdovi in parse, convert or write",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(30)))
+    func crcValidMutationsClip2() throws { try Self.fuzzClip(2) }
+}
+
+extension DoviCrcValidFuzzTests {
+    @Test("replay a dumped RPU", .enabled(if: ProcessInfo.processInfo.environment["AETHER_FUZZ_REPLAY"] != nil))
+    func replay() throws {
+        let d = [UInt8](try Data(contentsOf: URL(fileURLWithPath: ProcessInfo.processInfo.environment["AETHER_FUZZ_REPLAY"]!)))
+        let u = d.withUnsafeBufferPointer { DoviRpuGuard.verifiedUnescaped($0.baseAddress!, $0.count) }
+        print("[replay] crc ok \(u != nil), guard says unimplemented: \(u.map { DoviRpuGuard.reachesUnimplementedPath($0) } ?? false)")
+        let r = d.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        print("[replay] parsed \(r != nil)")
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift b/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift
new file mode 100644
index 000000000..30b447c4d
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift
@@ -0,0 +1,99 @@
+import Testing
+import Foundation
+import CoreVideo
+import IOSurface
+@testable import AetherEngine
+
+/// `DoviDisplayMetadata`: the RPU payload form, and the two attachments tvOS's compositor reads, on the
+/// CVBuffer and on its backing IOSurface (where tvOS actually reads them).
+struct DoviDisplayMetadataTests {
+
+    private static let nal: [UInt8] = [0x7C, 0x01, 0x19, 0x08, 0x09, 0xAA, 0xBB]
+
+    private static func makeBuffer() throws -> CVPixelBuffer {
+        var buffer: CVPixelBuffer?
+        let status = CVPixelBufferCreate(
+            kCFAllocatorDefault, 64, 64, kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+            [kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary, &buffer)
+        #expect(status == kCVReturnSuccess)
+        let b = try #require(buffer)
+        #expect(CVPixelBufferGetIOSurface(b) != nil, "the buffer must be IOSurface-backed")
+        return b
+    }
+
+    private static func surfaceValue(_ b: CVPixelBuffer, _ key: String) -> CFTypeRef? {
+        guard let s = CVPixelBufferGetIOSurface(b)?.takeUnretainedValue() else { return nil }
+        return IOSurfaceCopyValue(s, key as CFString)
+    }
+
+    // MARK: payload(fromNAL:)
+
+    @Test("payload strips the 0x7C 0x01 NAL header and leaves emulation-prevention bytes alone")
+    func payloadStripsHeader() {
+        let withEpb: [UInt8] = [0x7C, 0x01, 0x19, 0x00, 0x00, 0x03, 0x01]
+        #expect(DoviDisplayMetadata.payload(fromNAL: withEpb) == Data([0x19, 0x00, 0x00, 0x03, 0x01]))
+        #expect(DoviDisplayMetadata.payload(fromNAL: Self.nal) == Data([0x19, 0x08, 0x09, 0xAA, 0xBB]))
+    }
+
+    @Test("payload passes a header-less RPU (leading 0x19) through unchanged")
+    func payloadPassesThroughHeaderless() {
+        let raw: [UInt8] = [0x19, 0x08, 0x09, 0x01]
+        #expect(DoviDisplayMetadata.payload(fromNAL: raw) == Data(raw))
+    }
+
+    @Test("payload returns nil for nil, for too-short input and for anything else")
+    func payloadRejectsOthers() {
+        #expect(DoviDisplayMetadata.payload(fromNAL: nil) == nil)
+        #expect(DoviDisplayMetadata.payload(fromNAL: []) == nil)
+        #expect(DoviDisplayMetadata.payload(fromNAL: [0x7C, 0x01]) == nil)
+        #expect(DoviDisplayMetadata.payload(fromNAL: [0x40, 0x01, 0x19, 0x00]) == nil)
+        #expect(DoviDisplayMetadata.payload(fromNAL: [0x7C, 0x02, 0x19, 0x00]) == nil)
+        #expect(DoviDisplayMetadata.payload(fromNAL: [0x18, 0x00, 0x00]) == nil)
+    }
+
+    // MARK: attach
+
+    @Test("attach sets the RPU as CFData and the compatibility ID as a CFString, on the CVBuffer and the IOSurface")
+    func attachSetsBothKeys() throws {
+        let b = try Self.makeBuffer()
+        DoviDisplayMetadata.attach(rpuNAL: Self.nal, to: b)
+
+        let rpu = try #require(CVBufferCopyAttachment(b, DoviDisplayMetadata.rpuDataKey as CFString, nil))
+        #expect(CFGetTypeID(rpu) == CFDataGetTypeID())
+        #expect((rpu as? Data) == Data([0x19, 0x08, 0x09, 0xAA, 0xBB]))
+
+        // tvOS parses this with CFStringGetIntValue: a CFNumber here aborts backboardd.
+        let id = try #require(CVBufferCopyAttachment(b, DoviDisplayMetadata.compatibilityIDKey as CFString, nil))
+        #expect(CFGetTypeID(id) == CFStringGetTypeID(), "compatibility ID must be a CFString")
+        #expect((id as? String) == "1")
+
+        // Mirrored onto the backing surface, with the same types.
+        let surfaceRpu = try #require(Self.surfaceValue(b, DoviDisplayMetadata.rpuDataKey))
+        #expect(CFGetTypeID(surfaceRpu) == CFDataGetTypeID())
+        let surfaceId = try #require(Self.surfaceValue(b, DoviDisplayMetadata.compatibilityIDKey))
+        #expect(CFGetTypeID(surfaceId) == CFStringGetTypeID())
+    }
+
+    @Test("attach(nil) clears both keys from the CVBuffer and from the backing IOSurface")
+    func attachNilClearsEverywhere() throws {
+        let b = try Self.makeBuffer()
+        DoviDisplayMetadata.attach(rpuNAL: Self.nal, to: b)
+        #expect(Self.surfaceValue(b, DoviDisplayMetadata.rpuDataKey) != nil, "precondition: mirrored to the surface")
+
+        DoviDisplayMetadata.attach(rpuNAL: nil, to: b)
+
+        #expect(CVBufferCopyAttachment(b, DoviDisplayMetadata.rpuDataKey as CFString, nil) == nil)
+        #expect(CVBufferCopyAttachment(b, DoviDisplayMetadata.compatibilityIDKey as CFString, nil) == nil)
+        #expect(Self.surfaceValue(b, DoviDisplayMetadata.rpuDataKey) == nil, "stale RPU left on the IOSurface")
+        #expect(Self.surfaceValue(b, DoviDisplayMetadata.compatibilityIDKey) == nil, "stale compatibility ID left on the IOSurface")
+    }
+
+    @Test("an unusable NAL clears a previous tenant's attachments too")
+    func attachUnusableClears() throws {
+        let b = try Self.makeBuffer()
+        DoviDisplayMetadata.attach(rpuNAL: Self.nal, to: b)
+        DoviDisplayMetadata.attach(rpuNAL: [0x00, 0x00, 0x00], to: b)
+        #expect(CVBufferCopyAttachment(b, DoviDisplayMetadata.rpuDataKey as CFString, nil) == nil)
+        #expect(Self.surfaceValue(b, DoviDisplayMetadata.rpuDataKey) == nil)
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviDitherTests.swift b/Tests/AetherEngineTests/DoviDitherTests.swift
new file mode 100644
index 000000000..ac2b64f2b
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviDitherTests.swift
@@ -0,0 +1,291 @@
+import Testing
+import Foundation
+import CoreVideo
+import Metal
+@testable import AetherEngine
+
+/// S4 from ``DoviFelMathTests``' list:
+/// the ordered dither is unbiased at the output, and Cb and Cr do not share a
+/// dither pattern.
+///
+/// These run the real `dovi_compose_luma` / `dovi_compose_chroma` kernels and
+/// read the planes back, so they fail if the shader stops matching the claim.
+///
+/// What they deliberately do *not* lock is the half-step centring in
+/// `dovi_dither`. At `vdr_scale <= 64` the raw table `k/64` and the centred table
+/// `(k + 0.5)/64` select exactly the same cells, so at the 10-bit-into-12-bit
+/// scale of 4 that every Dolby Vision stream uses, the two are bit-identical and
+/// no end-to-end test can tell them apart. The centring matters only above that,
+/// and the reason it is there is written out in the shader.
+struct DoviDitherTests {
+
+    static let width = 64
+    static let height = 64
+
+    static func makeBuffer(width: Int, height: Int) -> CVPixelBuffer? {
+        var buffer: CVPixelBuffer?
+        CVPixelBufferCreate(
+            kCFAllocatorDefault, width, height,
+            kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+            [
+                kCVPixelBufferMetalCompatibilityKey: true,
+                kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary
+            ] as CFDictionary,
+            &buffer
+        )
+        return buffer
+    }
+
+    static func fillPlane(_ buffer: CVPixelBuffer, plane: Int, components: Int, value: Int) {
+        CVPixelBufferLockBaseAddress(buffer, [])
+        defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+        guard let base = CVPixelBufferGetBaseAddressOfPlane(buffer, plane) else { return }
+        let bytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(buffer, plane)
+        let w = CVPixelBufferGetWidthOfPlane(buffer, plane)
+        let h = CVPixelBufferGetHeightOfPlane(buffer, plane)
+        for row in 0..<h {
+            let rowPtr = (base + row * bytesPerRow).assumingMemoryBound(to: UInt16.self)
+            for column in 0..<(w * components) {
+                rowPtr[column] = UInt16(value << 6)
+            }
+        }
+    }
+
+    /// The 8x8 Bayer cell at the plane's origin, one component of it.
+    static func readCell(_ buffer: CVPixelBuffer, plane: Int, components: Int, component: Int) -> [Int] {
+        CVPixelBufferLockBaseAddress(buffer, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(buffer, .readOnly) }
+        guard let base = CVPixelBufferGetBaseAddressOfPlane(buffer, plane) else { return [] }
+        let bytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(buffer, plane)
+        var out: [Int] = []
+        out.reserveCapacity(64)
+        for row in 0..<8 {
+            let rowPtr = (base + row * bytesPerRow).assumingMemoryBound(to: UInt16.self)
+            for column in 0..<8 {
+                out.append(Int(rowPtr[column * components + component] >> 6))
+            }
+        }
+        return out
+    }
+
+    /// A flat curve: `pred_norm` is the constant `c0`, whatever the input code.
+    /// Used to drive one exact VDR value onto the whole plane, so the only thing
+    /// varying across the cell is the dither.
+    static func constantCurve(c0: Int32) -> DoviPolynomialParams {
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 2
+        poly.pivots[0] = 0
+        poly.pivots[1] = 1023
+        poly.method[0] = DoviMapping.polynomial.rawValue
+        poly.order[0] = 1
+        poly.coef[0] = [c0, 0, 0]
+        poly.coefShift[0] = 23
+        return poly
+    }
+
+    /// Smallest `c0` whose denormalised VDR value is exactly `vdr`, and the value
+    /// the kernel will actually compute from it.
+    static func curveHitting(vdr: Int, blMax: Int, vdrScale: Int) -> (curve: DoviPolynomialParams, vdr: Int) {
+        // Curves are normalised by 2^bits (blMax + 1) both ways.
+        let blNorm = blMax + 1
+        let norm = Double(vdr) / (Double(blNorm) * Double(vdrScale))
+        let fixed = Int32((norm * Double(1 << 23)).rounded())
+        let exact = Double(fixed) / Double(1 << 23)
+        let produced = Int((exact * Double(blNorm) * Double(vdrScale)).rounded(.toNearestOrEven))
+        return (constantCurve(c0: fixed), produced)
+    }
+
+    static func compose(
+        lumaCurve: DoviPolynomialParams,
+        cbCurve: DoviPolynomialParams,
+        crCurve: DoviPolynomialParams,
+        dither: DoviDither,
+        frameIndex: UInt32
+    ) -> CVPixelBuffer? {
+        guard let composer = DoviFelComposer(),
+              let bl = makeBuffer(width: width, height: height),
+              let el = makeBuffer(width: width / 2, height: height / 2) else { return nil }
+        fillPlane(bl, plane: 0, components: 1, value: 512)
+        fillPlane(bl, plane: 1, components: 2, value: 512)
+        fillPlane(el, plane: 0, components: 1, value: 512)
+        fillPlane(el, plane: 1, components: 2, value: 512)
+
+        var params = DoviMetalParams()
+        params.ditherMode = dither
+        params.flags = [.disableResidual]
+        params.polyY = lumaCurve
+        params.polyCb = cbCurve
+        params.polyCr = crCurve
+        return composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: frameIndex)
+    }
+
+    // MARK: - Unbiased
+
+    @Test("dither is unbiased: the 8x8 cell mean is the exact pre-rounding value, at every quarter-code residue")
+    func ditherMeanMatchesExactValue() throws {
+        // vdr_scale is 4, so the value reaching the rounding step is k + r/4.
+        // r = 0 is the case where rounding is exact and dither must not move it;
+        // r = 2 is the case a flat 0.5 bias resolves entirely the wrong way for
+        // half the levels, which is what dither exists to fix.
+        for r in 0..<4 {
+            let target = 500 * 4 + r
+            let (curve, vdr) = Self.curveHitting(vdr: target, blMax: 1023, vdrScale: 4)
+            #expect(vdr == target, "curve construction missed the target VDR value: \(vdr) != \(target)")
+
+            guard let dst = Self.compose(
+                lumaCurve: curve,
+                cbCurve: Self.constantCurve(c0: 0),
+                crCurve: Self.constantCurve(c0: 0),
+                dither: .bayer8x8,
+                frameIndex: 0
+            ) else {
+                Issue.record("Composer returned nil")
+                return
+            }
+
+            let cell = Self.readCell(dst, plane: 0, components: 1, component: 0)
+            #expect(cell.count == 64)
+            let mean = Double(cell.reduce(0, +)) / 64.0
+            let exact = Double(vdr) / 4.0
+            #expect(abs(mean - exact) < 1e-9,
+                    "residue \(r): dithered cell mean \(mean) is not the exact value \(exact)")
+
+            // Only two output levels may appear, and they must bracket the value.
+            let levels = Set(cell).sorted()
+            #expect(levels.count <= 2, "residue \(r): dither produced \(levels.count) levels: \(levels)")
+            for level in levels {
+                #expect(abs(Double(level) - exact) < 1.0,
+                        "residue \(r): level \(level) is more than a code from \(exact)")
+            }
+        }
+    }
+
+    @Test("the per-frame inversion does not bias either frame of the pair")
+    func frameInversionIsUnbiased() throws {
+        // Residue 1: three quarters of the cell stays low, so an inversion that
+        // drew from a shifted set of offsets would show up as a mean shift here.
+        let (curve, vdr) = Self.curveHitting(vdr: 500 * 4 + 1, blMax: 1023, vdrScale: 4)
+        var means: [Double] = []
+        for frame in [UInt32(0), UInt32(1)] {
+            guard let dst = Self.compose(
+                lumaCurve: curve,
+                cbCurve: Self.constantCurve(c0: 0),
+                crCurve: Self.constantCurve(c0: 0),
+                dither: .bayer8x8,
+                frameIndex: frame
+            ) else {
+                Issue.record("Composer returned nil")
+                return
+            }
+            let cell = Self.readCell(dst, plane: 0, components: 1, component: 0)
+            means.append(Double(cell.reduce(0, +)) / 64.0)
+        }
+        let exact = Double(vdr) / 4.0
+        #expect(abs(means[0] - exact) < 1e-9, "frame 0 mean \(means[0]) != \(exact)")
+        #expect(abs(means[1] - exact) < 1e-9, "frame 1 mean \(means[1]) != \(exact)")
+    }
+
+    // MARK: - Decorrelated
+
+    @Test("Cb and Cr use different dither phases, so a flat field does not get a shared pattern")
+    func chromaPhasesAreDecorrelated() throws {
+        // Residue 2 splits the cell evenly, which is the residue with the most
+        // pattern to compare.
+        let (curve, vdr) = Self.curveHitting(vdr: 500 * 4 + 2, blMax: 1023, vdrScale: 4)
+
+        guard let dst = Self.compose(
+            lumaCurve: Self.constantCurve(c0: 0),
+            cbCurve: curve,
+            crCurve: curve,
+            dither: .bayer8x8,
+            frameIndex: 0
+        ) else {
+            Issue.record("Composer returned nil")
+            return
+        }
+
+        let cb = Self.readCell(dst, plane: 1, components: 2, component: 0)
+        let cr = Self.readCell(dst, plane: 1, components: 2, component: 1)
+        #expect(cb.count == 64 && cr.count == 64)
+
+        let exact = Double(vdr) / 4.0
+        #expect(abs(Double(cb.reduce(0, +)) / 64.0 - exact) < 1e-9, "Cb cell mean is biased")
+        #expect(abs(Double(cr.reduce(0, +)) / 64.0 - exact) < 1e-9, "Cr cell mean is biased")
+
+        // Same curve, same input, same frame, so any difference is the phase.
+        // At the 50% level the selected set is a checkerboard in (x + y) parity,
+        // and the Cb/Cr offsets differ by (0, 1), which inverts that parity: the
+        // two patterns come out exact complements, 64 of 64. A weak offset is the
+        // failure worth catching here rather than a missing one -- the (4, 4)
+        // diagonal this replaced is a near-symmetry of the matrix and scored 0 of
+        // 64 at this level, so `cb != cr` alone would not have been enough.
+        let differing = zip(cb, cr).filter { $0 != $1 }.count
+        #expect(differing >= 48,
+                "Cb and Cr dither patterns differ on only \(differing) of 64 pixels; the phase offset is gone or is a symmetry of the Bayer matrix")
+    }
+
+    // MARK: - Dither actually changes something
+
+    @Test("with dither off the same field collapses to one level, so the cell spread above is the dither's")
+    func unditheredIsFlat() throws {
+        let (curve, _) = Self.curveHitting(vdr: 500 * 4 + 2, blMax: 1023, vdrScale: 4)
+        guard let dst = Self.compose(
+            lumaCurve: curve,
+            cbCurve: Self.constantCurve(c0: 0),
+            crCurve: Self.constantCurve(c0: 0),
+            dither: .none,
+            frameIndex: 0
+        ) else {
+            Issue.record("Composer returned nil")
+            return
+        }
+        let cell = Self.readCell(dst, plane: 0, components: 1, component: 0)
+        #expect(Set(cell).count == 1, "undithered output is not flat: \(Set(cell).sorted())")
+    }
+
+    /// The 8x8 ordered-dither matrix as a literal table (`k` in `k/64`).
+    static let bayerGolden: [Int] = [
+        0, 32, 8, 40, 2, 34, 10, 42,
+        48, 16, 56, 24, 50, 18, 58, 26,
+        12, 44, 4, 36, 14, 46, 6, 38,
+        60, 28, 52, 20, 62, 30, 54, 22,
+        3, 35, 11, 43, 1, 33, 9, 41,
+        51, 19, 59, 27, 49, 17, 57, 25,
+        15, 47, 7, 39, 13, 45, 5, 37,
+        63, 31, 55, 23, 61, 29, 53, 21,
+    ]
+
+    /// Recovers every cell of the dither matrix from the GPU and compares it with the golden table.
+    /// A 16-bit VDR into a 10-bit plane gives `vdr_scale = 64`, so a constant luma of `500*64 + j`
+    /// rounds up in a cell exactly when `j + k >= 64`; the first `j` at which a cell rises gives `k = 64 - j`.
+    @Test("the dither matrix the kernel applies is the golden Bayer 8x8, cell for cell")
+    func ditherMatrixIsGolden() throws {
+        let composer = try #require(DoviFelComposer())
+        var recovered = [Int](repeating: 0, count: 64)
+        var rose = [Bool](repeating: false, count: 64)
+        for j in 0..<64 {
+            var p = DoviMetalParams()
+            let depthsOK = p.setBitDepths(bl: 10, vdr: 16)
+            #expect(depthsOK)
+            p.ditherMode = .bayer8x8
+            p.flags = [.disableResidual]
+            p.frameIndex = 0
+            p.polyY = DoviGpuCurveSweepTests.identityCurve()
+            p.polyCb = DoviGpuCurveSweepTests.identityCurve()
+            p.polyCr = DoviGpuCurveSweepTests.identityCurve()
+            p.polyY.numPivots = 2
+            p.polyY.pivots[0] = 0; p.polyY.pivots[1] = 1023
+            p.polyY.method[0] = DoviMapping.polynomial.rawValue
+            p.polyY.order[0] = 0
+            p.polyY.coefShift[0] = 23
+            p.polyY.coef[0] = [Int32((Double(500 * 64 + j) / (1024.0 * 64.0) * 8388608.0).rounded()), 0, 0]
+            let out = try DoviGpuEdgeCaseTests.composeConstant(composer, blWidth: 16, blHeight: 16,
+                                                               bl: (500, 512, 512), el: (512, 512, 512), params: p)
+            let rows = (0..<8).map { DoviGpuCurveSweepTests.readPlane(out, plane: 0, components: 1, row: $0) }
+            for y in 0..<8 { for x in 0..<8 where !rose[y * 8 + x] && rows[y][x][0] == 501 {
+                rose[y * 8 + x] = true; recovered[y * 8 + x] = 64 - j
+            } }
+        }
+        #expect(recovered == Self.bayerGolden, "recovered \(recovered)")
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviElBitDepthTests.swift b/Tests/AetherEngineTests/DoviElBitDepthTests.swift
new file mode 100644
index 000000000..36df3cf37
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviElBitDepthTests.swift
@@ -0,0 +1,100 @@
+import Testing
+import Foundation
+import Dovi
+@testable import AetherEngine
+
+/// An RPU whose enhancement layer is not 10-bit is refused (the composer then falls back to the base layer),
+/// the same as one whose base layer is not 10-bit.
+struct DoviElBitDepthTests {
+
+    private static let crcTable: [UInt32] = (0..<256).map { i in
+        var c = UInt32(i) << 24
+        for _ in 0..<8 { c = c & 0x8000_0000 != 0 ? (c << 1) ^ 0x04C1_1DB7 : c << 1 }
+        return c
+    }
+
+    private static func unescape(_ b: [UInt8]) -> [UInt8] {
+        var out = [UInt8](), zeros = 0
+        for x in b {
+            if zeros >= 2 && x == 3 { zeros = 0; continue }
+            out.append(x)
+            zeros = x == 0 ? zeros + 1 : 0
+        }
+        return out
+    }
+
+    /// Rewrites the CRC of an unescaped RPU (header 7C 01, payload, CRC32, 0x80) after a mutation.
+    private static func repairCrc(_ u: inout [UInt8]) {
+        let tailAt = u.count - 5
+        var crc: UInt32 = 0xFFFF_FFFF
+        for i in 3..<tailAt { crc = (crc << 8) ^ crcTable[Int((crc >> 24) ^ UInt32(u[i]))] }
+        u[tailAt] = UInt8(crc >> 24); u[tailAt + 1] = UInt8((crc >> 16) & 0xFF)
+        u[tailAt + 2] = UInt8((crc >> 8) & 0xFF); u[tailAt + 3] = UInt8(crc & 0xFF)
+    }
+
+    private static func header(_ nal: [UInt8]) -> (bl: Int, el: Int, vdr: Int)? {
+        // Through the guard: a mutated stream can reach paths in libdovi that abort the process.
+        guard let rpu = nal.withUnsafeBufferPointer({ DoviRpuGuard.parse($0.baseAddress!, $0.count) }) else { return nil }
+        defer { dovi_rpu_free(rpu) }
+        guard dovi_rpu_get_error(rpu) == nil, let h = dovi_rpu_get_header(rpu) else { return nil }
+        defer { dovi_rpu_free_header(h) }
+        return (Int(h.pointee.bl_bit_depth_minus8) + 8, Int(h.pointee.el_bit_depth_minus8) + 8, Int(h.pointee.vdr_bit_depth_minus8) + 8)
+    }
+
+    private static func bytes(_ hex: String) -> [UInt8] {
+        stride(from: 0, to: hex.count, by: 2).map { UInt8(hex.dropFirst($0).prefix(2), radix: 16)! }
+    }
+
+    /// The header codes el_bit_depth_minus8 = 2 as the exp-Golomb string 011; flipping its last bit gives 010,
+    /// which is el_bit_depth_minus8 = 1 (9-bit) in the same number of bits, so nothing after it shifts. Find that
+    /// bit by trying the first bytes and keeping the flip libdovi reports as an el_bit_depth error.
+    private static func rpuWithNineBitEl(from hex: String) -> [UInt8]? {
+        let base = unescape(bytes(hex))
+        guard let original = header(bytes(hex)), original.el == 10 else { return nil }
+        for byte in 3..<min(24, base.count - 5) {
+            for bit in 0..<8 {
+                var m = base
+                m[byte] ^= UInt8(1 << bit)
+                repairCrc(&m)
+                let escaped = DoviCrcValidFuzzTests.escape(m)
+                // Through the guard: a mutated stream can reach paths in libdovi that abort the process.
+                guard let rpu = escaped.withUnsafeBufferPointer({ DoviRpuGuard.parse($0.baseAddress!, $0.count) }) else { continue }
+                defer { dovi_rpu_free(rpu) }
+                if let e = dovi_rpu_get_error(rpu), String(cString: e).contains("el_bit_depth_minus8") { return escaped }
+            }
+        }
+        return nil
+    }
+
+    @Test("the real RPUs carry a 10-bit EL and are accepted",
+          arguments: [DoviFelMathTests.clipARpuHex, DoviFelMathTests.clipCRpuHex])
+    func tenBitElIsAccepted(hex: String) throws {
+        let nal = Self.bytes(hex)
+        let rpu = try #require(dovi_parse_unspec62_nalu(nal, nal.count))
+        defer { dovi_rpu_free(rpu) }
+        #expect(DoviFelComposer.parseRpuParameters(rpu: rpu) != nil)
+    }
+
+    /// The composer's own depth check, reached directly: libdovi never hands it an RPU that gets this far.
+    @Test("only a 10-bit base layer with a 10-bit enhancement layer passes the composer's depth check")
+    func layerDepthCheck() {
+        #expect(DoviFelComposer.layerBitDepthsSupported(bl: 10, el: 10))
+        #expect(!DoviFelComposer.layerBitDepthsSupported(bl: 10, el: 9))
+        #expect(!DoviFelComposer.layerBitDepthsSupported(bl: 10, el: 12))
+        #expect(!DoviFelComposer.layerBitDepthsSupported(bl: 8, el: 10))
+    }
+
+    /// libdovi 3.4 itself rejects `el_bit_depth_minus8 != 2` ("should be 2") for a Profile 7 RPU, and reports 2
+    /// for a converted 8.1 one, so no RPU it accepts reaches the composer's own EL check today (`layerDepthCheck` covers
+    /// that check). This pins the end-to-end behaviour:
+    /// the composer gets no parameters, so the caller presents the base layer.
+    @Test("a Profile 7 RPU with a 9-bit EL (everything else unchanged) is refused",
+          arguments: [DoviFelMathTests.clipARpuHex, DoviFelMathTests.clipCRpuHex])
+    func nonTenBitElIsRefused(hex: String) throws {
+        let nal = try #require(Self.rpuWithNineBitEl(from: hex), "could not craft a 9-bit-EL variant")
+        let rpu = try #require(nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) })
+        defer { dovi_rpu_free(rpu) }
+        #expect(dovi_rpu_get_error(rpu) != nil, "libdovi should flag the EL depth")
+        #expect(DoviFelComposer.parseRpuParameters(rpu: rpu) == nil)
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
new file mode 100644
index 000000000..e425870e9
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
@@ -0,0 +1,62 @@
+import Foundation
+import Testing
+import Metal
+@testable import AetherEngine
+
+/// The enhancement layer is upsampled to the base-layer grid by one hardware bilinear fetch
+/// (`dovi_sample_el_1d`). These tests run the production composer and read the residual back out of the
+/// un-quantised VDR plane, so a different filter (a Catmull-Rom, or nearest) fails them.
+@Suite(.enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
+struct DoviEnhancementUpsamplerTests {
+
+    typealias H = DoviGpuCurveSweepTests
+
+    /// BL luma constant 512 (VDR 2048), EL luma `elColumn(x)` at half resolution, residual scale 2048: the
+    /// output is 2048 + floor((2|r| - 1) * 2048 / 4096) with r = el - 512, i.e. |r| - 1 for the codes used here
+    /// (|r| of 88 or more is far from the half-step rounding), and the first row is returned.
+    private func composeLuma(elColumn: (Int) -> Int) throws -> [Int] {
+        let composer = try #require(DoviFelComposer())
+        var p = DoviGpuEdgeCaseTests.params(nlqY: DoviGpuEdgeCaseTests.nlq(vdrInMax: 4095))
+        p.ditherMode = .debugRawVDR
+        let bl = try #require(H.makeBuffer(width: 64, height: 8))
+        let el = try #require(H.makeBuffer(width: 32, height: 4))
+        H.fillPlane(bl, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 0, components: 1) { x, _, _ in elColumn(x) }
+        H.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+        let out = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: p))
+        return Array(DoviTestSupport.rawVDR(out)[0][0..<64])
+    }
+
+    /// Residual in VDR codes for an EL code, from the DoViBaker formula (positive side): ((2r - 1) * 2048) >> 12.
+    private func residual(_ el: Int) -> Double {
+        Double(((2 * (el - 512) - 1) * 2048) >> 12)
+    }
+
+    @Test("a linear EL ramp is reproduced between EL texel centres, one bilinear step per base-layer pixel")
+    func rampIsLinearlyInterpolated() throws {
+        // EL column x is 600 + 4x. BL pixel gx samples EL coordinate gx / 2 - 0.25 (centres at x + 0.5).
+        let row = try composeLuma { 600 + 4 * $0 }
+        for gx in 2..<62 {
+            let elValue = 600.0 + 4.0 * (Double(gx) / 2.0 - 0.25)
+            let expected = 2048.0 + (elValue - 512.0) - 0.5     // linear in el: |r| - 1/2
+            #expect(abs(Double(row[gx]) - expected) <= 1.5, "gx \(gx): \(row[gx]) vs \(expected)")
+        }
+    }
+
+    @Test("a step edge in the EL is blended, never overshot, and the plateaus are exact")
+    func stepHasNoRinging() throws {
+        let low = 600, high = 700
+        let row = try composeLuma { $0 < 16 ? low : high }
+        let lo = 2048 + Int(residual(low)), hi = 2048 + Int(residual(high))
+        for gx in 0..<64 {
+            #expect(row[gx] >= lo && row[gx] <= hi, "gx \(gx) = \(row[gx]) leaves [\(lo), \(hi)]: the filter rings")
+        }
+        #expect(row[10] == lo)
+        #expect(row[53] == hi)
+        // The edge sits between EL columns 15 and 16, i.e. BL pixels 31 and 32: one pixel each side is strictly inside.
+        let inside = (28..<36).filter { row[$0] > lo && row[$0] < hi }
+        #expect(inside.count >= 2 && inside.count <= 4, "edge transition spans \(inside.count) pixels")
+        for gx in 1..<64 { #expect(row[gx] >= row[gx - 1], "monotone at \(gx)") }
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviFelFuzzTests.swift b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
new file mode 100644
index 000000000..0d9c8a0e7
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
@@ -0,0 +1,252 @@
+import Testing
+import Foundation
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+import Dovi
+@testable import AetherEngine
+
+/// Corrupt and hostile input must degrade (nil parameters, dropped EL, base layer
+/// only), never crash or hang. Seeds are real packets/RPUs from the FEL fixtures;
+/// mutations are deterministic so a failure reproduces.
+struct DoviFelFuzzTests {
+
+    /// SplitMix64: deterministic, no dependence on the system RNG.
+    struct RNG {
+        var state: UInt64
+        mutating func next() -> UInt64 {
+            state &+= 0x9E3779B97F4A7C15
+            var z = state
+            z = (z ^ (z >> 30)) &* 0xBF58476D1CE4E5B9
+            z = (z ^ (z >> 27)) &* 0x94D049BB133111EB
+            return z ^ (z >> 31)
+        }
+        mutating func below(_ n: Int) -> Int { n <= 0 ? 0 : Int(next() % UInt64(n)) }
+    }
+
+    /// First video packet that contains an RPU, as raw bytes, plus one RPU NAL.
+    static func seed(index: Int = 2) throws -> (packet: [UInt8], rpu: [UInt8])? {
+        let name = DoviFelRealFileTests.fixtures[index]
+        guard DoviFelRealFileTests.available(name) else { return nil }
+        let demuxer = Demuxer()
+        try demuxer.open(url: DoviFelRealFileTests.url(name))
+        defer { demuxer.close() }
+        let idx = Int32(demuxer.videoStreamIndex)
+        while let pkt = try demuxer.readPacket() {
+            defer {
+                av_packet_unref(pkt)
+                var o: UnsafeMutablePointer<AVPacket>? = pkt
+                trackedPacketFree(&o)
+            }
+            guard pkt.pointee.stream_index == idx, let data = pkt.pointee.data else { continue }
+            let bytes = [UInt8](UnsafeBufferPointer(start: data, count: Int(pkt.pointee.size)))
+            let copy = makePacket(bytes)
+            defer { var o: UnsafeMutablePointer<AVPacket>? = copy; trackedPacketFree(&o) }
+            let r = DoviRpuConverter.separateDualLayers(copy, extractEL: false, useCustomBlockSource: true, extractParams: true)
+            if let raw = r.rpuData { return (bytes, raw) }
+        }
+        return nil
+    }
+
+    /// Owns its buffer, padded the way FFmpeg packets are.
+    static func makePacket(_ bytes: [UInt8]) -> UnsafeMutablePointer<AVPacket> {
+        let pkt = trackedPacketAlloc()!
+        let pad = Int(AV_INPUT_BUFFER_PADDING_SIZE)
+        let ref = av_buffer_alloc(bytes.count + pad)!
+        memset(ref.pointee.data, 0, bytes.count + pad)
+        bytes.withUnsafeBufferPointer { memcpy(ref.pointee.data, $0.baseAddress!, bytes.count) }
+        pkt.pointee.buf = ref
+        pkt.pointee.data = ref.pointee.data
+        pkt.pointee.size = Int32(bytes.count)
+        pkt.pointee.pts = 0
+        pkt.pointee.dts = 0
+        return pkt
+    }
+
+    /// Mutations only probe the parser if they start from an RPU libdovi really accepts. libdovi
+    /// hands back a handle even when parsing fails, so the error, not the handle, is the verdict.
+    static func expectLibdoviAccepts(_ nal: [UInt8], sourceLocation: SourceLocation = #_sourceLocation) throws {
+        let rpu = try #require(nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) },
+                               sourceLocation: sourceLocation)
+        defer { dovi_rpu_free(rpu) }
+        #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")",
+                sourceLocation: sourceLocation)
+        #expect(DoviFelComposer.parseRpuParameters(rpu: rpu) != nil, sourceLocation: sourceLocation)
+    }
+
+    static func mutate(_ input: [UInt8], _ rng: inout RNG) -> [UInt8] {
+        var b = input
+        switch rng.below(6) {
+        case 0: // flip a few bits
+            for _ in 0..<(1 + rng.below(8)) where !b.isEmpty { b[rng.below(b.count)] ^= UInt8(1 << rng.below(8)) }
+        case 1: // truncate
+            b = Array(b.prefix(rng.below(b.count + 1)))
+        case 2: // overwrite a run with 0xFF / 0x00
+            if !b.isEmpty {
+                let start = rng.below(b.count), len = 1 + rng.below(16)
+                let v: UInt8 = rng.below(2) == 0 ? 0xFF : 0x00
+                for i in start..<min(b.count, start + len) { b[i] = v }
+            }
+        case 3: // random garbage of the same length
+            for i in 0..<b.count { b[i] = UInt8(truncatingIfNeeded: rng.next()) }
+        case 4: // duplicate a slice
+            if b.count > 4 {
+                let start = rng.below(b.count - 1), len = 1 + rng.below(min(32, b.count - start))
+                b.insert(contentsOf: b[start..<(start + len)], at: start)
+            }
+        default: // extend with junk
+            for _ in 0..<rng.below(64) { b.append(UInt8(truncatingIfNeeded: rng.next())) }
+        }
+        return b
+    }
+
+    /// A length-prefixed access unit built from a synthetic RPU: a base-layer slice, an enhancement-layer
+    /// NAL (`unspec63`) and the RPU (`unspec62`), so the splitter fuzz runs without a clip.
+    static func syntheticPacket(rpu: [UInt8]) -> [UInt8] {
+        func framed(_ nal: [UInt8]) -> [UInt8] {
+            let n = UInt32(nal.count)
+            return [UInt8(n >> 24), UInt8(n >> 16 & 0xFF), UInt8(n >> 8 & 0xFF), UInt8(n & 0xFF)] + nal
+        }
+        let base: [UInt8] = [0x02, 0x01] + (0..<48).map { UInt8(truncatingIfNeeded: $0 &* 7 &+ 1) }
+        let el: [UInt8] = [0x7E, 0x01, 0x02, 0x01] + (0..<24).map { UInt8(truncatingIfNeeded: $0 &* 5 &+ 3) }
+        return framed(base) + framed(el) + framed(rpu)
+    }
+
+    static func checkMutatedRpuParsing(seedRPU: [UInt8], label: String, rngState: UInt64, iterations: Int) throws {
+        #expect(seedRPU.withUnsafeBufferPointer { DoviRpuGuard.crcIsValid($0.baseAddress!, $0.count) }, "a seed RPU must pass the CRC guard")
+        try expectLibdoviAccepts(seedRPU)
+        var rng = RNG(state: rngState)
+        var parsed = 0, rejected = 0
+        for _ in 0..<iterations {
+            let rpuBytes = mutate(seedRPU, &rng)
+            guard !rpuBytes.isEmpty else { continue }
+            guard let rpu = rpuBytes.withUnsafeBufferPointer({ DoviRpuGuard.parse($0.baseAddress!, $0.count) }) else {
+                rejected += 1
+                continue
+            }
+            defer { dovi_rpu_free(rpu) }
+            if let p = DoviFelComposer.parseRpuParameters(rpu: rpu) {
+                parsed += 1
+                // Whatever survives must be safe for the kernels to index.
+                for poly in [p.polyY, p.polyCb, p.polyCr] {
+                    #expect(poly.numPivots <= UInt32(DoviPolynomialParams.maxPivots))
+                    if poly.numPivots >= 2 {
+                        let pieces = Int(poly.numPivots) - 1
+                        for i in 0..<pieces {
+                            #expect(poly.pivots[i] <= poly.pivots[i + 1], "pivots must ascend")
+                            #expect(poly.order[i] <= 3)
+                            #expect(poly.coefShift[i] <= 23 || poly.method[i] == DoviMapping.mmr.rawValue)
+                        }
+                        #expect(poly.pivots[Int(poly.numPivots) - 1] <= p.blMax)
+                    }
+                }
+                #expect(p.blMax == 1023)
+                #expect(p.vdrScale >= 1)
+                for n in [p.nlqY, p.nlqCb, p.nlqCr] {
+                    #expect(n.nlqShift <= 23)
+                    #expect(n.vdrInMax >= 0)
+                }
+            } else {
+                rejected += 1
+            }
+        }
+        print("[fuzz] RPU \(label): \(parsed) parsed, \(rejected) rejected of \(iterations)")
+        #expect(parsed + rejected > iterations * 3 / 4)
+    }
+
+    @Test("a mutated synthetic RPU never crashes libdovi or the parameter parser; the result is nil or self-consistent",
+          .timeLimit(.minutes(2)), arguments: DoviCrcValidFuzzTests.syntheticSeeds.indices)
+    func mutatedSyntheticRpuParsing(index: Int) throws {
+        let seed = DoviCrcValidFuzzTests.syntheticSeeds[index]
+        try Self.checkMutatedRpuParsing(seedRPU: seed.nal, label: seed.name, rngState: 0xFE1 + UInt64(index), iterations: 4000)
+    }
+
+    @Test("a mutated RPU from a real clip never crashes libdovi or the parameter parser; the result is nil or self-consistent",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(2)))
+    func mutatedRpuParsing() throws {
+        let seed = try #require(try Self.seed())
+        try Self.checkMutatedRpuParsing(seedRPU: seed.rpu, label: "clip", rngState: 0xFE1, iterations: 4000)
+    }
+
+    static func checkMutatedPacketSplitting(seedPacket: [UInt8], useCustomBlockSource: Bool, iterations: Int) {
+        var rng = RNG(state: useCustomBlockSource ? 0xA11 : 0xB22)
+        for i in 0..<iterations {
+            let bytes = mutate(seedPacket, &rng)
+            let pkt = makePacket(bytes.isEmpty ? [0] : bytes)
+            let r = DoviRpuConverter.separateDualLayers(
+                pkt, extractEL: true, useCustomBlockSource: useCustomBlockSource, extractParams: true
+            )
+            if let el = r.elPacket {
+                // An extracted EL must be a well-formed length-prefixed stream inside its buffer.
+                var off = 0
+                let size = Int(el.pointee.size)
+                while off + 4 <= size {
+                    let n = (Int(el.pointee.data[off]) << 24) | (Int(el.pointee.data[off + 1]) << 16)
+                        | (Int(el.pointee.data[off + 2]) << 8) | Int(el.pointee.data[off + 3])
+                    #expect(n >= 0 && off + 4 + n <= size, "iteration \(i): EL NAL overruns its packet")
+                    if off + 4 + n > size { break }
+                    off += 4 + n
+                }
+                #expect(off == size || size - off < 4, "iteration \(i): trailing bytes in EL packet")
+                var o: UnsafeMutablePointer<AVPacket>? = el
+                trackedPacketFree(&o)
+            }
+            var o: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&o)
+        }
+    }
+
+    @Test("a mutated or truncated synthetic access unit is split without crashing, and never reads past its buffer",
+          .timeLimit(.minutes(3)),
+          arguments: DoviCrcValidFuzzTests.syntheticSeeds.indices, [true, false])
+    func mutatedSyntheticPacketSplitting(index: Int, useCustomBlockSource: Bool) {
+        let packet = Self.syntheticPacket(rpu: DoviCrcValidFuzzTests.syntheticSeeds[index].nal)
+        Self.checkMutatedPacketSplitting(seedPacket: packet, useCustomBlockSource: useCustomBlockSource, iterations: 1500)
+    }
+
+    @Test("a mutated or truncated access unit from a real clip is split without crashing, and never reads past its buffer",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(3)),
+          arguments: [true, false])
+    func mutatedPacketSplitting(useCustomBlockSource: Bool) throws {
+        let seed = try #require(try Self.seed())
+        Self.checkMutatedPacketSplitting(seedPacket: seed.packet, useCustomBlockSource: useCustomBlockSource, iterations: 1500)
+    }
+
+    @Test("length prefixes that lie about their size are contained by the NAL walker",
+          arguments: [0xFFFF_FFFF, 0x7FFF_FFFF, 0x8000_0000, 0x0000_1000, 0x0000_0004, 0])
+    func lyingLengthPrefix(length: UInt32) throws {
+        // [len][2-byte NAL header + 6 bytes] — the prefix claims `length`.
+        var bytes: [UInt8] = [
+            UInt8(length >> 24 & 0xFF), UInt8(length >> 16 & 0xFF), UInt8(length >> 8 & 0xFF), UInt8(length & 0xFF),
+            0x7E, 0x01, 1, 2, 3, 4, 5, 6,
+        ]
+        for variant in 0..<3 {
+            if variant == 1 { bytes += bytes }                 // a second, equally wrong, NAL
+            if variant == 2 { bytes = Array(bytes.prefix(6)) } // cut inside the header
+            let pkt = Self.makePacket(bytes)
+            let r = DoviRpuConverter.separateDualLayers(pkt, extractEL: true, useCustomBlockSource: false, extractParams: true)
+            if let el = r.elPacket { var o: UnsafeMutablePointer<AVPacket>? = el; trackedPacketFree(&o) }
+            var o: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&o)
+        }
+    }
+
+    @Test("empty, tiny and null-data packets are handled")
+    func degeneratePackets() {
+        for size in [0, 1, 2, 3, 4, 5] {
+            let pkt = Self.makePacket([UInt8](repeating: 0x7E, count: size))
+            pkt.pointee.size = Int32(size)
+            let r = DoviRpuConverter.separateDualLayers(pkt, extractEL: true, useCustomBlockSource: false, extractParams: true)
+            #expect(r.elPacket == nil)
+            var o: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&o)
+        }
+        let empty = trackedPacketAlloc()!   // data == nil
+        let r = DoviRpuConverter.separateDualLayers(empty, extractEL: true, useCustomBlockSource: true, extractParams: true)
+        #expect(r.elPacket == nil && r.rpuData == nil)
+        var o: UnsafeMutablePointer<AVPacket>? = empty
+        trackedPacketFree(&o)
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviFelMathTests.swift b/Tests/AetherEngineTests/DoviFelMathTests.swift
new file mode 100644
index 000000000..bffd2ed3a
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviFelMathTests.swift
@@ -0,0 +1,323 @@
+import Testing
+import Foundation
+import CoreVideo
+import Metal
+import Dovi
+@testable import AetherEngine
+
+/// Numerical checks of the Dolby Vision Profile 7 FEL reconstruction, all driven through the production
+/// `DoviFelComposer.compose` with `.debugRawVDR` (12-bit VDR codes, no quantisation) and the real RPU parser.
+/// Nothing here re-implements the kernel's arithmetic: expectations are worked out from the DoViBaker
+/// formulas (erazortt/DoViBaker, `DoViProcessor.cpp`) and written down as numbers.
+struct DoviFelMathTests {
+
+    // Raw 376-byte unspec62 RPU NAL extracted from fel-clip-a.mkv
+    static let clipARpuHex = "7c011908090840613650ae20002008020080200802007f801ffc00ffc001fffa0000030100000300d0000008000006800000400000340000030200000301a000001000000d0000030080000068000004000003034000002000000a800000800000e18618800000800000800000800000800000800000b0c30c800000800000800000800000800000800000986186800000800000800000800000800000540000040000040000070c30c4000004000004000004000004000004000005861864000004000004000004000004000004000004c30c34000004000004000004000004012000010010010000030100480000400400400000401200001001001000001c95980000d7a8959be7f3ac7095991328000004000003002000000300200000030070d8890c06182978c238145000000698f96bfffc00000300000300000300018081f73805463008015faa4900c0282183180081872b94210002020000030008050000030002261140120c1f4000641f2e1276ffb6cfda80"
+
+    // Raw 225-byte unspec62 RPU NAL extracted from fel-clip-c.mp4
+    static let clipCRpuHex = "7c011908090840613650af003ff801ffc00ffc001fffa000001000000d0000030080000068000004000003020090000080080080000080240000200200200000200900000800800800000d12b300001af512b37cfe758e12b3226500000300800000040000030004000003000e1b112180c3052f1847028a00000300d31f2d7fff800000030000030000030030103ee700a8c0300800410a6680c02821800800800800800400020200000300080500000300000300000300120c07d0000201c000f650301c0040038680b080180080080080080080041204ff80008041ac0ad580"
+
+    private static func hexToBytes(_ hex: String) -> [UInt8] {
+        var bytes: [UInt8] = []
+        var i = hex.startIndex
+        while i < hex.endIndex {
+            let next = hex.index(i, offsetBy: 2)
+            if let byte = UInt8(hex[i..<next], radix: 16) {
+                bytes.append(byte)
+            }
+            i = next
+        }
+        return bytes
+    }
+
+    // MARK: - Fixtures
+
+    private typealias H = DoviGpuCurveSweepTests
+
+    /// A one-piece curve over [0, 1023] with Q23 coefficients given as doubles.
+    private static func polynomial(_ c0: Double, _ c1: Double = 0, _ c2: Double = 0, order: UInt32) -> DoviPolynomialParams {
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 2
+        poly.pivots[0] = 0; poly.pivots[1] = 1023
+        poly.method[0] = DoviMapping.polynomial.rawValue
+        poly.order[0] = order
+        poly.coefShift[0] = 23
+        poly.coef[0] = [Int32(c0 * 8388608.0), Int32(c1 * 8388608.0), Int32(c2 * 8388608.0)]
+        return poly
+    }
+
+    private static func rawParams(residual: Bool) -> DoviMetalParams {
+        var p = DoviGpuEdgeCaseTests.params(flags: residual ? [] : [.disableResidual])
+        p.ditherMode = .debugRawVDR
+        return p
+    }
+
+    // MARK: - D1 & S2: inverse NLQ
+
+    /// DoViBaker `nonLinearInverseQuantization`: rr = e - offset; rr = 2 rr - sign; dq = rr * S, then a shift
+    /// that lands in VDR codes; for S = 2048 at denom 23 that is (2|r| - 1) * 2048 >> 12. The kernel reconstructs
+    /// the magnitude and applies the sign afterwards, so a negative residual truncates toward zero where
+    /// DoViBaker's arithmetic shift floors: the two differ by at most one code on negative half-steps.
+    @Test("inverse NLQ through the composer: el = 1023 gives +510 (not 511), el = 0 gives -511, centre gives 0",
+          arguments: [
+            (1023, 2558),   // r = +511: (1021 * 2048) >> 12 = 510
+            (0, 1537),      // r = -512: (1023 * 2048) >> 12 = 511 -> -511 (DoViBaker floors to -512)
+            (512, 2048),          // r = 0
+            (768, 2303),    // r = +256: (511 * 2048) >> 12 = 255
+            (256, 1793),    // r = -256: -255 (DoViBaker -256)
+            (513, 2048),          // r = +1: (1 * 2048) >> 12 = 0
+            (514, 2049),      // r = +2: (3 * 2048) >> 12 = 1
+          ])
+    func inverseNlqThroughComposer(el: Int, expectedVdr: Int) throws {
+        let composer = try #require(DoviFelComposer())
+        var p = Self.rawParams(residual: true)
+        p.nlqY = DoviGpuEdgeCaseTests.nlq(vdrInMax: 4095)   // not binding: isolate the quantiser
+        let out = try DoviGpuEdgeCaseTests.composeConstant(composer, bl: (512, 512, 512), el: (el, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [expectedVdr], "el=\(el)")
+    }
+
+    // MARK: - D3: delta-coded pivots
+
+    @Test("D3: the parser prefix-sums delta-coded pivots into absolute breakpoints")
+    func pivotPrefixSumAccumulation() {
+        let clipABytes = Self.hexToBytes(Self.clipARpuHex)
+        guard let rpu = dovi_parse_unspec62_nalu(clipABytes, clipABytes.count) else {
+            Issue.record("Failed to parse clip A RPU")
+            return
+        }
+        defer { dovi_rpu_free(rpu) }
+        // libdovi returns a handle even when parsing fails; only the error says it was accepted.
+        #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")")
+        guard let params = DoviFelComposer.parseRpuParameters(rpu: rpu) else {
+            Issue.record("Failed to parse clip A RPU")
+            return
+        }
+
+        // Luma pivots from clip A are delta-coded: 0 128 128 128 128 128 128 128 127
+        let expectedLumaPivots: [UInt32] = [0, 128, 256, 384, 512, 640, 768, 896, 1023]
+        #expect(params.polyY.numPivots == 9)
+        for i in 0..<9 {
+            #expect(params.polyY.pivots[i] == expectedLumaPivots[i], Comment("Pivot \(i) expected \(expectedLumaPivots[i]), got \(params.polyY.pivots[i])"))
+        }
+    }
+
+    /// DoViBaker `getPivotIndex`: the first piece whose upper pivot the sample is below, and the last piece for
+    /// anything at or above the top pivot. Pieces here are [0,128), [128,256), [256,1023] and each one's constant
+    /// is distinct, so the output names the piece that was selected.
+    @Test("piece selection on the GPU: boundaries belong to the upper piece and the top code selects the last piece")
+    func pieceSelectionOnGpu() throws {
+        let composer = try #require(DoviFelComposer())
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 4
+        poly.pivots[0] = 0; poly.pivots[1] = 128; poly.pivots[2] = 256; poly.pivots[3] = 1023
+        let levels = [0.25, 0.5, 0.75]
+        for piece in 0..<3 {
+            poly.method[piece] = DoviMapping.polynomial.rawValue
+            poly.order[piece] = 0
+            poly.coefShift[piece] = 23
+            poly.coef[piece] = [Int32(levels[piece] * 8388608.0), 0, 0]
+        }
+        var p = Self.rawParams(residual: false)
+        p.polyY = poly
+
+        let bl = try #require(H.makeBuffer(width: 1024, height: 4))
+        let el = try #require(H.makeBuffer(width: 512, height: 2))
+        H.fillPlane(bl, plane: 0, components: 1) { c, _, _ in min(c, 1023) }
+        H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+        let out = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: p))
+        let row = Array(DoviTestSupport.rawVDR(out)[0][0..<1024])
+        let expected = [(0, 1024), (127, 1024), (128, 2048), (255, 2048), (256, 3072), (1000, 3072), (1023, 3072)]
+        for (code, vdr) in expected {
+            #expect(row[code] == vdr, "BL code \(code)")
+        }
+    }
+
+    // MARK: - D4 & N1: polynomial coefficients and denominator
+
+    /// DoViBaker `polynompialMapping`: the input is the BL code over 2^bl_bit_depth (1024, not 1023) and the
+    /// result is in 12-bit VDR codes after 2^vdr_bit_depth (4096).
+    @Test("polynomial reshaping on the GPU matches the closed form over all 1024 base-layer codes")
+    func polynomialOverAllCodes() throws {
+        let composer = try #require(DoviFelComposer())
+        let c0 = 0.02, c1 = 0.95, c2 = 0.10
+        var p = Self.rawParams(residual: false)
+        p.polyY = Self.polynomial(c0, c1, c2, order: 2)
+        // The coefficients the kernel actually receives, so the comparison is not about Int32 truncation.
+        let q = p.polyY.coef[0].map { Double($0) / 8388608.0 }
+
+        let bl = try #require(H.makeBuffer(width: 1024, height: 4))
+        let el = try #require(H.makeBuffer(width: 512, height: 2))
+        H.fillPlane(bl, plane: 0, components: 1) { c, _, _ in c }
+        H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+        let out = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: p))
+        let row = DoviTestSupport.rawVDR(out)[0]
+        var worst = 0.0
+        for code in 0..<1024 {
+            let x = Double(code) / 1024.0
+            let exact = min(max((q[0] + q[1] * x + q[2] * x * x) * 4096.0, 0), 4095)
+            worst = max(worst, abs(Double(row[code]) - exact))
+        }
+        #expect(worst <= 1.0, "worst deviation \(worst) VDR codes")
+    }
+
+    // MARK: - N3: prediction overshoot survives until the residual is added
+
+    @Test("N3: a prediction above the VDR range keeps its overshoot until the residual is added")
+    func predictionOvershootKeptBeforeResidual() throws {
+        let composer = try #require(DoviFelComposer())
+        // Prediction 1.02 -> 4178 12-bit codes (above vdr_max 4095); EL 312 -> r = -200 -> (399 * 2048) >> 12 = 199 -> -199.
+        // Clamping the prediction first would give 4095 - 199 = 3896; adding first gives 4178 - 199 = 3979.
+        var p = Self.rawParams(residual: true)
+        p.polyY = Self.polynomial(1.02, order: 0)
+        p.nlqY = DoviGpuEdgeCaseTests.nlq(vdrInMax: 4095)
+        let out = try DoviGpuEdgeCaseTests.composeConstant(composer, bl: (512, 512, 512), el: (312, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [3979])
+    }
+
+    // MARK: - D2: chroma MMR on a real RPU
+
+    @Test("D2: clip A order-3 chroma MMR parses, and maps mid-grey to mid-grey and a Cb sweep to the pinned curve")
+    func chromaMmrOnRealRpu() throws {
+        let clipABytes = Self.hexToBytes(Self.clipARpuHex)
+        let rpu = try #require(dovi_parse_unspec62_nalu(clipABytes, clipABytes.count))
+        defer { dovi_rpu_free(rpu) }
+        #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")")
+        var params = try #require(DoviFelComposer.parseRpuParameters(rpu: rpu))
+
+        #expect(params.polyCb.usesMmr, "Cb curve must be MMR on clip A")
+        #expect(params.polyCr.usesMmr, "Cr curve must be MMR on clip A")
+        #expect(params.polyCb.order[0] == 3, Comment("Cb MMR order must be 3, got \(params.polyCb.order[0])"))
+        #expect(params.polyCr.order[0] == 3, Comment("Cr MMR order must be 3, got \(params.polyCr.order[0])"))
+        #expect(params.mmrCb.coefShift == 23, "MMR coef shift must be 23")
+
+        params.ditherMode = .debugRawVDR
+        params.flags.insert(.disableResidual)
+        let composer = try #require(DoviFelComposer())
+
+        // Chroma plane is 1024 wide for a 2048-wide base layer: column c carries Cb = c, with Y and Cr at mid-grey.
+        let bl = try #require(H.makeBuffer(width: 2048, height: 4))
+        let el = try #require(H.makeBuffer(width: 1024, height: 2))
+        H.fillPlane(bl, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(bl, plane: 1, components: 2) { c, _, comp in comp == 0 ? c : 512 }
+        H.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+        let out = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params))
+        let planes = DoviTestSupport.rawVDR(out, chromaOnly: true)
+        let cb = Array(planes[1][0..<1024]).map { Double($0) / 4.0 }   // 10-bit equivalent codes
+        let cr = Array(planes[2][0..<1024]).map { Double($0) / 4.0 }
+
+        // Mid-grey in, mid-grey out: the property the flat-64 green collapse violated.
+        #expect(abs(cb[512] - 512.0) < 2.0, "Cb(512) must be ~512, got \(cb[512])")
+        #expect(abs(cr[512] - 512.0) < 2.0, "Cr at mid-grey input must be ~512, got \(cr[512])")
+
+        let span = (cb.max() ?? 0) - (cb.min() ?? 0)
+        #expect(span > 500.0, "Cb curve is nearly flat over the full input range (span \(span) codes)")
+        var violations = 0
+        for code in 1..<1024 where cb[code] < cb[code - 1] - 1.0 { violations += 1 }
+        #expect(violations == 0, "Cb curve must be non-decreasing in its own component, \(violations) violations")
+
+        // Regression anchors measured off this RPU through the composer (not independently derived; mid-grey above
+        // is the derived check). They catch a piece, an order or a coefficient index shifting.
+        for (code, anchor) in Self.chromaAnchors {
+            #expect(abs(cb[code] - anchor) < 1.0, "Cb(\(code)) drifted: \(cb[code]), pinned \(anchor)")
+        }
+    }
+
+    private static let chromaAnchors: [(Int, Double)] = [(0, 0.0), (256, 222.5), (768, 886.75), (1023, 1023.75)]
+
+    // MARK: - Metal GPU Composition & Pixel Sanity Assertions
+
+    @Test("Metal GPU Composition: Real RPU reconstructs 10-bit P010 without flat-64 green chroma")
+    func metalGpuCompositionSanity() throws {
+        guard let composer = DoviFelComposer() else {
+            Issue.record("Failed to initialize DoviFelComposer")
+            return
+        }
+
+        let clipABytes = Self.hexToBytes(Self.clipARpuHex)
+        guard let rpu = dovi_parse_unspec62_nalu(clipABytes, clipABytes.count) else {
+            Issue.record("Failed to parse clip A RPU")
+            return
+        }
+        defer { dovi_rpu_free(rpu) }
+        // libdovi returns a handle even when parsing fails; only the error says it was accepted.
+        #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")")
+        guard let params = DoviFelComposer.parseRpuParameters(rpu: rpu) else {
+            Issue.record("Failed to parse clip A RPU")
+            return
+        }
+
+        let w = 256, h = 256
+        let pixelFormat = kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange
+
+        var blBufferOpt: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, w, h, pixelFormat, [
+            kCVPixelBufferMetalCompatibilityKey: true,
+            kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary
+        ] as CFDictionary, &blBufferOpt)
+
+        var elBufferOpt: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, w / 2, h / 2, pixelFormat, [
+            kCVPixelBufferMetalCompatibilityKey: true,
+            kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary
+        ] as CFDictionary, &elBufferOpt)
+
+        guard let blBuffer = blBufferOpt, let elBuffer = elBufferOpt else {
+            Issue.record("Failed to allocate CVPixelBuffers")
+            return
+        }
+
+        // Mid-grey base layer (luma 512, Cb/Cr 512) and a neutral enhancement
+        // layer (512, the NLQ offset, so the residual is zero).
+        //
+        // Both go through the stride-aware helper. The previous version walked each
+        // plane as `width * height` contiguous samples, which ignores row padding
+        // and, for the enhancement layer's chroma plane, computed twice the
+        // sample count the plane holds: it wrote 16 KiB past the end and faulted
+        // whenever the pages behind the IOSurface happened not to be mapped.
+        DoviGpuCurveSweepTests.fillPlane(blBuffer, plane: 0, components: 1) { _, _, _ in 512 }
+        DoviGpuCurveSweepTests.fillPlane(blBuffer, plane: 1, components: 2) { _, _, _ in 512 }
+        DoviGpuCurveSweepTests.fillPlane(elBuffer, plane: 0, components: 1) { _, _, _ in 512 }
+        DoviGpuCurveSweepTests.fillPlane(elBuffer, plane: 1, components: 2) { _, _, _ in 512 }
+
+        // Execute Metal GPU composition
+        guard let dst = composer.compose(
+            baseBuffer: blBuffer,
+            enhancementBuffer: elBuffer,
+            params: params,
+            frameIndex: 1
+        ) else {
+            Issue.record("Composer returned nil")
+            return
+        }
+
+        // Read back output pixels and assert that chroma is NOT flat 64
+        CVPixelBufferLockBaseAddress(dst, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(dst, .readOnly) }
+
+        guard let outUvPtr = CVPixelBufferGetBaseAddressOfPlane(dst, 1) else {
+            Issue.record("No output chroma plane")
+            return
+        }
+
+        let outUv = outUvPtr.assumingMemoryBound(to: UInt16.self)
+        let sampleCb = Int(outUv[0] >> 6)
+        let sampleCr = Int(outUv[1] >> 6)
+
+        // Mid-gray in -> mid-gray out (~512). A flat 64 would be the green-frame failure.
+        #expect(sampleCb > 400 && sampleCb < 600, "Output Cb sample must be near mid-gray (~512), was \(sampleCb) (D2 flat 64 regression)")
+        #expect(sampleCr > 400 && sampleCr < 600, "Output Cr sample must be near mid-gray (~512), was \(sampleCr) (D2 flat 64 regression)")
+
+        guard let outYPtr = CVPixelBufferGetBaseAddressOfPlane(dst, 0) else {
+            Issue.record("No output luma plane")
+            return
+        }
+        let outY = outYPtr.assumingMemoryBound(to: UInt16.self)
+        let sampleY = Int(outY[0] >> 6)
+        #expect(sampleY > 400 && sampleY < 600, "Output Y sample must be near mid-gray (~512), was \(sampleY)")
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
new file mode 100644
index 000000000..992f4bd41
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -0,0 +1,46 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// End-to-end FEL checks on real Profile 7 files, where the synthetic suites
+/// cannot reach: container framing quirks (the Matroska `packet->data != buf->data`
+/// case that produced zero frames), real RPUs, real reorder, seeks and teardown.
+///
+/// The fixtures (`fel-clip-a.mkv`, `fel-clip-b.mkv`, `fel-clip-c.mp4`) live in the
+/// directory named by `DV_FEL_TESTS_DIR`, or in `DV FEL Tests/` next to the package;
+/// they are not checked in, and every test skips when its file is absent.
+struct DoviFelRealFileTests {
+
+    static let fixtures = [
+        "fel-clip-a.mkv",
+        "fel-clip-b.mkv",
+        "fel-clip-c.mp4",
+    ]
+
+    static func url(_ name: String) -> URL {
+        if let dir = ProcessInfo.processInfo.environment["DV_FEL_TESTS_DIR"] {
+            return URL(fileURLWithPath: dir).appendingPathComponent(name)
+        }
+        return URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()   // AetherEngineTests
+            .deletingLastPathComponent()   // Tests
+            .deletingLastPathComponent()   // AetherEngine
+            .deletingLastPathComponent()   // repo root
+            .appendingPathComponent("DV FEL Tests")
+            .appendingPathComponent(name)
+    }
+
+    static func available(_ name: String) -> Bool {
+        FileManager.default.fileExists(atPath: url(name).path)
+    }
+
+    /// The `.enabled(if:)` reason of every test that needs a clip: the clips are not checked in, so
+    /// those tests show as skipped without them rather than passing without having run.
+    static let needsClips: Comment = "needs the DV FEL test clips (not checked in): set DV_FEL_TESTS_DIR"
+
+    /// The fixtures present, for `arguments:` of a test that runs once per clip.
+    static var availableFixtures: [String] { fixtures.filter(available) }
+
+    /// The first two clips, when present: the ones long enough to seek into.
+    static var firstTwoClips: [String] { [fixtures[0], fixtures[1]].filter(available) }
+}
diff --git a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
new file mode 100644
index 000000000..e39d0f257
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
@@ -0,0 +1,210 @@
+import Testing
+import Foundation
+import CoreVideo
+@testable import AetherEngine
+
+/// Hostile parameter blocks and content thrown at the composition kernels. The RPU guard and the
+/// parser should never let such values through, but the kernels are the last line: whatever arrives,
+/// they must neither hang nor write outside the legal output range, and must be deterministic.
+struct DoviGpuAdversarialTests {
+
+    typealias H = DoviGpuCurveSweepTests
+
+    struct RNG: RandomNumberGenerator {
+        var s: UInt64
+        mutating func next() -> UInt64 { s = s &* 6364136223846793005 &+ 1442695040888963407; return s ^ (s >> 29) }
+    }
+
+    static let extremes: [Int32] = [0, 1, -1, 2, 1 << 15, -(1 << 15), 1 << 23, -(1 << 23), 1 << 30, Int32.max, Int32.min, Int32.min + 1]
+
+    static func i32(_ r: inout RNG) -> Int32 {
+        r.next() % 3 == 0 ? extremes[Int(r.next() % UInt64(extremes.count))] : Int32(truncatingIfNeeded: r.next())
+    }
+    static func u32(_ r: inout RNG, _ cap: UInt32) -> UInt32 {
+        r.next() % 4 == 0 ? [0, 1, cap, cap + 1, UInt32.max][Int(r.next() % 5)] : UInt32(r.next() % UInt64(cap + 1))
+    }
+
+    static func hostileCurve(_ r: inout RNG) -> DoviPolynomialParams {
+        var c = DoviPolynomialParams()
+        c.numPivots = u32(&r, 12)
+        for i in 0..<c.pivots.count { c.pivots[i] = u32(&r, 1100) }   // not sorted on purpose
+        for i in 0..<DoviPolynomialParams.maxPieces {
+            c.method[i] = r.next() % 2 == 0 ? 0 : (r.next() % 2 == 0 ? 1 : UInt32.max)
+            c.order[i] = u32(&r, 5)
+            c.coef[i] = [i32(&r), i32(&r), i32(&r)]
+            c.coefShift[i] = u32(&r, 40)
+        }
+        return c
+    }
+
+    static func hostileMmr(_ r: inout RNG) -> DoviMmrParams {
+        var m = DoviMmrParams()
+        for i in 0..<m.constant.count {
+            m.constant[i] = i32(&r)
+            for j in 0..<m.coef[i].count { m.coef[i][j] = i32(&r) }
+        }
+        m.coefShift = u32(&r, 40)
+        return m
+    }
+
+    static func hostileNlq(_ r: inout RNG) -> DoviNlqParams {
+        var n = DoviNlqParams()
+        n.nlqMethod = r.next() % 4 == 0 ? .none : .linear
+        n.nlqOffset = i32(&r); n.nlqScale = i32(&r); n.nlqThreshold = i32(&r); n.vdrInMax = i32(&r)
+        n.nlqShift = u32(&r, 40)
+        return n
+    }
+
+    static func hostile(_ r: inout RNG, w: Int, h: Int) -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.blWidth = UInt32(w); p.blHeight = UInt32(h); p.elWidth = UInt32(w / 2); p.elHeight = UInt32(h / 2)
+        p.ditherMode = [.none, .bayer8x8, .fullPrecision][Int(r.next() % 3)]
+        p.frameIndex = UInt32(truncatingIfNeeded: r.next())
+        var f = DoviComposerFlags()
+        if r.next() % 4 == 0 { f.insert(.disableResidual) }
+        if r.next() % 2 == 0 { f.insert(.lumaMmr) }
+        p.flags = f
+        p.polyY = hostileCurve(&r); p.polyCb = hostileCurve(&r); p.polyCr = hostileCurve(&r)
+        p.mmrY = hostileMmr(&r); p.mmrCb = hostileMmr(&r); p.mmrCr = hostileMmr(&r)
+        p.nlqY = hostileNlq(&r); p.nlqCb = hostileNlq(&r); p.nlqCr = hostileNlq(&r)
+        // Bit depths straight from the parser's validated set, plus one the setter refuses.
+        let depths = [(10, 12), (10, 10), (8, 12), (10, 16), (12, 12), (16, 16)]
+        let d = depths[Int(r.next() % UInt64(depths.count))]
+        _ = p.setBitDepths(bl: d.0, vdr: d.1)
+        if r.next() % 8 == 0 { p.blMax = u32(&r, 70000); p.vdrMax = u32(&r, 70000); p.vdrScale = u32(&r, 70000) }
+        return p
+    }
+
+    static func words(_ b: CVPixelBuffer, plane: Int) -> [UInt16] {
+        CVPixelBufferLockBaseAddress(b, .readOnly); defer { CVPixelBufferUnlockBaseAddress(b, .readOnly) }
+        let base = CVPixelBufferGetBaseAddressOfPlane(b, plane)!
+        let bpr = CVPixelBufferGetBytesPerRowOfPlane(b, plane)
+        let w = CVPixelBufferGetWidthOfPlane(b, plane) * (plane == 0 ? 1 : 2), hh = CVPixelBufferGetHeightOfPlane(b, plane)
+        var out: [UInt16] = []
+        for y in 0..<hh {
+            let row = (base + y * bpr).assumingMemoryBound(to: UInt16.self)
+            out.append(contentsOf: UnsafeBufferPointer(start: row, count: w))
+        }
+        return out
+    }
+
+    @Test("hostile parameters and random content: always finishes, stays in the legal range, is deterministic",
+          arguments: Array(UInt64(1)...48))
+    func hostileParameters(seed: UInt64) throws {
+        var r = RNG(s: seed &* 0x9E3779B97F4A7C15)
+        let composer = try #require(DoviFelComposer())
+        let w = 96, h = 48
+        for iter in 0..<40 {
+            let params = Self.hostile(&r, w: w, h: h)
+            let bl = try #require(H.makeBuffer(width: w, height: h))
+            let el = try #require(H.makeBuffer(width: w / 2, height: h / 2))
+            var s = RNG(s: UInt64(iter) &+ seed &* 77)
+            let full = s.next() % 3 == 0   // sometimes use the full 16-bit word range, not just 10-bit codes
+            func code(_ s: inout RNG) -> Int { full ? Int(s.next() & 0xFFFF) >> 6 : Int(s.next() % 1024) }
+            H.fillPlane(bl, plane: 0, components: 1) { _, _, _ in code(&s) }
+            H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in code(&s) }
+            H.fillPlane(el, plane: 0, components: 1) { _, _, _ in code(&s) }
+            H.fillPlane(el, plane: 1, components: 2) { _, _, _ in code(&s) }
+
+            let a = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 0),
+                                 "seed \(seed) iter \(iter) refused a well-formed buffer pair")
+            let aY = Self.words(a, plane: 0), aC = Self.words(a, plane: 1)
+            let b = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 0))
+            #expect(aY == Self.words(b, plane: 0) && aC == Self.words(b, plane: 1), "seed \(seed) iter \(iter) is not deterministic")
+
+            let bad = aY.filter { ($0 >> 6) < 64 || ($0 >> 6) > 940 }.count + aC.filter { ($0 >> 6) < 64 || ($0 >> 6) > 960 }.count
+            #expect(bad == 0, "seed \(seed) iter \(iter): \(bad) samples outside video range (dither \(params.ditherMode), blMax \(params.blMax), vdrMax \(params.vdrMax), vdrScale \(params.vdrScale))")
+        }
+    }
+
+    @Test("parameters that lie about the buffer size cannot read or write out of bounds")
+    func lyingGeometry() throws {
+        let composer = try #require(DoviFelComposer())
+        let bl = try #require(H.makeBuffer(width: 64, height: 32))
+        let el = try #require(H.makeBuffer(width: 32, height: 16))
+        H.fillPlane(bl, plane: 0, components: 1) { x, y, _ in (x * 7 + y * 13) & 1023 }
+        H.fillPlane(bl, plane: 1, components: 2) { x, y, _ in (x * 5 + y * 3) & 1023 }
+        H.fillPlane(el, plane: 0, components: 1) { x, y, _ in (x * 11 + y) & 1023 }
+        H.fillPlane(el, plane: 1, components: 2) { x, y, _ in (x + y * 9) & 1023 }
+        let cases: [(UInt32, UInt32, UInt32, UInt32)] = [
+            (0, 0, 0, 0), (1, 1, 1, 1), (64, 32, 0, 0), (64, 32, 1, 1), (64, 32, 4096, 4096),
+            (4096, 4096, 32, 16), (UInt32.max, UInt32.max, UInt32.max, UInt32.max), (64, 32, 31, 15), (65, 33, 32, 16),
+        ]
+        for (bw, bh, ew, eh) in cases {
+            var p = DoviGpuEdgeCaseTests.params()
+            p.blWidth = bw; p.blHeight = bh; p.elWidth = ew; p.elHeight = eh
+            // Either refused or composed at the real buffer geometry; never a crash or a hang.
+            if let out = composer.compose(baseBuffer: bl, enhancementBuffer: el, params: p, frameIndex: 0) {
+                #expect(CVPixelBufferGetWidth(out) == 64 && CVPixelBufferGetHeight(out) == 32, "output must follow the real base buffer, not the claimed size")
+                let y = Self.words(out, plane: 0)
+                #expect(y.allSatisfy { ($0 >> 6) >= 64 && ($0 >> 6) <= 940 })
+            }
+        }
+    }
+}
+
+extension DoviGpuAdversarialTests {
+    /// Production drives the composer through the async API, which owns the in-flight slot accounting;
+    /// the synchronous `compose` is single-threaded by contract.
+    @Test("concurrent async composes at changing resolutions neither deadlock nor corrupt each other")
+    func concurrentComposeWithResolutionChanges() async throws {
+        let composer = try #require(DoviFelComposer())
+        let sizes = [(64, 16), (128, 32), (96, 48), (256, 64)]
+        let results = await withTaskGroup(of: Bool.self, returning: [Bool].self) { group in
+            for t in 0..<6 {
+                group.addTask {
+                    var ok = true
+                    for i in 0..<60 {
+                        let (w, h) = sizes[(t + i / 5) % sizes.count]
+                        guard let bl = H.makeBuffer(width: w, height: h), let el = H.makeBuffer(width: w / 2, height: h / 2) else { return false }
+                        H.fillPlane(bl, plane: 0, components: 1) { _, _, _ in 512 + t * 10 }
+                        H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+                        H.fillPlane(el, plane: 0, components: 1) { _, _, _ in 612 }
+                        H.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+                        let good: Bool = await withCheckedContinuation { c in
+                            composer.composeAsync(baseBuffer: bl, enhancementBuffer: el,
+                                                  params: DoviGpuEdgeCaseTests.params(), frameIndex: UInt32(i)) { out in
+                                guard let out else { c.resume(returning: false); return }
+                                c.resume(returning: CVPixelBufferGetWidth(out) == w && Set(Self.words(out, plane: 0)).count == 1)
+                            }
+                        }
+                        ok = ok && good
+                    }
+                    return ok
+                }
+            }
+            var r: [Bool] = []
+            for await v in group { r.append(v) }
+            return r
+        }
+        #expect(results.count == 6 && results.allSatisfy { $0 })
+        composer.acquireSlot(); composer.releaseSlot()
+    }
+}
+
+extension DoviGpuAdversarialTests {
+    /// The spec's fixed-point pseudo-code and the DoViBaker oracle normalise by 2^bits both
+    /// ways, so a curve value of exactly one half is exactly the middle of the VDR range. Normalising by
+    /// 2^bits - 1 put the same neutral chroma at 2049 (clip A) and as low as 2041 (clip B).
+    @Test("a curve value of one half lands on exactly 2048, through polynomial and MMR constants",
+          arguments: [false, true])
+    func halfIsExactlyMidRange(mmr: Bool) throws {
+        let composer = try #require(DoviFelComposer())
+        var p = DoviGpuEdgeCaseTests.params(flags: [.disableResidual])
+        p.ditherMode = .debugRawVDR
+        var curve = DoviPolynomialParams()
+        curve.numPivots = 2; curve.pivots[0] = 0; curve.pivots[1] = 1023
+        curve.order[0] = 1; curve.coefShift[0] = 23
+        if mmr {
+            curve.method[0] = DoviMapping.mmr.rawValue
+            var m = DoviMmrParams(); m.constant[0] = 1 << 22; m.coefShift = 23
+            p.mmrCb = m; p.mmrCr = m
+        } else {
+            curve.method[0] = DoviMapping.polynomial.rawValue
+            curve.coef[0] = [1 << 22, 0, 0]
+        }
+        p.polyCb = curve; p.polyCr = curve
+        let out = try DoviGpuEdgeCaseTests.composeConstant(composer, bl: (512, 700, 300), el: (512, 512, 512), params: p)
+        for plane in DoviTestSupport.rawVDR(out)[1...] { #expect(Set(plane) == [2048]) }
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
new file mode 100644
index 000000000..d142ab989
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
@@ -0,0 +1,393 @@
+import Testing
+import Foundation
+import CoreVideo
+import Metal
+@testable import AetherEngine
+
+/// Runs the real composition kernels over every base-layer code and compares the
+/// result against ``DolbyVisionStillConverter/ReshapeCurve`` in Swift.
+///
+/// The rest of the suite re-implements the shader's arithmetic in Swift and tests
+/// the re-implementation, so it would pass unchanged if the Metal source diverged
+/// from it. These tests execute `dovi_compose_luma` and `dovi_compose_chroma` and
+/// read the output planes back, which is the only way the two can disagree and be
+/// caught. They are built around the cases a single-piece test cannot see:
+/// per-piece order, per-piece coefficient denominators, and per-piece MMR
+/// coefficients.
+struct DoviGpuCurveSweepTests {
+
+    static let blWidth = 1024
+    static let blHeight = 4
+
+    // MARK: - Buffer helpers
+
+    static func makeBuffer(width: Int, height: Int) -> CVPixelBuffer? {
+        var buffer: CVPixelBuffer?
+        CVPixelBufferCreate(
+            kCFAllocatorDefault, width, height,
+            kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+            [
+                kCVPixelBufferMetalCompatibilityKey: true,
+                kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary
+            ] as CFDictionary,
+            &buffer
+        )
+        return buffer
+    }
+
+    /// Writes one 10-bit code per (plane, column, row) through `value`, honouring
+    /// the plane's own stride. P010 is MSB-aligned, hence the shift by 6.
+    static func fillPlane(
+        _ buffer: CVPixelBuffer,
+        plane: Int,
+        components: Int,
+        _ value: (_ column: Int, _ row: Int, _ component: Int) -> Int
+    ) {
+        CVPixelBufferLockBaseAddress(buffer, [])
+        defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+        guard let base = CVPixelBufferGetBaseAddressOfPlane(buffer, plane) else { return }
+        let bytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(buffer, plane)
+        let width = CVPixelBufferGetWidthOfPlane(buffer, plane)
+        let height = CVPixelBufferGetHeightOfPlane(buffer, plane)
+        for row in 0..<height {
+            let rowPtr = (base + row * bytesPerRow).assumingMemoryBound(to: UInt16.self)
+            for column in 0..<width {
+                for c in 0..<components {
+                    rowPtr[column * components + c] = UInt16(value(column, row, c) << 6)
+                }
+            }
+        }
+    }
+
+    static func readPlane(
+        _ buffer: CVPixelBuffer,
+        plane: Int,
+        components: Int,
+        row: Int
+    ) -> [[Int]] {
+        CVPixelBufferLockBaseAddress(buffer, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(buffer, .readOnly) }
+        guard let base = CVPixelBufferGetBaseAddressOfPlane(buffer, plane) else { return [] }
+        let bytesPerRow = CVPixelBufferGetBytesPerRowOfPlane(buffer, plane)
+        let width = CVPixelBufferGetWidthOfPlane(buffer, plane)
+        let rowPtr = (base + row * bytesPerRow).assumingMemoryBound(to: UInt16.self)
+        var out: [[Int]] = []
+        out.reserveCapacity(width)
+        for column in 0..<width {
+            var sample: [Int] = []
+            for c in 0..<components {
+                sample.append(Int(rowPtr[column * components + c] >> 6))
+            }
+            out.append(sample)
+        }
+        return out
+    }
+
+    // MARK: - Reference output stage
+
+    /// The quantisation the kernels apply after the curve: denormalise by
+    /// `bl_max * vdr_scale`, clamp to the VDR range, then round down to the output
+    /// plane and clamp to video range. Dither is off for these tests, so the
+    /// kernel's bias is a flat 0.5 and the result is exactly reproducible.
+    static func quantize(predNorm: Double, blMax: Int, vdrScale: Int, vdrMax: Int, lo: Int, hi: Int) -> Int {
+        let vdr = min(max(Int((predNorm * Double(blMax) * Double(vdrScale)).rounded(.toNearestOrEven)), 0), vdrMax)
+        let scaled = Double(vdr) / Double(vdrScale)
+        return min(max(Int(floor(scaled + 0.5)), lo), hi)
+    }
+
+    /// Exact value of an RPU-style Q(shift) coefficient, so the reference and the
+    /// shader are compared on the same number rather than on the intended one.
+    static func fp(_ value: Double, shift: UInt32) -> (fixed: Int32, exact: Double) {
+        let scale = Double(1 << shift)
+        let fixed = Int32(value * scale)
+        return (fixed, Double(fixed) / scale)
+    }
+
+    static func identityCurve() -> DoviPolynomialParams {
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 2
+        poly.pivots[0] = 0
+        poly.pivots[1] = 1023
+        poly.method[0] = DoviMapping.polynomial.rawValue
+        poly.order[0] = 1
+        poly.coef[0] = [0, 1 << 23, 0]
+        poly.coefShift[0] = 23
+        return poly
+    }
+
+    // MARK: - Luma: multi-piece polynomial
+
+    @Test("GPU luma sweep: a 3-piece polynomial with per-piece order and denominator matches the reference curve")
+    func lumaMultiPiecePolynomialSweep() throws {
+        guard let composer = DoviFelComposer() else {
+            Issue.record("Failed to initialize DoviFelComposer")
+            return
+        }
+
+        let blMax = 1023
+        let pivotCodes: [UInt32] = [0, 256, 700, 1023]
+
+        // Piece 1 deliberately uses a different coefficient denominator and a
+        // quadratic term: a kernel that read piece 0's order or shift for every
+        // piece would pass a single-piece test and fail here.
+        let shifts: [UInt32] = [23, 20, 23]
+        let intended: [[Double]] = [
+            [0.08, 0.90, 0.00],
+            [0.05, 0.70, 0.20],
+            [0.30, 0.55, 0.00]
+        ]
+        let orders: [UInt32] = [1, 2, 1]
+
+        var poly = DoviPolynomialParams()
+        poly.numPivots = UInt32(pivotCodes.count)
+        for (i, pivot) in pivotCodes.enumerated() { poly.pivots[i] = pivot }
+
+        var exact: [[Double]] = []
+        for piece in 0..<3 {
+            poly.method[piece] = DoviMapping.polynomial.rawValue
+            poly.order[piece] = orders[piece]
+            poly.coefShift[piece] = shifts[piece]
+            var row: [Double] = []
+            for j in 0..<3 {
+                let c = Self.fp(intended[piece][j], shift: shifts[piece])
+                // Coefficients above the piece's order are not read by the kernel,
+                // so the reference must zero them rather than trust the table.
+                let live = UInt32(j) <= orders[piece]
+                poly.coef[piece][j] = live ? c.fixed : 0
+                row.append(live ? c.exact : 0)
+            }
+            exact.append(row)
+        }
+
+        var params = DoviMetalParams()
+        params.ditherMode = .none
+        params.flags = [.disableResidual]   // this test is about the curve, not the residual
+        params.polyY = poly
+        params.polyCb = Self.identityCurve()
+        params.polyCr = Self.identityCurve()
+
+        guard let bl = Self.makeBuffer(width: Self.blWidth, height: Self.blHeight),
+              let el = Self.makeBuffer(width: Self.blWidth / 2, height: Self.blHeight / 2) else {
+            Issue.record("Failed to allocate CVPixelBuffers")
+            return
+        }
+        // One base-layer code per column, so a single row of output covers the
+        // whole 10-bit input domain.
+        Self.fillPlane(bl, plane: 0, components: 1) { column, _, _ in column }
+        Self.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+        Self.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        Self.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+
+        guard let dst = composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 0) else {
+            Issue.record("Composer returned nil")
+            return
+        }
+
+        let reference = DolbyVisionStillConverter.ReshapeCurve(
+            pivots: pivotCodes.map { Double($0) / Double(blMax) },
+            isMMR: [false, false, false],
+            poly: exact,
+            mmrOrder: [0, 0, 0],
+            mmrConst: [0, 0, 0],
+            mmrCoef: [[[]], [[]], [[]]]
+        )
+
+        let output = Self.readPlane(dst, plane: 0, components: 1, row: 0)
+        #expect(output.count == Self.blWidth)
+
+        var worst = 0
+        var worstCode = -1
+        for code in 0..<min(output.count, 1024) {
+            let x = Double(code) / Double(blMax)
+            let expected = Self.quantize(
+                predNorm: reference.map(x, (x, 0.5, 0.5)),
+                blMax: blMax, vdrScale: 4, vdrMax: 4095, lo: 64, hi: 940
+            )
+            let diff = abs(output[code][0] - expected)
+            if diff > worst {
+                worst = diff
+                worstCode = code
+            }
+        }
+        #expect(worst <= 1,
+                "GPU luma output diverges from the reference curve by \(worst) codes at BL \(worstCode)")
+
+        // A curve that landed on a single piece everywhere, or collapsed to
+        // identity, would still satisfy a tolerance check, so pin two interior
+        // points that only the correct piece can produce.
+        // BL 100 sits in piece 0: 0.08 + 0.9 * 100/1023 = 0.1680 -> 172.
+        // BL 900 sits in piece 2: 0.30 + 0.55 * 900/1023 = 0.7839 -> 802.
+        #expect(abs(output[100][0] - 172) <= 1, "piece 0 not applied at BL 100: got \(output[100][0])")
+        #expect(abs(output[900][0] - 802) <= 1, "piece 2 not applied at BL 900: got \(output[900][0])")
+    }
+
+    // MARK: - Chroma: per-piece MMR
+
+    @Test("GPU chroma sweep: MMR coefficients are read per reshaping piece, not only from piece 0")
+    func chromaPerPieceMmrSweep() throws {
+        guard let composer = DoviFelComposer() else {
+            Issue.record("Failed to initialize DoviFelComposer")
+            return
+        }
+
+        let blMax = 1023
+        let shift: UInt32 = 23
+        let pivotCodes: [UInt32] = [0, 512, 1023]
+
+        // Two MMR pieces whose coefficients differ enough that reading piece 0 for
+        // the whole range is off by ~160 codes at the top of the sweep, well past
+        // any float tolerance. Piece 1 is order 2, so it also catches an
+        // implementation that reuses piece 0's order.
+        let constants = [Self.fp(0.02, shift: shift), Self.fp(-0.05, shift: shift)]
+        let piece0Order0 = [0.10, 0.80, 0.05, 0, 0, 0, 0]
+        let piece1Order0 = [0.05, 1.10, 0.02, 0, 0, 0, 0]
+        let piece1Order1 = [0.00, -0.35, 0.00, 0, 0, 0, 0]
+
+        var poly = DoviPolynomialParams()
+        poly.numPivots = UInt32(pivotCodes.count)
+        for (i, pivot) in pivotCodes.enumerated() { poly.pivots[i] = pivot }
+        poly.method[0] = DoviMapping.mmr.rawValue
+        poly.method[1] = DoviMapping.mmr.rawValue
+        poly.order[0] = 1
+        poly.order[1] = 2
+
+        var mmr = DoviMmrParams()
+        mmr.coefShift = shift
+        mmr.constant[0] = constants[0].fixed
+        mmr.constant[1] = constants[1].fixed
+
+        var exactCoef: [[[Double]]] = [
+            [Array(repeating: 0.0, count: 7), Array(repeating: 0.0, count: 7), Array(repeating: 0.0, count: 7)],
+            [Array(repeating: 0.0, count: 7), Array(repeating: 0.0, count: 7), Array(repeating: 0.0, count: 7)]
+        ]
+        for (k, value) in piece0Order0.enumerated() {
+            let c = Self.fp(value, shift: shift)
+            mmr.coef[0][k] = c.fixed
+            exactCoef[0][0][k] = c.exact
+        }
+        for (k, value) in piece1Order0.enumerated() {
+            let c = Self.fp(value, shift: shift)
+            mmr.coef[1][k] = c.fixed
+            exactCoef[1][0][k] = c.exact
+        }
+        for (k, value) in piece1Order1.enumerated() {
+            let c = Self.fp(value, shift: shift)
+            mmr.coef[1][7 + k] = c.fixed
+            exactCoef[1][1][k] = c.exact
+        }
+
+        var params = DoviMetalParams()
+        params.ditherMode = .none
+        params.flags = [.disableResidual]
+        params.polyY = Self.identityCurve()
+        params.polyCb = poly
+        params.mmrCb = mmr
+        params.polyCr = Self.identityCurve()
+
+        guard let bl = Self.makeBuffer(width: Self.blWidth, height: Self.blHeight),
+              let el = Self.makeBuffer(width: Self.blWidth / 2, height: Self.blHeight / 2) else {
+            Issue.record("Failed to allocate CVPixelBuffers")
+            return
+        }
+        // Constant luma so the cross terms are a known y, and two codes of Cb per
+        // chroma column so the 512-wide plane still sweeps the full input range.
+        let lumaCode = 512
+        Self.fillPlane(bl, plane: 0, components: 1) { _, _, _ in lumaCode }
+        Self.fillPlane(bl, plane: 1, components: 2) { column, _, component in
+            component == 0 ? min(column * 2, 1023) : 512
+        }
+        Self.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        Self.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+
+        guard let dst = composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 0) else {
+            Issue.record("Composer returned nil")
+            return
+        }
+
+        let reference = DolbyVisionStillConverter.ReshapeCurve(
+            pivots: pivotCodes.map { Double($0) / Double(blMax) },
+            isMMR: [true, true],
+            poly: [[0, 0, 0], [0, 0, 0]],
+            mmrOrder: [1, 2],
+            mmrConst: [constants[0].exact, constants[1].exact],
+            mmrCoef: exactCoef
+        )
+
+        let output = Self.readPlane(dst, plane: 1, components: 2, row: 0)
+        #expect(output.count == Self.blWidth / 2)
+
+        let y = Double(lumaCode) / Double(blMax)
+        let v = Double(512) / Double(blMax)
+
+        var worst = 0
+        var worstColumn = -1
+        for column in 0..<output.count {
+            let cbCode = min(column * 2, 1023)
+            let u = Double(cbCode) / Double(blMax)
+            let expected = Self.quantize(
+                predNorm: reference.map(u, (y, u, v)),
+                blMax: blMax, vdrScale: 4, vdrMax: 4095, lo: 64, hi: 960
+            )
+            let diff = abs(output[column][0] - expected)
+            if diff > worst {
+                worst = diff
+                worstColumn = column
+            }
+            // Cr is identity, so it also shows whether the two curves were mixed up.
+            #expect(abs(output[column][1] - 512) <= 1,
+                    "Cr must pass through at 512, got \(output[column][1]) at column \(column)")
+        }
+        #expect(worst <= 2,
+                "GPU chroma output diverges from the reference MMR curve by \(worst) codes at column \(worstColumn)")
+
+        // Explicit N4 guard: at the top of the range piece 1 must be in force.
+        // Piece 1 at u = 1022/1023 gives ~0.7372 -> ~754 codes; evaluating piece 0
+        // there would give ~0.9207 -> ~942, so the two readings cannot be confused.
+        let top = output.count - 1
+        #expect(output[top][0] < 800,
+                "the top of the sweep used piece 0's MMR coefficients: got \(output[top][0])")
+    }
+
+    // MARK: - Identity is bit-exact
+
+    @Test("GPU identity curve is bit-exact: every base-layer code survives the round trip")
+    func identityCurveIsBitExact() throws {
+        guard let composer = DoviFelComposer() else {
+            Issue.record("Failed to initialize DoviFelComposer")
+            return
+        }
+
+        var params = DoviMetalParams()
+        params.ditherMode = .none
+        params.flags = [.disableResidual]
+        params.polyY = Self.identityCurve()
+        params.polyCb = Self.identityCurve()
+        params.polyCr = Self.identityCurve()
+
+        guard let bl = Self.makeBuffer(width: Self.blWidth, height: Self.blHeight),
+              let el = Self.makeBuffer(width: Self.blWidth / 2, height: Self.blHeight / 2) else {
+            Issue.record("Failed to allocate CVPixelBuffers")
+            return
+        }
+        Self.fillPlane(bl, plane: 0, components: 1) { column, _, _ in column }
+        Self.fillPlane(bl, plane: 1, components: 2) { column, _, _ in min(column * 2, 1023) }
+        Self.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        Self.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+
+        guard let dst = composer.compose(baseBuffer: bl, enhancementBuffer: el, params: params, frameIndex: 0) else {
+            Issue.record("Composer returned nil")
+            return
+        }
+
+        // Denormalising by bl_max * vdr_scale (1023 * 4) rather than vdr_max is
+        // what makes this exact; * 4095 would drift by up to 3 codes at the top.
+        let output = Self.readPlane(dst, plane: 0, components: 1, row: 0)
+        for code in 64...940 {
+            #expect(output[code][0] == code,
+                    "identity curve changed BL code \(code) into \(output[code][0])")
+        }
+        // Below and above the video range the output saturates instead.
+        #expect(output[0][0] == 64)
+        #expect(output[1023][0] == 940)
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
new file mode 100644
index 000000000..30bbc0334
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
@@ -0,0 +1,492 @@
+import Testing
+import Foundation
+import CoreVideo
+import Metal
+@testable import AetherEngine
+
+/// Edge cases for the composition kernels, executed on the GPU with expected
+/// values worked out by hand rather than by re-running the shader's arithmetic.
+///
+/// Conventions used throughout: identity curves, denominator 23, 10-bit BL into
+/// 12-bit VDR (vdr_scale 4), and an NLQ with `scale = 2048`, `shift = 11`, which is
+/// what the real P7 streams carry, so that one EL code of residual is exactly one
+/// VDR code. Dither is off so every expectation is exact.
+struct DoviGpuEdgeCaseTests {
+
+    typealias H = DoviGpuCurveSweepTests
+
+    // MARK: - Fixtures
+
+    static func nlq(
+        offset: Int32 = 512,
+        scale: Int32 = 2048,
+        threshold: Int32 = 0,
+        vdrInMax: Int32 = 512,
+        method: DoviNlqMethod = .linear
+    ) -> DoviNlqParams {
+        var n = DoviNlqParams()
+        n.nlqMethod = method
+        n.nlqOffset = offset
+        n.nlqScale = scale
+        n.nlqThreshold = threshold
+        n.vdrInMax = vdrInMax
+        n.nlqShift = 11
+        return n
+    }
+
+    static func params(
+        flags: DoviComposerFlags = [],
+        nlqY: DoviNlqParams = nlq(),
+        nlqCb: DoviNlqParams = nlq(),
+        nlqCr: DoviNlqParams = nlq()
+    ) -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.ditherMode = .none
+        p.flags = flags
+        p.polyY = H.identityCurve()
+        p.polyCb = H.identityCurve()
+        p.polyCr = H.identityCurve()
+        p.nlqY = nlqY
+        p.nlqCb = nlqCb
+        p.nlqCr = nlqCr
+        return p
+    }
+
+    /// Constant-field compose: BL (y, cb, cr) at `blWidth x blHeight`, EL
+    /// (y, cb, cr) at half that, returning the output buffer.
+    static func composeConstant(
+        _ composer: DoviFelComposer,
+        blWidth: Int = 64, blHeight: Int = 16,
+        bl: (y: Int, cb: Int, cr: Int),
+        el: (y: Int, cb: Int, cr: Int),
+        params: DoviMetalParams
+    ) throws -> CVPixelBuffer {
+        let blBuf = try #require(H.makeBuffer(width: blWidth, height: blHeight))
+        let elBuf = try #require(H.makeBuffer(width: blWidth / 2, height: blHeight / 2))
+        H.fillPlane(blBuf, plane: 0, components: 1) { _, _, _ in bl.y }
+        H.fillPlane(blBuf, plane: 1, components: 2) { _, _, c in c == 0 ? bl.cb : bl.cr }
+        H.fillPlane(elBuf, plane: 0, components: 1) { _, _, _ in el.y }
+        H.fillPlane(elBuf, plane: 1, components: 2) { _, _, c in c == 0 ? el.cb : el.cr }
+        return try #require(composer.compose(baseBuffer: blBuf, enhancementBuffer: elBuf, params: params, frameIndex: 0))
+    }
+
+    /// Every sample of a plane.
+    static func allSamples(_ buffer: CVPixelBuffer, plane: Int, components: Int) -> [[Int]] {
+        let height = CVPixelBufferGetHeightOfPlane(buffer, plane)
+        return (0..<height).flatMap { H.readPlane(buffer, plane: plane, components: components, row: $0) }
+    }
+
+    static func lumaValues(_ buffer: CVPixelBuffer) -> Set<Int> {
+        Set(allSamples(buffer, plane: 0, components: 1).map { $0[0] })
+    }
+
+    // MARK: - Residual (inverse NLQ) on the GPU
+
+    /// (EL luma code, expected output luma code) for a BL of 512.
+    /// vdr = 512 * 4 + residual; out = floor(vdr / 4 + 0.5). The residual is reconstructed at the
+    /// middle of the quantisation step, (|r| - 1/2) * scale, truncated: |r| = 1 -> 0, 2 -> 1, 3 -> 2.
+    @Test("GPU residual: positive, negative and zero residual land on the hand-computed code",
+          arguments: [
+            (612, 537),   // +100 -> 99 -> 2147 / 4 = 536.75 -> 537
+            (412, 487),   // -100 -> -99 -> 1949 / 4 = 487.25 -> 487
+            (512, 512),   // el == offset: no residual, and not zeroed out
+            (513, 512),   // +1 -> 0 -> 2048 / 4 = 512
+            (514, 512),   // +2 -> 1 -> 2049 / 4 = 512.25 -> 512
+            (515, 513),   // +3 -> 2 -> 2050 / 4 = 512.5  -> rounds up to 513
+            (511, 512),   // -1 -> 0 -> 512
+          ])
+    func residualSigns(elY: Int, expected: Int) throws {
+        let composer = try #require(DoviFelComposer())
+        let out = try Self.composeConstant(composer, bl: (512, 512, 512), el: (elY, 512, 512), params: Self.params())
+        #expect(Self.lumaValues(out) == [expected], "el=\(elY)")
+    }
+
+    @Test("GPU residual: vdr_in_max clamps the magnitude symmetrically")
+    func residualClampedByVdrInMax() throws {
+        let composer = try #require(DoviFelComposer())
+        let p = Self.params(nlqY: Self.nlq(vdrInMax: 256))
+        // +511 -> clamped to +256 -> (2048 + 256) / 4 = 576 ; -512 -> -256 -> 448
+        let hi = try Self.composeConstant(composer, bl: (512, 512, 512), el: (1023, 512, 512), params: p)
+        let lo = try Self.composeConstant(composer, bl: (512, 512, 512), el: (0, 512, 512), params: p)
+        #expect(Self.lumaValues(hi) == [576])
+        #expect(Self.lumaValues(lo) == [448])
+    }
+
+    @Test("GPU residual: a non-zero deadzone threshold is added to the magnitude, as in the reference pseudo-code")
+    func residualThresholdAdded() throws {
+        // DoViBaker: dq = (2|r| - 1) * S + 2 * T, all >> (shift + 1). With S = 2048 (one code per EL code), shift 11 and
+        // T = 50 codes: |r| = 100 -> (99.5 + 50) = 149.5 -> 149; |r| = 30 -> 29.5 + 50 = 79.5 -> 79; negative mirrors.
+        let composer = try #require(DoviFelComposer())
+        let p = Self.params(nlqY: Self.nlq(threshold: 50 * 2048))
+        let big = try Self.composeConstant(composer, bl: (512, 512, 512), el: (612, 512, 512), params: p)
+        let small = try Self.composeConstant(composer, bl: (512, 512, 512), el: (542, 512, 512), params: p)
+        let neg = try Self.composeConstant(composer, bl: (512, 512, 512), el: (412, 512, 512), params: p)
+        #expect(Self.lumaValues(big) == [(2048 + 149) / 4])     // 549.25 -> 549
+        #expect(Self.lumaValues(small) == [532])                // (2048 + 79) / 4 = 531.75, rounded
+        #expect(Self.lumaValues(neg) == [475])                  // (2048 - 149) / 4 = 474.75, rounded
+    }
+
+    @Test("GPU residual: zero scale, method none and disable_residual each yield the bare base layer")
+    func residualOff() throws {
+        let composer = try #require(DoviFelComposer())
+        let cases: [(String, DoviMetalParams)] = [
+            ("zero scale", Self.params(nlqY: Self.nlq(scale: 0))),
+            ("method none", Self.params(nlqY: Self.nlq(method: .none))),
+            ("disable flag", Self.params(flags: [.disableResidual])),
+            ("disabled helper", Self.params(nlqY: .disabled)),
+        ]
+        for (name, p) in cases {
+            let out = try Self.composeConstant(composer, bl: (512, 512, 512), el: (900, 100, 900), params: p)
+            #expect(Self.lumaValues(out) == [512], "\(name)")
+        }
+    }
+
+    @Test("GPU residual: Cb and Cr are inverted independently and with their own parameters")
+    func chromaResidualIndependent() throws {
+        let composer = try #require(DoviFelComposer())
+        // Cr gets half the slope of Cb, so the same +100 EL swing gives +100 and +50.
+        let p = Self.params(nlqCb: Self.nlq(scale: 2048), nlqCr: Self.nlq(scale: 1024))
+        let out = try Self.composeConstant(composer, bl: (512, 400, 600), el: (512, 612, 612), params: p)
+        let uv = Self.allSamples(out, plane: 1, components: 2)
+        // Cb: (1600 + 99) / 4 = 424.75 -> 425 ; Cr: (2400 + 49) / 4 = 612.25 -> 612
+        #expect(Set(uv.map { $0[0] }) == [425])
+        #expect(Set(uv.map { $0[1] }) == [612])
+    }
+
+    @Test("GPU residual: only Cb active leaves Cr at its base value")
+    func chromaOneComponentActive() throws {
+        let composer = try #require(DoviFelComposer())
+        let p = Self.params(nlqCr: Self.nlq(scale: 0))
+        let out = try Self.composeConstant(composer, bl: (512, 400, 600), el: (512, 612, 612), params: p)
+        let uv = Self.allSamples(out, plane: 1, components: 2)
+        #expect(Set(uv.map { $0[0] }) == [425])
+        #expect(Set(uv.map { $0[1] }) == [600])
+    }
+
+    // MARK: - Output range
+
+    @Test("GPU clamps to video range: luma 64...940, chroma 64...960")
+    func outputClamps() throws {
+        let composer = try #require(DoviFelComposer())
+        let p = Self.params(flags: [.disableResidual])
+        let low = try Self.composeConstant(composer, bl: (0, 0, 0), el: (512, 512, 512), params: p)
+        let high = try Self.composeConstant(composer, bl: (1023, 1023, 1023), el: (512, 512, 512), params: p)
+        #expect(Self.lumaValues(low) == [64])
+        #expect(Set(Self.allSamples(low, plane: 1, components: 2).flatMap { $0 }) == [64])
+        #expect(Self.lumaValues(high) == [940])
+        #expect(Set(Self.allSamples(high, plane: 1, components: 2).flatMap { $0 }) == [960])
+    }
+
+    @Test("GPU residual pushing past the VDR range saturates instead of wrapping")
+    func residualSaturates() throws {
+        let composer = try #require(DoviFelComposer())
+        let p = Self.params()
+        // BL 1023 + 511 residual -> 4092 + 511 > 4095 -> clamp -> out 1024 -> luma cap 940.
+        let hi = try Self.composeConstant(composer, bl: (1023, 512, 512), el: (1023, 512, 512), params: p)
+        // BL 0 - 512 residual -> negative -> clamp 0 -> luma floor 64.
+        let lo = try Self.composeConstant(composer, bl: (0, 512, 512), el: (0, 512, 512), params: p)
+        #expect(Self.lumaValues(hi) == [940])
+        #expect(Self.lumaValues(lo) == [64])
+    }
+
+    // MARK: - Geometry
+
+    @Test("GPU writes every pixel for sizes that are not a multiple of the threadgroup or of 8",
+          arguments: [(4, 4), (6, 4), (34, 10), (130, 18), (514, 6), (1030, 10)])
+    func oddGeometryCoversEveryPixel(width: Int, height: Int) throws {
+        let composer = try #require(DoviFelComposer())
+        // Residual of +100 over the whole frame: an unwritten pixel would read 0,
+        // and a border pixel that mis-sampled the EL would miss 537.
+        let out = try Self.composeConstant(
+            composer, blWidth: width, blHeight: height,
+            bl: (512, 512, 512), el: (612, 612, 412), params: Self.params()
+        )
+        #expect(Self.lumaValues(out) == [537], "luma \(width)x\(height)")
+        let uv = Self.allSamples(out, plane: 1, components: 2)
+        #expect(uv.count == (width / 2) * (height / 2))
+        #expect(Set(uv.map { $0[0] }) == [537], "Cb \(width)x\(height)")
+        #expect(Set(uv.map { $0[1] }) == [487], "Cr \(width)x\(height)")
+    }
+
+    @Test("a frame whose enhancement chroma plane would be empty is refused, not composed from garbage",
+          arguments: [(2, 2), (6, 2)])
+    func tooSmallForChromaIsRefused(width: Int, height: Int) throws {
+        let composer = try #require(DoviFelComposer())
+        let blBuf = try #require(H.makeBuffer(width: width, height: height))
+        let elBuf = try #require(H.makeBuffer(width: width / 2, height: height / 2))
+        #expect(composer.compose(baseBuffer: blBuf, enhancementBuffer: elBuf, params: Self.params()) == nil)
+        // and the failed attempt must not have leaked a parameter slot
+        let ok = try Self.composeConstant(composer, bl: (512, 512, 512), el: (612, 512, 512), params: Self.params())
+        #expect(Self.lumaValues(ok) == [537])
+    }
+
+    @Test("GPU enhancement-layer upsampling preserves a constant field to the last row and column")
+    func upsamplingPartitionOfUnity() throws {
+        let composer = try #require(DoviFelComposer())
+        // EL is 1/4 the BL area. A weight set that does not sum to one, or one that
+        // reads past the edge, shows up as a border that differs from the interior.
+        for (w, h) in [(64, 16), (66, 18), (130, 34)] {
+            let out = try Self.composeConstant(
+                composer, blWidth: w, blHeight: h,
+                bl: (512, 512, 512), el: (700, 512, 512), params: Self.params()
+            )
+            // +188 is clamped to vdr_in_max 512 so is not clipped: (2048 + 188)/4 = 559.
+            #expect(Self.lumaValues(out) == [559], "\(w)x\(h)")
+        }
+    }
+
+    // MARK: - Curve shape
+
+    @Test("GPU zero-width piece is never selected; the later piece owns the shared pivot")
+    func zeroWidthPiece() throws {
+        let composer = try #require(DoviFelComposer())
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 4
+        poly.pivots[0] = 0; poly.pivots[1] = 500; poly.pivots[2] = 500; poly.pivots[3] = 1023
+        for piece in 0..<3 {
+            poly.method[piece] = DoviMapping.polynomial.rawValue
+            poly.order[piece] = 1
+            poly.coefShift[piece] = 23
+        }
+        poly.coef[0] = [0, 1 << 23, 0]          // identity
+        poly.coef[1] = [Int32(0.9 * 8388608.0), 0, 0]   // would output ~0.9 if ever chosen
+        poly.coef[2] = [0, 1 << 23, 0]          // identity
+        var p = Self.params(flags: [.disableResidual])
+        p.polyY = poly
+
+        let bl = try #require(H.makeBuffer(width: 1024, height: 4))
+        let el = try #require(H.makeBuffer(width: 512, height: 2))
+        H.fillPlane(bl, plane: 0, components: 1) { c, _, _ in min(c, 1023) }
+        H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 1, components: 2) { _, _, _ in 512 }
+        let out = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: p))
+        let row = H.readPlane(out, plane: 0, components: 1, row: 0).map { $0[0] }
+        for code in [100, 499, 500, 501, 900] {
+            #expect(row[code] == min(max(code, 64), 940), "code \(code)")
+        }
+    }
+
+    @Test("GPU luma MMR path reads the base-layer chroma, not just luma")
+    func lumaMmrUsesChroma() throws {
+        let composer = try #require(DoviFelComposer())
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 2
+        poly.pivots[0] = 0; poly.pivots[1] = 1023
+        poly.method[0] = DoviMapping.mmr.rawValue
+        poly.order[0] = 1
+        poly.coefShift[0] = 23
+        var mmr = DoviMmrParams()
+        mmr.coefShift = 23
+        // Terms are [y, u, v, yu, yv, uv, yuv]; select u only, so luma out = BL Cb.
+        mmr.coef[0][1] = 1 << 23
+
+        var p = Self.params(flags: [.disableResidual, .lumaMmr])
+        p.polyY = poly
+        p.mmrY = mmr
+        let out = try Self.composeConstant(composer, bl: (800, 300, 700), el: (512, 512, 512), params: p)
+        #expect(Self.lumaValues(out) == [300])
+    }
+
+    @Test("GPU luma MMR with a constant term and order 2 matches the hand-computed value")
+    func lumaMmrOrderTwo() throws {
+        let composer = try #require(DoviFelComposer())
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 2
+        poly.pivots[0] = 0; poly.pivots[1] = 1023
+        poly.method[0] = DoviMapping.mmr.rawValue
+        poly.order[0] = 2
+        poly.coefShift[0] = 23
+        var mmr = DoviMmrParams()
+        mmr.coefShift = 23
+        mmr.constant[0] = Int32(0.1 * 8388608.0)
+        mmr.coef[0][0] = Int32(0.5 * 8388608.0)    // order 1, y
+        mmr.coef[0][7] = Int32(0.2 * 8388608.0)    // order 2, y^2
+        var p = Self.params(flags: [.disableResidual, .lumaMmr])
+        p.polyY = poly
+        p.mmrY = mmr
+        // y = 600/1023: 0.1 + 0.5 y + 0.2 y^2
+        let y = 600.0 / 1023.0
+        let pred = 0.1 + 0.5 * y + 0.2 * y * y
+        let expected = Int(floor(Double(Int((pred * 1023.0 * 4.0).rounded(.toNearestOrEven))) / 4.0 + 0.5))
+        let out = try Self.composeConstant(composer, bl: (600, 512, 512), el: (512, 512, 512), params: p)
+        #expect(Self.lumaValues(out) == [expected])
+    }
+
+    // MARK: - Dither
+
+    @Test("GPU dither keeps the mean level and only moves values by one code")
+    func ditherStaysWithinOneCode() throws {
+        let composer = try #require(DoviFelComposer())
+        var p = Self.params()
+        p.ditherMode = .bayer8x8
+        // Residual +3 (reconstructed as +2) on a 512 base: exactly 512.5, so dither splits 512/513.
+        let blBuf = try #require(H.makeBuffer(width: 64, height: 64))
+        let elBuf = try #require(H.makeBuffer(width: 32, height: 32))
+        H.fillPlane(blBuf, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(blBuf, plane: 1, components: 2) { _, _, _ in 512 }
+        H.fillPlane(elBuf, plane: 0, components: 1) { _, _, _ in 515 }
+        H.fillPlane(elBuf, plane: 1, components: 2) { _, _, _ in 512 }
+        for frame: UInt32 in [0, 1] {
+            let out = try #require(composer.compose(baseBuffer: blBuf, enhancementBuffer: elBuf, params: p, frameIndex: frame))
+            let samples = Self.allSamples(out, plane: 0, components: 1).map { $0[0] }
+            #expect(samples.allSatisfy { $0 == 512 || $0 == 513 })
+            let mean = Double(samples.reduce(0, +)) / Double(samples.count)
+            #expect(abs(mean - 512.5) < 0.01, "frame \(frame) mean \(mean)")
+        }
+    }
+
+    // MARK: - Robustness of the composer itself
+
+    @Test("compose refuses degenerate buffers instead of crashing")
+    func degenerateBuffers() throws {
+        let composer = try #require(DoviFelComposer())
+        // A non-planar buffer cannot give the six textures the kernels need.
+        var bgra: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, 64, 16, kCVPixelFormatType_32BGRA,
+                            [kCVPixelBufferMetalCompatibilityKey: true] as CFDictionary, &bgra)
+        let good = try #require(H.makeBuffer(width: 64, height: 16))
+        let half = try #require(H.makeBuffer(width: 32, height: 8))
+        if let bgra {
+            #expect(composer.compose(baseBuffer: bgra, enhancementBuffer: half, params: Self.params()) == nil)
+            #expect(composer.compose(baseBuffer: good, enhancementBuffer: bgra, params: Self.params()) == nil)
+        }
+    }
+
+    @Test("repeated composes at a changing resolution recycle the pool without leaking slots")
+    func resolutionChangeMidStream() throws {
+        let composer = try #require(DoviFelComposer())
+        for (w, h) in [(64, 16), (128, 32), (64, 16), (256, 64), (64, 16)] {
+            for _ in 0..<8 {
+                let out = try Self.composeConstant(
+                    composer, blWidth: w, blHeight: h,
+                    bl: (512, 512, 512), el: (612, 512, 512), params: Self.params()
+                )
+                #expect(CVPixelBufferGetWidth(out) == w)
+                #expect(CVPixelBufferGetHeight(out) == h)
+            }
+        }
+        // All in-flight slots must have been returned: a leak would deadlock here.
+        composer.acquireSlot()
+        composer.releaseSlot()
+        #expect(composer.takePeakSlotsInUse() >= 1)
+    }
+}
+
+extension DoviGpuEdgeCaseTests {
+    private static func rawWord(_ b: CVPixelBuffer, plane: Int) -> Int {
+        CVPixelBufferLockBaseAddress(b, .readOnly); defer { CVPixelBufferUnlockBaseAddress(b, .readOnly) }
+        let stride = CVPixelBufferGetBytesPerRowOfPlane(b, plane) / 2
+        return Int(CVPixelBufferGetBaseAddressOfPlane(b, plane)!.assumingMemoryBound(to: UInt16.self)[3 * stride + 3])
+    }
+
+    @Test("full-precision output keeps the two VDR bits the 10-bit code drops")
+    func fullPrecisionKeepsLowBits() throws {
+        let composer = try #require(DoviFelComposer())
+        // BL 500 -> VDR 2000; +2 residual (reconstructed as +1) -> 2001 = 500.25 in 10-bit codes.
+        var p = Self.params(); p.ditherMode = .fullPrecision
+        let out = try Self.composeConstant(composer, bl: (500, 512, 512), el: (514, 512, 512), params: p)
+        #expect(Self.rawWord(out, plane: 0) == 2001 * 16)
+        #expect(Self.rawWord(out, plane: 0) >> 6 == 500, "the top 10 bits stay a valid P010 code")
+        var r = Self.params(); r.ditherMode = .none
+        let rounded = try Self.composeConstant(composer, bl: (500, 512, 512), el: (514, 512, 512), params: r)
+        #expect(Self.rawWord(rounded, plane: 0) == 500 << 6)
+    }
+}
+
+// MARK: - DoViBaker input and prediction clamps
+
+extension DoviGpuEdgeCaseTests {
+    /// A one-piece MMR curve over `[lo, hi]` whose only non-zero term is `term` of `[y, u, v, yu, yv, uv, yuv]`.
+    private static func mmrPassThrough(term: Int, lo: UInt32 = 0, hi: UInt32 = 1023) -> (DoviPolynomialParams, DoviMmrParams) {
+        var poly = DoviPolynomialParams()
+        poly.numPivots = 2
+        poly.pivots[0] = lo; poly.pivots[1] = hi
+        poly.method[0] = DoviMapping.mmr.rawValue
+        poly.order[0] = 1
+        poly.coefShift[0] = 23
+        var mmr = DoviMmrParams()
+        mmr.coefShift = 23
+        mmr.coef[0][term] = 1 << 23
+        return (poly, mmr)
+    }
+
+    private static func rawParams() -> DoviMetalParams {
+        var p = params(flags: [.disableResidual])
+        p.ditherMode = .debugRawVDR
+        return p
+    }
+
+    /// DoViBaker `mmrMapping` clamps s0 to pivot_value[0], s1 to pivot_value[1], s2 to pivot_value[2] (each
+    /// component's own range) before forming the cross terms. With a pass-through MMR the output is the
+    /// clamped input, in 12-bit VDR codes (x4).
+    @Test("MMR inputs are clamped to their own component's pivot range: Cb to poly_cb, Cr to poly_cr, luma to poly_y")
+    func mmrInputsClampedToOwnComponentRange() throws {
+        let composer = try #require(DoviFelComposer())
+
+        // Cb term (u) with poly_cb range [64, 940]: BL Cb 1000 -> 940, BL Cb 30 -> 64.
+        var p = Self.rawParams()
+        (p.polyCb, p.mmrCb) = Self.mmrPassThrough(term: 1, lo: 64, hi: 940)
+        var out = try Self.composeConstant(composer, bl: (512, 1000, 512), el: (512, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[1]) == [940 * 4])
+        out = try Self.composeConstant(composer, bl: (512, 30, 512), el: (512, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[1]) == [64 * 4])
+
+        // Cb output reading the v term: clamped by poly_cr's range [100, 900], not poly_cb's.
+        p = Self.rawParams()
+        (p.polyCb, p.mmrCb) = Self.mmrPassThrough(term: 2)
+        p.polyCr = {
+            var c = H.identityCurve(); c.pivots[0] = 100; c.pivots[1] = 900; return c
+        }()
+        out = try Self.composeConstant(composer, bl: (512, 512, 1000), el: (512, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[1]) == [900 * 4])
+        out = try Self.composeConstant(composer, bl: (512, 512, 20), el: (512, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[1]) == [100 * 4])
+
+        // Cr output reading the y term: clamped by poly_y's range [64, 940].
+        p = Self.rawParams()
+        (p.polyCr, p.mmrCr) = Self.mmrPassThrough(term: 0)
+        p.polyY = {
+            var c = H.identityCurve(); c.pivots[0] = 64; c.pivots[1] = 940; return c
+        }()
+        out = try Self.composeConstant(composer, bl: (1000, 512, 512), el: (512, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[2]) == [940 * 4])
+
+        // Luma MMR reading Cb: clamped by poly_cb's range.
+        p = Self.rawParams()
+        p.flags.insert(.lumaMmr)
+        (p.polyY, p.mmrY) = Self.mmrPassThrough(term: 1)
+        p.polyCb = {
+            var c = H.identityCurve(); c.pivots[0] = 200; c.pivots[1] = 800; return c
+        }()
+        out = try Self.composeConstant(composer, bl: (512, 1000, 512), el: (512, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [800 * 4])
+    }
+
+    /// DoViBaker floors the polynomial and the MMR result at 0 (`vv = (vv < 0) ? 0 : vv`) before the residual
+    /// is added, so a negative prediction is not pulled back up by it: 0 + 99, not -410 + 99 -> clamp 0.
+    @Test("a negative prediction is floored at 0 before the residual is added")
+    func negativePredictionFlooredBeforeResidual() throws {
+        let composer = try #require(DoviFelComposer())
+        var neg = DoviPolynomialParams()
+        neg.numPivots = 2; neg.pivots[0] = 0; neg.pivots[1] = 1023
+        neg.method[0] = DoviMapping.polynomial.rawValue
+        neg.order[0] = 0; neg.coefShift[0] = 23
+        neg.coef[0] = [Int32(-0.1 * 8388608.0), 0, 0]   // -0.1 * 4096 = -410 VDR codes
+
+        var p = Self.params()
+        p.ditherMode = .debugRawVDR
+        p.polyY = neg
+        let out = try Self.composeConstant(composer, bl: (512, 512, 512), el: (612, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [99])   // +100 EL codes -> +99 residual
+
+        // The same through MMR (chroma): constant -0.1, residual +99.
+        var m = DoviMmrParams(); m.coefShift = 23; m.constant[0] = Int32(-0.1 * 8388608.0)
+        var mp = DoviPolynomialParams()
+        mp.numPivots = 2; mp.pivots[1] = 1023
+        mp.method[0] = DoviMapping.mmr.rawValue; mp.order[0] = 1; mp.coefShift[0] = 23
+        p.polyCb = mp; p.mmrCb = m
+        let c = try Self.composeConstant(composer, bl: (512, 512, 512), el: (512, 612, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(c)[1]) == [99])
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
new file mode 100644
index 000000000..b60c8eeb0
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
@@ -0,0 +1,240 @@
+import Testing
+import Foundation
+import Metal
+@testable import AetherEngine
+
+/// Checks the parameter ABI on the GPU rather than by hand.
+///
+/// Metal has no `static_assert`, and `xcrun metal` is not installed on every
+/// machine that runs this suite, so the shader's view of `DoviMetalParams` cannot
+/// be asserted at compile time. Instead `dovi_layout_probe` reads the last field
+/// of each sub-block back out of the buffer the host actually uploaded: any offset
+/// drift between ``DoviMetalParams/serialize()`` and the shader's struct
+/// definitions moves a sentinel and fails a comparison below.
+struct DoviLayoutProbeTests {
+
+    /// Distinct value per probed field, so a shifted read lands on a value that
+    /// belongs to a different field rather than on a plausible one.
+    static func sentinelParams() -> DoviMetalParams {
+        var p = DoviMetalParams()
+
+        p.blWidth = 101
+        p.blHeight = 102
+        p.elWidth = 103
+        p.elHeight = 104
+        p.targetMode = 105
+        p.ditherMode = .bayer8x8
+        p.frameIndex = 107
+        p.flags = [.disableResidual, .lumaMmr]
+
+        p.polyY.numPivots = 9
+        p.polyY.pivots[8] = 1023
+        p.polyY.method[7] = DoviMapping.mmr.rawValue
+        p.polyY.order[7] = 2
+        p.polyY.coef[7][2] = -12345        // negative, to prove the sign survives
+        p.polyY.coefShift[7] = 23
+        p.mmrY.constant[7] = 777
+        p.mmrY.coef[7][20] = 888
+        p.mmrY.coefShift = 23
+
+        p.polyCb.numPivots = 5
+        p.polyCb.coefShift[7] = 17
+        p.mmrCb.coef[7][20] = 1234
+        p.mmrCb.coefShift = 19
+
+        p.polyCr.numPivots = 3
+        p.polyCr.coefShift[7] = 13
+        p.mmrCr.coef[7][20] = -4321
+        p.mmrCr.coefShift = 11
+
+        Self.applyComponentSentinels(&p)
+
+        p.minPq = 1
+        p.maxPq = 2
+        p.avgPq = 3
+        p.blMax = 1023
+        p.vdrMax = 4095
+        p.vdrScale = 4
+
+        return p
+    }
+
+
+    // MARK: - Per-component sentinels
+
+    /// Fields probed per component, in slot order from `firstComponentSlot`; mirrors the shader's probe kernel.
+    static let componentFieldNames = [
+        "poly.pivots[0]", "poly.pivots[1]", "poly.method[0]", "poly.order[0]",
+        "poly.coef[0][0]", "poly.coef[0][1]", "poly.coef[1][0]", "poly.coef_shift[0]",
+        "mmr.constant[0]", "mmr.coef[0][0]", "mmr.coef[0][1]", "mmr.coef[1][0]",
+        "nlq.method", "nlq.offset", "nlq.scale", "nlq.threshold", "nlq.shift", "nlq.vdr_in_max",
+        "nlq.pivots[0]", "nlq.pivots[1]",
+    ]
+    static let firstComponentSlot = 36
+
+    /// Distinct non-zero sentinel for component `c`, field `k`; fields that are signed alternate sign so a
+    /// sign-lost read is caught too. `nlq.method` is an enum with two legal values, so it uses those.
+    static func sentinel(_ c: Int, _ k: Int) -> UInt32 {
+        let magnitude = UInt32(1000 * (c + 1) + 10 * k + 1)
+        let signed = [4, 5, 8, 10, 15]   // coef[0][0], coef[0][1], mmr.constant[0], mmr.coef[0][1], nlq.threshold
+        if signed.contains(k) { return UInt32(bitPattern: -Int32(magnitude)) }
+        if k == 12 { return [DoviNlqMethod.none, .linear, .none][c].rawValue }
+        return magnitude
+    }
+
+    static func slot(_ c: Int, _ k: Int) -> Int { firstComponentSlot + c * componentFieldNames.count + k }
+
+    /// Writes the per-component sentinels over `p`.
+    static func applyComponentSentinels(_ p: inout DoviMetalParams) {
+        let polys: [WritableKeyPath<DoviMetalParams, DoviPolynomialParams>] = [\.polyY, \.polyCb, \.polyCr]
+        let mmrs: [WritableKeyPath<DoviMetalParams, DoviMmrParams>] = [\.mmrY, \.mmrCb, \.mmrCr]
+        let nlqs: [WritableKeyPath<DoviMetalParams, DoviNlqParams>] = [\.nlqY, \.nlqCb, \.nlqCr]
+        for c in 0..<3 {
+            func u(_ k: Int) -> UInt32 { sentinel(c, k) }
+            func i(_ k: Int) -> Int32 { Int32(bitPattern: sentinel(c, k)) }
+            p[keyPath: polys[c]].pivots[0] = u(0)
+            p[keyPath: polys[c]].pivots[1] = u(1)
+            p[keyPath: polys[c]].method[0] = u(2)
+            p[keyPath: polys[c]].order[0] = u(3)
+            p[keyPath: polys[c]].coef[0][0] = i(4)
+            p[keyPath: polys[c]].coef[0][1] = i(5)
+            p[keyPath: polys[c]].coef[1][0] = i(6)
+            p[keyPath: polys[c]].coefShift[0] = u(7)
+            p[keyPath: mmrs[c]].constant[0] = i(8)
+            p[keyPath: mmrs[c]].coef[0][0] = i(9)
+            p[keyPath: mmrs[c]].coef[0][1] = i(10)
+            p[keyPath: mmrs[c]].coef[1][0] = i(11)
+            p[keyPath: nlqs[c]].nlqMethod = DoviNlqMethod(rawValue: u(12))!
+            p[keyPath: nlqs[c]].nlqOffset = i(13)
+            p[keyPath: nlqs[c]].nlqScale = i(14)
+            p[keyPath: nlqs[c]].nlqThreshold = i(15)
+            p[keyPath: nlqs[c]].nlqShift = u(16)
+            p[keyPath: nlqs[c]].vdrInMax = i(17)
+            p[keyPath: nlqs[c]].nlqPivots = [u(18), u(19)]
+        }
+    }
+
+    @Test("The shader reads every parameter sub-block at the offset the Swift serializer wrote it to")
+    func layoutProbeRoundTrip() throws {
+        let composer = try #require(DoviFelComposer())
+        let params = Self.sentinelParams()
+        let slots = try #require(composer.probeLayout(params: params),
+                                 "dovi_layout_probe is unavailable, so the parameter ABI is unverified")
+        #expect(slots.count == DoviFelComposer.layoutProbeSlots)
+
+        /// Compares one slot, naming the field so a failure says which offset moved.
+        func expect(_ slot: Int, _ value: UInt32, _ field: String) {
+            #expect(slots[slot] == value,
+                    "slot \(slot) (\(field)) read \(slots[slot]), expected \(value)")
+        }
+        func expect(_ slot: Int, signed value: Int32, _ field: String) {
+            expect(slot, UInt32(bitPattern: value), field)
+        }
+
+        // sizeof on the GPU side, against the size the serializer produced.
+        expect(0, UInt32(DoviMetalParams.serializedSize), "sizeof(DoviMetalParams)")
+        #expect(params.serialize().count == DoviMetalParams.serializedSize)
+
+        expect(1, 101, "bl_width")
+        expect(2, 102, "bl_height")
+        expect(3, 103, "el_width")
+        expect(4, 104, "el_height")
+        expect(5, 105, "target_mode")
+        expect(6, DoviDither.bayer8x8.rawValue, "dither_mode")
+        expect(7, 107, "frame_index")
+        expect(8, DoviComposerFlags([.disableResidual, .lumaMmr]).rawValue, "flags")
+
+        expect(9, 9, "poly_y.num_pivots")
+        expect(10, 1023, "poly_y.pivots[8]")
+        expect(11, DoviMapping.mmr.rawValue, "poly_y.method[7]")
+        expect(12, 2, "poly_y.order[7]")
+        expect(13, signed: -12345, "poly_y.coef[7][2]")
+        expect(14, 23, "poly_y.coef_shift[7]")
+        expect(15, 777, "mmr_y.mmr_constant[7]")
+        expect(16, 888, "mmr_y.coef[7][20]")
+        expect(17, 23, "mmr_y.coef_shift")
+        expect(18, Self.sentinel(0, 17), "nlq_y.vdr_in_max")
+        expect(19, Self.sentinel(0, 19), "nlq_y.nlq_pivots[1]")
+
+        expect(20, 5, "poly_cb.num_pivots")
+        expect(21, 17, "poly_cb.coef_shift[7]")
+        expect(22, 1234, "mmr_cb.coef[7][20]")
+        expect(23, 19, "mmr_cb.coef_shift")
+        expect(24, Self.sentinel(1, 19), "nlq_cb.nlq_pivots[1]")
+
+        expect(25, 3, "poly_cr.num_pivots")
+        expect(26, 13, "poly_cr.coef_shift[7]")
+        expect(27, signed: -4321, "mmr_cr.coef[7][20]")
+        expect(28, 11, "mmr_cr.coef_shift")
+        expect(29, Self.sentinel(2, 19), "nlq_cr.nlq_pivots[1]")
+
+        expect(30, 1, "min_pq")
+        expect(31, 2, "max_pq")
+        expect(32, 3, "avg_pq")
+        expect(33, 1023, "bl_max")
+        expect(34, 4095, "vdr_max")
+        expect(35, 4, "vdr_scale")
+
+        // First element of every array and every NLQ scalar, per component, each with its own sentinel.
+        let names = ["y", "cb", "cr"]
+        for c in 0..<3 {
+            for (k, field) in Self.componentFieldNames.enumerated() {
+                expect(Self.slot(c, k), Self.sentinel(c, k), "\(names[c]).\(field)")
+            }
+        }
+    }
+
+    @Test("Bit depths derive the normalisation constants, and reject pairs the kernels cannot express")
+    func bitDepthDerivation() {
+        var p = DoviMetalParams()
+
+        let profile7 = p.setBitDepths(bl: 10, vdr: 12)
+        #expect(profile7)
+        #expect(p.blMax == 1023)
+        #expect(p.vdrMax == 4095)
+        #expect(p.vdrScale == 4)
+
+        let eightBit = p.setBitDepths(bl: 8, vdr: 8)
+        #expect(eightBit)
+        #expect(p.blMax == 255)
+        #expect(p.vdrMax == 255)
+        #expect(p.vdrScale == 1, "equal depths must not scale the residual")
+
+        // A VDR depth below the base-layer depth has no meaning in the
+        // reconstruction, and would make vdr_scale a fraction.
+        let vdrBelowBl = p.setBitDepths(bl: 12, vdr: 10)
+        let vdrTooDeep = p.setBitDepths(bl: 10, vdr: 20)
+        let blTooShallow = p.setBitDepths(bl: 4, vdr: 12)
+        #expect(!vdrBelowBl)
+        #expect(!vdrTooDeep)
+        #expect(!blTooShallow)
+        #expect(p.blMax == 255, "a rejected pair must leave the previous values alone")
+    }
+
+    @Test("A zeroed NLQ block is neutral, matching what a memset gives the C side")
+    func zeroedNlqIsNeutral() {
+        let zeroed = DoviNlqParams()
+        // nlq_method 0 is LINEAR, so neutrality has to come from the zero slope:
+        // the kernel returns no residual when nlq_scale is zero. That is what lets
+        // a memset-zeroed C struct and a default-initialised Swift value agree.
+        #expect(zeroed.nlqMethod == .linear)
+        #expect(zeroed.nlqScale == 0)
+
+        let disabled = DoviNlqParams.disabled
+        #expect(disabled.nlqMethod == .none)
+        #expect(disabled.nlqScale == 0)
+    }
+
+    @Test("serialize(into:) writes byte-for-byte identical output to serialize() -> Data")
+    func serializeIntoRawBufferMatchesSerializeData() {
+        let params = Self.sentinelParams()
+        let expectedData = params.serialize()
+
+        var rawBytes = [UInt8](repeating: 0, count: DoviMetalParams.serializedSize)
+        rawBytes.withUnsafeMutableBytes { raw in
+            params.serialize(into: raw)
+        }
+
+        #expect(Data(rawBytes) == expectedData)
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviRpuConverterTests.swift b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
index 7e33a1789..da8ab3d33 100644
--- a/Tests/AetherEngineTests/DoviRpuConverterTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
@@ -7,6 +7,7 @@ import Dovi
 /// Successful real-RPU conversion and the FEL/MEL string value are validated against
 /// dovi_tool ground truth via `aetherctl dovitest` and on device; these guard the
 /// pure byte-walk branches (degrade-on-failure, EL drop, no-op) from regressing.
+@Suite(.serialized)
 struct DoviRpuConverterTests {
 
     /// 2-byte HEVC NAL header (type in bits 1..6 of byte 0, layer 0, temporal_id_plus1 = 1) + payload.
@@ -165,6 +166,15 @@ struct DoviRpuConverterTests {
         #expect(DoviRpuConverter.enhancementLayerType(pkt) == nil)
     }
 
+    @Test("enhancementLayerType does not hand libdovi an RPU the guard rejects (it would abort the process)")
+    func elTypeSkipsAnRPUThatWouldAbortLibdovi() {
+        // CRC-valid, but a linear-interpolation polynomial piece, which libdovi panics on.
+        let rpu = DoviRpuGuardTests.craft(linearOnComponent: 0)
+        let pkt = avccPacket([hevcNAL(type: 1, payload: [0xAA]), rpu])
+        defer { free(pkt) }
+        #expect(DoviRpuConverter.enhancementLayerType(pkt) == nil)
+    }
+
     // MARK: - #365: framing is given, not assumed
 
     /// Pack NALs Annex B, the framing a Matroska remux with Annex-B CodecPrivate delivers.
@@ -436,4 +446,188 @@ struct DoviRpuConverterTests {
         #expect(DoviRpuConverter.convertPacketToProfile81(pkt) == true)
         #expect(packetBytes(pkt) == input)
     }
+
+    // MARK: - Single parse per RPU
+
+    /// Each RPU must be parsed exactly once. Before the fix, `separateDualLayers`
+    /// parsed via `DoviFelComposer.parseRpuParameters` (internally calling
+    /// `dovi_parse_unspec62_nalu`) and then again via a direct call, and
+    /// `DualLayerVideoDecoder` added a third. After the fix: one parse per RPU.
+    @Test("separateDualLayers parses each RPU exactly once")
+    func singleParsePerRPUPerformance() {
+        // Build a P7 packet from the real RPU fixture: BL + RPU + EL.
+        // clipARpuHex already includes the 2-byte HEVC NAL header (0x7C, 0x01 = type 62).
+        let bl = hevcNAL(type: 1, payload: [0xAA, 0xBB])
+        let rpu = hexToBytes(DoviFelMathTests.clipARpuHex)
+        let el = hevcNAL(type: 63, payload: [0xCC])
+        let pkt = avccPacket([bl, rpu, el])
+        defer { free(pkt) }
+
+        // Baseline: no prior parses.
+        DoviFelComposer.resetParseRpuCountForTesting()
+        #expect(DoviFelComposer.parseRpuCountForTesting == 0)
+
+        let result = DoviRpuConverter.separateDualLayers(pkt)
+
+        // Exactly one parse happened (via parseRpuParameters).
+        #expect(DoviFelComposer.parseRpuCountForTesting == 1,
+                "expected exactly 1 parse per RPU, got \(DoviFelComposer.parseRpuCountForTesting)")
+        #expect(result.rpuParams != nil)
+        #expect(result.convertedRpu != nil)
+        #expect(result.isFEL == true)
+        #expect(result.isMEL == false)
+        #expect(result.success == true)
+    }
+
+    // MARK: - Several RPUs in one packet
+
+    /// The raw bytes, the parameters and the converted RPU of a result must all come from one RPU.
+    /// Clip A and clip C differ in pivots and in size, so each output names its source.
+    @Test("with two valid RPUs in a packet, raw bytes, parameters and converted RPU all come from the last one")
+    func twoValidRpusComeFromOneRpu() throws {
+        let first = hexToBytes(DoviFelMathTests.clipARpuHex)
+        let second = hexToBytes(DoviFelMathTests.clipCRpuHex)
+        let pkt = avccPacket([hevcNAL(type: 1, payload: [0xAA]), first, second, hevcNAL(type: 63, payload: [0xCC])])
+        defer { free(pkt) }
+        let result = DoviRpuConverter.separateDualLayers(pkt)
+
+        #expect(result.success)
+        #expect(result.rpuData == second)
+        // Parameters of the second RPU: its luma curve is not the first's 9-pivot one.
+        let expected = try #require(Self.parameters(of: second))
+        let got = try #require(result.rpuParams)
+        #expect(got.polyY.numPivots == expected.polyY.numPivots)
+        #expect(got.polyY.pivots == expected.polyY.pivots)
+        #expect(got.polyCb.coef == expected.polyCb.coef)
+        #expect(got.mmrCb.coef == expected.mmrCb.coef)
+        let other = try #require(Self.parameters(of: first))
+        #expect(got.polyY.pivots != other.polyY.pivots || got.mmrCb.coef != other.mmrCb.coef, "fixture RPUs must differ")
+        #expect(result.convertedRpu == Self.converted(second))
+    }
+
+    @Test("a second RPU that fails the guard leaves the first RPU's bytes, parameters and conversion intact")
+    func failingSecondRpuKeepsFirstConsistent() throws {
+        let first = hexToBytes(DoviFelMathTests.clipARpuHex)
+        var bad = hexToBytes(DoviFelMathTests.clipCRpuHex)
+        bad[bad.count - 6] ^= 0xFF   // inside the CRC-covered payload: the guard refuses it
+        let pkt = avccPacket([hevcNAL(type: 1, payload: [0xAA]), first, bad, hevcNAL(type: 63, payload: [0xCC])])
+        defer { free(pkt) }
+        let result = DoviRpuConverter.separateDualLayers(pkt)
+
+        #expect(!result.success, "the dropped RPU is still reported")
+        #expect(result.rpuData == first)
+        let expected = try #require(Self.parameters(of: first))
+        let got = try #require(result.rpuParams)
+        #expect(got.polyY.pivots == expected.polyY.pivots)
+        #expect(got.mmrCb.coef == expected.mmrCb.coef)
+        #expect(result.convertedRpu == Self.converted(first))
+        #expect(result.isFEL)
+    }
+
+    private static func parameters(of nal: [UInt8]) -> DoviMetalParams? {
+        guard let rpu = dovi_parse_unspec62_nalu(nal, nal.count) else { return nil }
+        defer { dovi_rpu_free(rpu) }
+        return DoviFelComposer.parseRpuParameters(rpu: rpu)
+    }
+
+    private static func converted(_ nal: [UInt8]) -> [UInt8]? {
+        guard let rpu = dovi_parse_unspec62_nalu(nal, nal.count) else { return nil }
+        defer { dovi_rpu_free(rpu) }
+        guard let out = DoviRpuConverter.convertedUnspec62(rpu) else { return nil }
+        defer { dovi_data_free(out) }
+        return [UInt8](UnsafeBufferPointer(start: out.pointee.data, count: out.pointee.len))
+    }
+
+    @Test("separateDualLayers skips parameter extraction when extractParams is false")
+    func separateDualLayersSkipsParameterExtractionWhenRequested() {
+        let bl = hevcNAL(type: 1, payload: [0xAA, 0xBB])
+        let rpu = hexToBytes(DoviFelMathTests.clipARpuHex)
+        let el = hevcNAL(type: 63, payload: [0xCC])
+        let pkt = avccPacket([bl, rpu, el])
+        defer { free(pkt) }
+
+        DoviFelComposer.resetParseRpuCountForTesting()
+        #expect(DoviFelComposer.parseRpuCountForTesting == 0)
+
+        let result = DoviRpuConverter.separateDualLayers(pkt, extractParams: false)
+
+        #expect(DoviFelComposer.parseRpuCountForTesting == 0,
+                "expected 0 parses when extractParams is false, got \(DoviFelComposer.parseRpuCountForTesting)")
+        #expect(result.rpuParams == nil)
+        #expect(result.convertedRpu != nil)
+        #expect(result.isFEL == true)
+        #expect(result.isMEL == false)
+        #expect(result.success == true)
+    }
+
+    @Test("convertPacketToProfile81 skips parameter extraction")
+    func convertPacketToProfile81SkipsParameterExtraction() {
+        let bl = hevcNAL(type: 1, payload: [0xAA, 0xBB])
+        let rpu = hexToBytes(DoviFelMathTests.clipARpuHex)
+        let el = hevcNAL(type: 63, payload: [0xCC])
+        let pkt = avccPacket([bl, rpu, el])
+        defer { free(pkt) }
+
+        DoviFelComposer.resetParseRpuCountForTesting()
+        #expect(DoviFelComposer.parseRpuCountForTesting == 0)
+
+        let success = DoviRpuConverter.convertPacketToProfile81(pkt)
+
+        #expect(DoviFelComposer.parseRpuCountForTesting == 0,
+                "expected 0 parses in convertPacketToProfile81, got \(DoviFelComposer.parseRpuCountForTesting)")
+        #expect(success == true)
+    }
+
+    // MARK: - Untouched Base Layer with CustomBlockSource
+
+    @Test("separateDualLayers with useCustomBlockSource leaves packet untouched while extracting EL and RPU")
+    func separateDualLayersWithCustomBlockSourceLeavesPacketUntouched() {
+        let bl = hevcNAL(type: 1, payload: [0xAA, 0xBB, 0xCC, 0xDD])
+        let rpu = hexToBytes(DoviFelMathTests.clipARpuHex)
+        let el = hevcNAL(type: 63, payload: [0xEE, 0xFF])
+        let pkt = avccPacket([bl, rpu, el])
+        defer { free(pkt) }
+
+        let originalData = pkt.pointee.data
+        let originalSize = pkt.pointee.size
+        let originalBuf = pkt.pointee.buf
+
+        let result = DoviRpuConverter.separateDualLayers(
+            pkt,
+            extractEL: true,
+            useCustomBlockSource: true,
+            extractParams: true
+        )
+        defer {
+            var elOpt: UnsafeMutablePointer<AVPacket>? = result.elPacket
+            trackedPacketFree(&elOpt)
+        }
+
+        // Base-layer packet pointer, size, and AVBufferRef must be COMPLETELY UNTOUCHED
+        #expect(pkt.pointee.data == originalData)
+        #expect(pkt.pointee.size == originalSize)
+        #expect(pkt.pointee.buf == originalBuf)
+
+        // EL packet, RPU params, and converted RPU must still be correctly extracted
+        #expect(result.elPacket != nil)
+        #expect(result.rpuParams != nil)
+        #expect(result.convertedRpu != nil)
+        #expect(result.isFEL == true)
+        #expect(result.isMEL == false)
+        #expect(result.success == true)
+    }
+
+    /// Hex-string decoder for RPU fixtures.
+    private func hexToBytes(_ hex: String) -> [UInt8] {
+        var bytes: [UInt8] = []
+        var i = hex.startIndex
+        while i < hex.endIndex {
+            let next = hex.index(i, offsetBy: 2)
+            if let byte = UInt8(hex[i..<next], radix: 16) {
+                bytes.append(byte)
+            }
+            i = next
+        }
+        return bytes
+    }
 }
diff --git a/Tests/AetherEngineTests/DoviRpuGuardTests.swift b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
index 2f5616a7d..0610b4bbf 100644
--- a/Tests/AetherEngineTests/DoviRpuGuardTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
@@ -528,4 +528,11 @@ struct DoviRpuGuardTests {
         #expect(elType == (residual == .fel ? "FEL" : "MEL"))
         #expect(Self.convertedBytes(nal) != nil)
     }
+
+    @Test("real RPUs from the FEL fixtures are never flagged",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips))
+    func realRpusPass() throws {
+        let seed = try #require(try DoviFelFuzzTests.seed())
+        #expect(Self.verdict(seed.rpu) == (true, false))
+    }
 }
diff --git a/Tests/AetherEngineTests/DoviShaderSyncTests.swift b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
new file mode 100644
index 000000000..2d61883b4
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
@@ -0,0 +1,81 @@
+import Testing
+import Foundation
+import Metal
+@testable import AetherEngine
+
+/// Guards the Dolby Vision shader source integrity and parameter serialization.
+struct DoviShaderSyncTests {
+
+    static let metalAvailable = MTLCreateSystemDefaultDevice() != nil
+
+    @Test("The runtime-compiled source carries all expected kernels")
+    func runtimeSourceCarriesKernels() {
+        for kernel in ["dovi_compose_luma", "dovi_compose_chroma", "dovi_layout_probe"] {
+            #expect(DoviShaderSource.source.contains("kernel void \(kernel)("),
+                    "runtime source is missing \(kernel)")
+        }
+    }
+
+    @Test("Serializing produces exactly the byte count the C struct occupies")
+    func serializedSizeIsStable() {
+        var params = DoviMetalParams()
+        params.polyY.numPivots = 9
+        params.mmrCb.coefShift = 23
+        #expect(params.serialize().count == DoviMetalParams.serializedSize)
+        #expect(DoviMetalParams.serializedSize == 2972,
+                "The parameter ABI changed; update tests and probe asserts")
+    }
+
+    @Test("two composers share one pipeline state instance (compiled once lazily)", .enabled(if: DoviShaderSyncTests.metalAvailable, "needs a Metal device"))
+    func twoComposersSharePipelineStateInstance() throws {
+        let c1 = try #require(DoviFelComposer())
+        let c2 = try #require(DoviFelComposer())
+
+        // Before accessing pipelines or composing, both composers exist without separate compiles.
+        // Accessing pipelines returns identical instances (shared across composers).
+        let luma1 = try #require(c1.lumaPipelineForTesting)
+        let luma2 = try #require(c2.lumaPipelineForTesting)
+        let chroma1 = try #require(c1.chromaPipelineForTesting)
+        let chroma2 = try #require(c2.chromaPipelineForTesting)
+
+        #expect(luma1 === luma2, "Composers must share the exact same luma pipeline state instance")
+        #expect(chroma1 === chroma2, "Composers must share the exact same chroma pipeline state instance")
+    }
+
+    private final class CompileCounter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value = 0
+        func bump() { lock.lock(); value += 1; lock.unlock() }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return value }
+    }
+
+    @Test("a shader that fails to compile is compiled once; every later call fails fast", .enabled(if: DoviShaderSyncTests.metalAvailable, "needs a Metal device"))
+    func compileFailureIsCached() throws {
+        let device = try #require(MTLCreateSystemDefaultDevice())
+        let cache = DoviFelComposer.SharedPipelines.Cache()
+        let compiles = CompileCounter()
+        for _ in 0..<5 {
+            #expect(throws: DoviFelComposer.ComposerError.self) {
+                try cache.resolve(device: device) {
+                    compiles.bump()
+                    throw DoviFelComposer.ComposerError.missingKernelFunction
+                }
+            }
+        }
+        #expect(compiles.count == 1)
+    }
+
+    @Test("concurrent first uses of the pipelines compile once", .enabled(if: DoviShaderSyncTests.metalAvailable, "needs a Metal device"))
+    func concurrentResolveCompilesOnce() throws {
+        let device = try #require(MTLCreateSystemDefaultDevice())
+        let cache = DoviFelComposer.SharedPipelines.Cache()
+        let compiles = CompileCounter()
+        DispatchQueue.concurrentPerform(iterations: 16) { _ in
+            _ = try? cache.resolve(device: device) {
+                compiles.bump()
+                return try DoviFelComposer.SharedPipelines.compile(device: device, source: DoviShaderSource.source)
+            }
+        }
+        #expect(compiles.count == 1)
+    }
+}
diff --git a/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift b/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
index e7257b402..6bfd1ee56 100644
--- a/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
+++ b/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
@@ -180,6 +180,11 @@ struct SampleBufferRendererLookaheadTests {
         #expect(abs(r.lead - 4 * frame) < 1e-9)
     }
 
+    @Test("The pool threshold follows the look-ahead cap")
+    func poolFollowsCap() {
+        #expect(DoviFelComposer.outputPoolAllocationThreshold == SampleBufferRenderer.felVideoLookaheadFrames + 2 + DoviFelComposer.maxFramesInFlight + 1)
+    }
+
     private func mayEnqueue(rate: Double?, pts: Double, clock: Double,
                             ready: Bool = true, armed: Bool = true) -> Bool {
         SampleBufferRenderer.mayEnqueueAnotherFrame(
diff --git a/Tests/AetherEngineTests/Support/DoviTestSupport.swift b/Tests/AetherEngineTests/Support/DoviTestSupport.swift
new file mode 100644
index 000000000..a854947b1
--- /dev/null
+++ b/Tests/AetherEngineTests/Support/DoviTestSupport.swift
@@ -0,0 +1,31 @@
+import Foundation
+import CoreVideo
+
+/// Helpers shared by the Dolby Vision composer tests.
+enum DoviTestSupport {
+
+    /// `media/` next to the package checkout, where local test titles live (git-ignored; tests that
+    /// need one skip when it is absent).
+    static var mediaDir: URL {
+        URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent().deletingLastPathComponent()
+            .deletingLastPathComponent().deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("media")
+    }
+
+    /// Raw planes from a `.debugRawVDR` compose: 12-bit VDR codes, Cb and Cr de-interleaved.
+    static func rawVDR(_ b: CVPixelBuffer, chromaOnly: Bool = false) -> [[Int]] {
+        CVPixelBufferLockBaseAddress(b, .readOnly); defer { CVPixelBufferUnlockBaseAddress(b, .readOnly) }
+        var out = [[Int]]()
+        let w = CVPixelBufferGetWidthOfPlane(b, 0), h = CVPixelBufferGetHeightOfPlane(b, 0)
+        let ys = CVPixelBufferGetBytesPerRowOfPlane(b, 0) / 2
+        let yb = CVPixelBufferGetBaseAddressOfPlane(b, 0)!.assumingMemoryBound(to: UInt16.self)
+        out.append(chromaOnly ? [] : (0..<(w * h)).map { Int(yb[($0 / w) * ys + $0 % w] >> 4) })
+        let cw = CVPixelBufferGetWidthOfPlane(b, 1), ch = CVPixelBufferGetHeightOfPlane(b, 1)
+        let cs = CVPixelBufferGetBytesPerRowOfPlane(b, 1) / 2
+        let cb = CVPixelBufferGetBaseAddressOfPlane(b, 1)!.assumingMemoryBound(to: UInt16.self)
+        for c in 0..<2 { out.append((0..<(cw * ch)).map { Int(cb[($0 / cw) * cs + ($0 % cw) * 2 + c] >> 4) }) }
+        return out
+    }
+}
diff --git a/Tests/AetherEngineTests/UndocumentedDolbyVisionKeysTests.swift b/Tests/AetherEngineTests/UndocumentedDolbyVisionKeysTests.swift
new file mode 100644
index 000000000..b125c2455
--- /dev/null
+++ b/Tests/AetherEngineTests/UndocumentedDolbyVisionKeysTests.swift
@@ -0,0 +1,33 @@
+import XCTest
+@testable import AetherEngine
+
+/// The FEL route hands tvOS its per-frame Dolby Vision metadata under two attachment keys that are in
+/// no public header. If a tvOS release stops honouring them there must be exactly one place to change,
+/// so the literals may be spelled in `DoviDisplayMetadata.swift` and nowhere else in `Sources/`;
+/// everything else goes through `DoviDisplayMetadata.rpuDataKey` / `.compatibilityIDKey`.
+final class UndocumentedDolbyVisionKeysTests: XCTestCase {
+
+    func testTheUndocumentedKeysAreSpelledInOneFileOnly() throws {
+        let sources = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources")
+        let owner = "DoviDisplayMetadata.swift"
+        let literals = ["\"DolbyVisionRPUData\"", "\"DolbyCompatibilityID\""]
+        let files = try XCTUnwrap(FileManager.default.enumerator(at: sources, includingPropertiesForKeys: nil))
+        var offenders: [String] = []
+        var ownerSpellsBoth = false
+        for case let url as URL in files where url.pathExtension == "swift" {
+            let text = try String(contentsOf: url, encoding: .utf8)
+            let hits = literals.filter { text.contains($0) }
+            if url.lastPathComponent == owner {
+                ownerSpellsBoth = hits.count == literals.count
+            } else if !hits.isEmpty {
+                offenders.append("\(url.lastPathComponent): \(hits.joined(separator: ", "))")
+            }
+        }
+        XCTAssertTrue(ownerSpellsBoth, "\(owner) should define both keys")
+        XCTAssertEqual(offenders, [], "use DoviDisplayMetadata.rpuDataKey / .compatibilityIDKey instead")
+    }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index 51cadd49a..3746316d2 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -540,8 +540,13 @@ Sources/AetherEngine/
 │   ├── 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.swift               libdovi RPU surgery for both routes. Native path: per-packet Profile 7 → 8.1 rewrite (convert type-62 RPU, drop type-63 EL). SW FEL path: `separateDualLayers` also lifts the EL into its own packet and returns the composer's reshaping parameters plus the 8.1 RPU attached as display metadata
 │   ├── DoviRpuConverter+Probe.swift         Diagnostic DV-conversion probe (`doviConvertProbe` / `DoviConvertProbeResult`), backs `aetherctl dovitest`
+│   ├── DoviDisplayMetadata.swift            SW FEL path: sets `DolbyVisionRPUData` (the Profile 8.1 RPU minus its NAL header) and `DolbyCompatibilityID` (the CFString "1", never a number) on every emitted buffer, or clears both; tvOS consumes them in backboardd
+│   ├── Metal/
+│   │   ├── DoviFelComposer.swift            BL + EL + RPU composition: runtime-compiled pipelines, pooled P010 output, `composeAsync` bounded at `maxFramesInFlight` with completions on its own serial queue; RPU → `DoviMetalParams` parsing
+│   │   ├── DoviShaderSource.swift           Luma / chroma compose kernels (reshaping, inverse NLQ, bilinear EL upsampling, ordered dither) and the ABI layout probe, compiled at runtime
+│   │   └── DoviMetalParams.swift            Swift mirror of the kernel parameter structs and their byte-exact serializer
 │   ├── 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
 │   ├── Issue99MuxerFailureRevive.swift      Bounded revive for a VOD pump that died with `muxerFailed` (#99): the first cut firing before any bridged audio reached the muxer (dec3 box) no longer ends the session
 │   ├── SlowServeSignal.swift                One-shot slow-serve timer arming the server's early chunked header (keeps TTFB under AVPlayer's ~3.5 s -12889 window, #93 round 3)
@@ -588,7 +593,7 @@ The `aetherctl` CLI target (`Sources/aetherctl/`) is documented separately in [d
 | Package | License | Purpose |
 | --- | --- | --- |
 | [FFmpegBuild](https://github.com/superuser404notfound/FFmpegBuild) | LGPL-2.1-or-later | Slim FFmpeg 8.1 (avcodec / avformat / avutil / swresample / swscale / avfilter + zimg) for demux + HLS-fMP4 mux + AudioBridge FLAC encode + SW-path dav1d decode + sws_scale YUV → NV12 / P010. avfilter ships a trimmed filter set: zscale + tonemap + colorspace (HDR → SDR still extraction), bwdif + yadif + yadif_videotoolbox + hwupload (SW + GPU deinterlacing). Bundles libzvbi for the DVB teletext decoder (#107). Shipped as dynamically linked frameworks, no GPL components |
-| [LibDovi](https://github.com/superuser404notfound/LibDovi) | MIT / Apache-2.0 | libdovi (the `dolby_vision` crate's C API) for live Dolby Vision Profile 7 to single-layer 8.1 RPU conversion (`dovi_convert_rpu_with_mode`, mode 2), so the Apple TV engages real DV on dual-layer UHD-BD remuxes instead of plain HDR10. Prebuilt xcframework, no Rust at the consumer's build time |
+| [LibDovi](https://github.com/superuser404notfound/LibDovi) | MIT / Apache-2.0 | libdovi (the `dolby_vision` crate's C API) for live Dolby Vision Profile 7 to single-layer 8.1 RPU conversion (`dovi_convert_rpu_with_mode`, mode 2), so the Apple TV engages real DV on dual-layer UHD-BD remuxes instead of plain HDR10. The software FEL path uses the same library to read the reshaping and NLQ parameters for the Metal composer and to produce the per-frame 8.1 RPU it attaches as display metadata. Prebuilt xcframework, no Rust at the consumer's build time |
 | [SMBClient](https://github.com/kishikawakatsumi/SMBClient) | MIT | Pure-Swift SMB2 client over `NWConnection`, backing the opt-in `AetherEngineSMB` product only (never linked by the core engine). NTLMv2 / guest, SMB 2.0.2 / 2.1. Replaced AMSMB2/libsmb2, which `EPERM`s on tvOS / iOS |
 | VideoToolbox | System | Native path video decode (HW where available, Apple's bundled SW dav1d on iOS / macOS) |
 | AVFoundation | System | AVPlayer + AVDisplayManager (native path); AVSampleBufferDisplayLayer + AVSampleBufferRenderSynchronizer (SW path) |

From 36c28ec2a97916c8d88d520d21bbdc59390c1664 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:31:18 +0100
Subject: [PATCH 009/132] feat(dovi): picture-order pairing and delivery
 building blocks for the dual-layer decoder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four self-contained pieces the dual-layer Profile 7 decoder is built from,
none of them wired to anything yet:

- HEVCPictureOrderCount: the H.265 picture order count (§8.3.1) of one
  layer, read from the parameter sets and each picture's first slice
  segment header. No decoding. Anything it cannot follow (unknown PPS/SPS,
  truncated header, pictures before the first IRAP) answers nil rather than
  a guess.
- DualLayerPictureAlignment: derives each layer's display slot from its
  POC and gives each enhancement-layer packet the presentation time of the
  base-layer picture in the same slot, so a stream whose enhancement layer
  has B-frames over a base layer without them pairs the right pictures.
  Falls back to access-unit pairing when a layer's POC is unavailable or
  the slots disagree by more than 16.
- FrameSideDataRing: fixed-capacity (32) ring of per-frame side data keyed
  by PTS, looked up within +-300 ticks.
- OrderedDelivery: hands composed frames across the VideoToolbox / Metal
  queue boundary in decode order.

Also exposes A53SEIParser.unescapeRBSP and parseHVCCParameterSets
(DoviRpuConverter+Probe) at module scope, which the POC reader and its
test use. No behaviour change: nothing calls these types. Not in this PR:
the decoder that uses them, the routing, the docs.

Tests: DualLayerPictureAlignmentTests, FrameSideDataRingTests,
OrderedDeliveryTests.
---
 .../AetherEngine/Decoder/A53SEIParser.swift   |   2 +-
 .../Decoder/DualLayerPictureAlignment.swift   | 173 ++++++++++
 .../Decoder/FrameSideDataRing.swift           | 164 +++++++++
 .../Decoder/OrderedDelivery.swift             | 326 ++++++++++++++++++
 .../Video/DoviRpuConverter+Probe.swift        |   2 +-
 .../Video/HEVCPictureOrderCount.swift         | 155 +++++++++
 ...lLayerPictureAlignmentSyntheticTests.swift | 170 +++++++++
 .../DualLayerPictureAlignmentTests.swift      | 137 ++++++++
 .../FrameSideDataRingTests.swift              | 152 ++++++++
 .../HEVCPictureOrderCountTests.swift          | 321 +++++++++++++++++
 .../HEVCSyntheticBitstream.swift              | 127 +++++++
 .../OrderedDeliveryTests.swift                | 247 +++++++++++++
 12 files changed, 1974 insertions(+), 2 deletions(-)
 create mode 100644 Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift
 create mode 100644 Sources/AetherEngine/Decoder/FrameSideDataRing.swift
 create mode 100644 Sources/AetherEngine/Decoder/OrderedDelivery.swift
 create mode 100644 Sources/AetherEngine/Video/HEVCPictureOrderCount.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
 create mode 100644 Tests/AetherEngineTests/FrameSideDataRingTests.swift
 create mode 100644 Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift
 create mode 100644 Tests/AetherEngineTests/HEVCSyntheticBitstream.swift
 create mode 100644 Tests/AetherEngineTests/OrderedDeliveryTests.swift

diff --git a/Sources/AetherEngine/Decoder/A53SEIParser.swift b/Sources/AetherEngine/Decoder/A53SEIParser.swift
index 2b34f6371..7c2d47933 100644
--- a/Sources/AetherEngine/Decoder/A53SEIParser.swift
+++ b/Sources/AetherEngine/Decoder/A53SEIParser.swift
@@ -116,7 +116,7 @@ enum A53SEIParser {
 
     /// Strip emulation-prevention bytes (00 00 03 -> 00 00). In a valid stream, a 0x03 after two
     /// zeros is always an EPB, so the unconditional drop matches FFmpeg's h2645 unescape.
-    private static func unescapeRBSP(_ p: UnsafePointer<UInt8>, _ n: Int) -> [UInt8] {
+    static func unescapeRBSP(_ p: UnsafePointer<UInt8>, _ n: Int) -> [UInt8] {
         var out = [UInt8]()
         out.reserveCapacity(n)
         var zeros = 0
diff --git a/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift b/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift
new file mode 100644
index 000000000..80a27660e
--- /dev/null
+++ b/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift
@@ -0,0 +1,173 @@
+import Foundation
+
+/// Gives each enhancement-layer packet the presentation time of the base-layer picture it belongs to.
+///
+/// A profile 7 access unit carries one picture of each layer, and the container stamps the unit with
+/// the base layer's presentation time. The two pictures of one unit need not be the same frame: the
+/// enhancement layer may have its own GOP (B-frames where the base layer has none, IDRs at other cuts),
+/// so its picture in a given unit can be a frame or two earlier or later. A spec decoder composes each
+/// layer's pictures in that layer's display order; pairing by access unit instead puts a neighbouring
+/// frame's residual onto moving detail.
+///
+/// Each layer's display order is followed causally as a display slot counted in access units from the
+/// start (or the last seek): a picture that opens a sequence (IDR, BLA, a CRA after a seek) is shown
+/// after every picture decoded before it, so its slot is the number of units before it; later pictures
+/// of that sequence sit at slot + (POC - its POC). Streams whose layers share a GOP (every UHD Blu-ray
+/// title seen so far) get identical slots in both layers, and their packets keep their unit's time.
+///
+/// Two limits, both of which end in the access-unit pairing a stream without this type would get:
+/// - A sequence opener takes the slot "units before it", which assumes the previous sequence's slots
+///   all lie below that count. If the previous sequence's POC numbering ran ahead of its unit count
+///   (gaps in its POCs), the opener and its first followers share slots with its last pictures, and
+///   the time kept for a slot is the newer one, so a restamp into that range can land on the wrong
+///   picture. It needs a mid-stream sequence change with such gaps; a seek resets all slots.
+/// - A layer whose slots drift further than `maxSlotDistance` from the unit position stops being
+///   placed until its next IDR or BLA (the only mid-stream pictures that open a sequence; a CRA
+///   opens one only at the start or after a seek). A stream that cuts GOPs with CRAs (open GOP)
+///   therefore stays on access-unit pairing from that point until the next seek.
+struct DualLayerPictureAlignment {
+
+    /// A slot further than this from the unit's own position is further than any DPB allows, so the
+    /// layer's sequence is not trusted (dolby-vision-fel.md §5.3).
+    static let maxSlotDistance = 16
+
+    /// How many slots earlier than its own unit an enhancement picture may be restamped. A base-layer
+    /// frame waits for its partner only until K newer base frames have arrived (`DualLayerVideoDecoder.
+    /// maxLayerSkewFrames`), so an enhancement picture restamped to a frame further back than that
+    /// finds its partner already bypassed and is dropped: the pair is lost without anyone noticing.
+    /// Beyond this distance the unit is treated like one whose slot is unknown (access-unit pairing,
+    /// counted in `unabsorbableRestamps`). The owner sets it from its own skew bound; the default is
+    /// the DPB bound, which absorbs anything the slots can say.
+    var maxBackwardRestamp = DualLayerPictureAlignment.maxSlotDistance
+    /// Units whose enhancement picture sat further back than `maxBackwardRestamp`.
+    private(set) var unabsorbableRestamps = 0
+
+    /// One layer's display slots.
+    private struct Layer {
+        var counter = HEVCPictureOrderCount()
+        /// slot = POC + offset in the current sequence; nil until a sequence opens, and for the rest of
+        /// a sequence whose slots cannot be trusted.
+        var offset: Int?
+
+        mutating func slot(_ p: HEVCPictureOrderCount.Picture, unit: Int) -> Int? {
+            if p.startsSequence {
+                offset = unit - p.poc
+                return unit
+            }
+            guard let offset else { return nil }
+            // A leading picture of the opener (RADL, POC below the IRAP's) is shown before the IRAP
+            // but decoded after it. That does not break the numbering: POC still steps one per
+            // picture, so it keeps the sequence's offset and lands before the opener's slot.
+            // (RASL pictures of a sequence-opening CRA never get here: `HEVCPictureOrderCount` does
+            // not report them, since a decoder starting at the CRA does not output them.)
+            let s = p.poc + offset
+            // Further from decode order than any DPB allows: POC is not stepping one per frame.
+            if abs(s - unit) > DualLayerPictureAlignment.maxSlotDistance { self.offset = nil; return nil }
+            return s
+        }
+    }
+
+    private var base = Layer()
+    private var enhancement = Layer()
+    /// Access units since the start or the last seek.
+    private var units = 0
+    /// Presentation time of recent base-layer pictures, by slot.
+    private var baseTime: [Int: Int64] = [:]
+    /// First base-layer slot seen since the reset: with the latest it gives the time per slot.
+    private var origin: (slot: Int, pts: Int64)?
+    private var latest: (slot: Int, pts: Int64)?
+
+    /// Units whose enhancement-layer picture was moved to another frame's time.
+    private(set) var reorderedUnits = 0
+    /// Whether the last unit's enhancement-layer picture was placed by its display slot (as opposed
+    /// to keeping its unit's time for want of one).
+    private(set) var lastEnhancementPlaced = false
+
+    mutating func seedBaseParameterSets(_ nals: [[UInt8]]) {
+        base.counter.feedParameterSets(nals)
+    }
+
+    /// After a seek both layers restart at their next IRAP.
+    mutating func reset() {
+        base.counter.reset(); base.offset = nil
+        enhancement.counter.reset(); enhancement.offset = nil
+        units = 0
+        baseTime.removeAll()
+        origin = nil
+        latest = nil
+    }
+
+    /// Reads both layers' pictures from one access unit (base-layer NALs, and enhancement-layer NALs
+    /// wrapped in unspec63) and returns the time to stamp on its enhancement-layer packet. `pts` is the
+    /// unit's presentation time, in the stream's time base. It comes back unchanged when both pictures
+    /// are the same frame, and whenever the enhancement picture's slot is not known.
+    mutating func enhancementPTS(_ data: UnsafePointer<UInt8>, _ size: Int, framing: VideoNALFraming, pts: Int64) -> Int64 {
+        var bl: HEVCPictureOrderCount.Picture?
+        var el: HEVCPictureOrderCount.Picture?
+        A53SEIParser.forEachNAL(data, size, framing) { nal, len in
+            let type = (nal[0] >> 1) & 0x3F
+            if type == 63 {
+                if len > 4, let p = enhancement.counter.feed(nal + 2, len - 2), el == nil { el = p }
+            } else if type < 48 {
+                if let p = base.counter.feed(nal, len), bl == nil { bl = p }
+            }
+        }
+        let unit = units
+        units += 1
+        lastEnhancementPlaced = false
+
+        let blSlot = bl.flatMap { base.slot($0, unit: unit) }
+        var elSlot = el.flatMap { enhancement.slot($0, unit: unit) }
+        if let slot = elSlot, (blSlot ?? unit) - slot > maxBackwardRestamp {
+            unabsorbableRestamps += 1
+            elSlot = nil
+        }
+        guard pts != Int64.min else { return pts }
+        if let blSlot {
+            baseTime[blSlot] = pts
+            if baseTime.count > 64 {
+                for s in baseTime.keys where s < unit - 32 { baseTime.removeValue(forKey: s) }
+            }
+            if origin == nil { origin = (blSlot, pts) }
+            latest = (blSlot, pts)
+        }
+
+        guard let elSlot else { return pts }
+        lastEnhancementPlaced = true
+        if elSlot == blSlot { return pts }
+        if let known = baseTime[elSlot] {
+            reorderedUnits += 1
+            return known
+        }
+        // That base-layer picture is still to come: extrapolate from the time per slot.
+        guard let origin, let latest, latest.slot != origin.slot,
+              let result = Self.extrapolate(origin: origin, latest: latest, slot: elSlot) else {
+            lastEnhancementPlaced = false; return pts
+        }
+        reorderedUnits += 1
+        return result
+    }
+
+    /// Time of a slot beyond the latest one, from the time per slot between two known ones. Timestamps
+    /// come from the stream, so every step is overflow-checked: a crafted value makes this decline
+    /// (nil), never trap.
+    static func extrapolate(origin: (slot: Int, pts: Int64), latest: (slot: Int, pts: Int64), slot: Int) -> Int64? {
+        guard let span = checkedSub(latest.pts, origin.pts),
+              let slotSpan = checkedSub(latest.slot, origin.slot), slotSpan != 0,
+              let ahead = checkedSub(slot, latest.slot) else { return nil }
+        let perSlot = Double(span) / Double(slotSpan)
+        guard perSlot > 0, perSlot.isFinite else { return nil }
+        let offset = (Double(ahead) * perSlot).rounded()
+        // 2^63 is exactly representable; anything at or beyond it, or NaN, cannot convert.
+        guard offset.isFinite, offset > -9.223372036854775807e18, offset < 9.223372036854775807e18 else { return nil }
+        return checkedAdd(latest.pts, Int64(offset))
+    }
+
+    private static func checkedSub<T: FixedWidthInteger>(_ a: T, _ b: T) -> T? {
+        let (v, o) = a.subtractingReportingOverflow(b); return o ? nil : v
+    }
+
+    private static func checkedAdd<T: FixedWidthInteger>(_ a: T, _ b: T) -> T? {
+        let (v, o) = a.addingReportingOverflow(b); return o ? nil : v
+    }
+}
diff --git a/Sources/AetherEngine/Decoder/FrameSideDataRing.swift b/Sources/AetherEngine/Decoder/FrameSideDataRing.swift
new file mode 100644
index 000000000..51310d5e1
--- /dev/null
+++ b/Sources/AetherEngine/Decoder/FrameSideDataRing.swift
@@ -0,0 +1,164 @@
+import Foundation
+
+/// Fixed-capacity ring buffer for Dolby Vision per-frame side data (dolby-vision-fel.md §5.3).
+///
+/// Stores `{ params, dmNAL }` keyed by canonical PTS.
+/// Fixed capacity of 32 entries (reorder depth plus maximum layer skew with margin).
+/// Insert overwrites the oldest entry when full.
+/// Lookup scans up to 32 entries for the nearest key within ±300 ticks (~3.3 ms).
+/// No heap reallocation on insert, no sorting, no dictionary overhead.
+struct FrameSideDataRing: Sendable {
+    static let capacity = 32
+    static let jitterToleranceTicks: Int64 = 300
+
+    /// Distance between two canonical keys, or nil when either is the missing-PTS key (`Int64.min`) or the
+    /// distance does not fit. A frame without a timestamp has no neighbour, so nothing matches it; and
+    /// the trapping `abs` of a plain subtraction overflows on exactly that key.
+    static func distance(_ a: Int64, _ b: Int64) -> UInt64? {
+        guard a != Int64.min, b != Int64.min else { return nil }
+        let (d, overflow) = a.subtractingReportingOverflow(b)
+        return overflow ? nil : d.magnitude
+    }
+
+    /// True when both keys carry a timestamp and are within the pairing jitter of each other.
+    static func isWithinJitter(_ a: Int64, _ b: Int64) -> Bool {
+        guard let d = distance(a, b) else { return false }
+        return d <= UInt64(jitterToleranceTicks)
+    }
+
+    struct Entry: Sendable {
+        var key: Int64
+        var params: DoviMetalParams?
+        var dmNAL: [UInt8]?
+
+        init(key: Int64, params: DoviMetalParams? = nil, dmNAL: [UInt8]? = nil) {
+            self.key = key
+            self.params = params
+            self.dmNAL = dmNAL
+        }
+    }
+
+    private var buffer: [Entry?]
+    private var writeIndex: Int = 0
+    private var entryCount: Int = 0
+
+    init() {
+        self.buffer = Array(repeating: nil, count: Self.capacity)
+    }
+
+    var count: Int { entryCount }
+    var isEmpty: Bool { entryCount == 0 }
+
+    var paramsCount: Int {
+        var result = 0
+        for i in 0..<entryCount {
+            let idx = (writeIndex - entryCount + i + Self.capacity) % Self.capacity
+            if buffer[idx]?.params != nil { result += 1 }
+        }
+        return result
+    }
+
+    var dmNALCount: Int {
+        var result = 0
+        for i in 0..<entryCount {
+            let idx = (writeIndex - entryCount + i + Self.capacity) % Self.capacity
+            if buffer[idx]?.dmNAL != nil { result += 1 }
+        }
+        return result
+    }
+
+    /// Inserts or updates an entry for `key`.
+    /// If an entry already exists for this exact key, updates its fields.
+    /// Otherwise overwrites the oldest slot in the ring.
+    mutating func insert(key: Int64, params: DoviMetalParams? = nil, dmNAL: [UInt8]? = nil) {
+        // If an entry exists for the exact key, update in-place without consuming a new slot:
+        for i in 0..<entryCount {
+            let idx = (writeIndex - entryCount + i + Self.capacity) % Self.capacity
+            if let entry = buffer[idx], entry.key == key {
+                if let params { buffer[idx]?.params = params }
+                if let dmNAL { buffer[idx]?.dmNAL = dmNAL }
+                return
+            }
+        }
+
+        // Otherwise write at writeIndex (overwriting the oldest if at capacity):
+        buffer[writeIndex] = Entry(key: key, params: params, dmNAL: dmNAL)
+        writeIndex = (writeIndex + 1) % Self.capacity
+        if entryCount < Self.capacity {
+            entryCount += 1
+        }
+    }
+
+    /// Finds the entry nearest to `key` within ±300 ticks.
+    func findNearestIndex(key: Int64) -> Int? {
+        var bestIndex: Int?
+        var minDiff = UInt64.max
+
+        for i in 0..<entryCount {
+            let idx = (writeIndex - entryCount + i + Self.capacity) % Self.capacity
+            guard let entry = buffer[idx] else { continue }
+            guard let diff = Self.distance(entry.key, key) else { continue }
+            if diff <= UInt64(Self.jitterToleranceTicks) && diff < minDiff {
+                minDiff = diff
+                bestIndex = idx
+                if diff == 0 { break } // Exact match
+            }
+        }
+        return bestIndex
+    }
+
+    /// Finds the nearest entry to `key` within ±300 ticks.
+    func find(key: Int64) -> Entry? {
+        guard let idx = findNearestIndex(key: key) else { return nil }
+        return buffer[idx]
+    }
+
+    /// Removes and returns `dmNAL` for `key` (or nearest within ±300 ticks).
+    mutating func removeDisplayMetadata(key: Int64) -> [UInt8]? {
+        var bestIndex: Int?
+        var minDiff = UInt64.max
+
+        for i in 0..<entryCount {
+            let idx = (writeIndex - entryCount + i + Self.capacity) % Self.capacity
+            guard let entry = buffer[idx], entry.dmNAL != nil else { continue }
+            guard let diff = Self.distance(entry.key, key) else { continue }
+            if diff <= UInt64(Self.jitterToleranceTicks) && diff < minDiff {
+                minDiff = diff
+                bestIndex = idx
+                if diff == 0 { break }
+            }
+        }
+
+        guard let idx = bestIndex, let nal = buffer[idx]?.dmNAL else { return nil }
+        buffer[idx]?.dmNAL = nil
+        return nal
+    }
+
+    /// Removes and returns `params` for `key` (or nearest within ±300 ticks).
+    mutating func removeParams(key: Int64) -> DoviMetalParams? {
+        var bestIndex: Int?
+        var minDiff = UInt64.max
+
+        for i in 0..<entryCount {
+            let idx = (writeIndex - entryCount + i + Self.capacity) % Self.capacity
+            guard let entry = buffer[idx], entry.params != nil else { continue }
+            guard let diff = Self.distance(entry.key, key) else { continue }
+            if diff <= UInt64(Self.jitterToleranceTicks) && diff < minDiff {
+                minDiff = diff
+                bestIndex = idx
+                if diff == 0 { break }
+            }
+        }
+
+        guard let idx = bestIndex, let p = buffer[idx]?.params else { return nil }
+        buffer[idx]?.params = nil
+        return p
+    }
+
+    /// Removes all entries from the ring.
+    mutating func removeAll() {
+        buffer = Array(repeating: nil, count: Self.capacity)
+        writeIndex = 0
+        entryCount = 0
+    }
+}
diff --git a/Sources/AetherEngine/Decoder/OrderedDelivery.swift b/Sources/AetherEngine/Decoder/OrderedDelivery.swift
new file mode 100644
index 000000000..35da8b13e
--- /dev/null
+++ b/Sources/AetherEngine/Decoder/OrderedDelivery.swift
@@ -0,0 +1,326 @@
+import Foundation
+import CoreMedia
+import CoreVideo
+import os
+
+/// A `CVPixelBuffer` (or the display metadata riding with it) on its way across a
+/// queue boundary.
+///
+/// `CVPixelBuffer` is a CoreFoundation class and not `Sendable`, but the handoff
+/// is a baton pass: whichever thread produced the buffer (a VideoToolbox output
+/// thread, or Metal's completion queue) stops touching it the moment it is handed
+/// to ``OrderedDelivery``, and `emit` is the only reader after that. The box
+/// states that rather than making the surrounding types unchecked.
+struct SendableBuffer: @unchecked Sendable {
+    let value: CVPixelBuffer
+}
+
+/// One frame ready to reach the display layer, composed or bypassed alike
+/// (dolby-vision-fel.md §5.7).
+///
+/// Everything `OrderedDelivery.emit` needs is resolved and carried here
+/// *before* the frame reaches the delivery queue: `dmNAL` and `hdr10Data` are
+/// looked up once, under the decoder's lock, at the same point pairing decides
+/// what happens to the frame (mirroring how `hdr10Data` already arrives as a
+/// parameter rather than a cache lookup). That is what lets `emit` attach
+/// metadata and call `onFrame` without reaching into the decoder's frame state.
+/// (`emit` itself may briefly take the decoder's lock through `onFrame`, as the
+/// decoder's own `reportDecodedFormat` does on this queue; what is guaranteed is the
+/// other direction, below.)
+struct DeliveredFrame: Sendable {
+    let buffer: SendableBuffer
+    let pts: CMTime
+    let hdr10Data: Data?
+    /// The Profile 8.1 `unspec62` NAL (with its 2-byte header) for this frame,
+    /// or nil if none was cached for its PTS. See `DoviDisplayMetadata.attach`.
+    let dmNAL: [UInt8]?
+}
+
+/// Ordered, single-owner delivery of decoded and composed frames to the host
+/// (dolby-vision-fel.md §5.7).
+///
+/// Every outgoing frame — composed on the GPU or bypassed straight from
+/// pairing — reaches the display layer through ``fulfil(ticket:epoch:_:)``.
+/// One serial queue, `qos: .userInteractive`, orders both kinds the same way
+/// once they reach it, and `emit` — the Dolby Vision attachment plus
+/// `onFrame` — runs there with **no lock held by this type**, and the invariant
+/// the decoder keeps in return is that nothing ever holds its lock while waiting on this
+/// queue (`fulfil` is non-blocking, `barrier()` is called only after unlocking), so a
+/// delivery that takes the decoder's lock briefly can never deadlock against it.
+/// Delivering under the decoder's `NSRecursiveLock` would call
+/// `emit` (and with it the renderer's `enqueue`, which takes its own lock)
+/// from inside that lock, one frame away from nesting it inside whatever lock
+/// the host's `onFrame` takes. `OrderedDelivery` shares no state with the
+/// decoder's lock: every field below is confined to `queue`.
+///
+/// `DoviFelComposer` keeps a small relay queue of its own
+/// (`deliveryQueue`), which every composed frame's completion still hops
+/// through before it ever calls `fulfil`. That queue is a §4.3 firewall
+/// against Metal's completion handler ever blocking, not a second ordering
+/// mechanism — `fulfil` reorders by ticket no matter which thread or queue
+/// calls it, so a bypass calling in directly from a VideoToolbox thread and
+/// a composition arriving via that relay hop are indistinguishable once
+/// they reach `queue`. See `DualLayerVideoDecoder.swift`'s `orderedDelivery`
+/// doc and dolby-vision-fel.md §5.7, §5.9 for the full justification.
+///
+/// **Epochs instead of moving the line under a lock.** A ticket carries the
+/// epoch it was issued in. ``reset(epoch:nextTicket:)`` bumps `epoch` and
+/// fast-forwards `nextToEmit` with `queue.sync`, which waits for anything
+/// already running or queued ahead of it to finish first. A composition
+/// already committed to the GPU when `flush()`/`close()` runs still calls
+/// `fulfil` later, from Metal's completion handler, tagged with the *old*
+/// epoch; by then `self.epoch` has moved on, so it is dropped instead of
+/// reaching `onFrame`. That is invariant I3 (dolby-vision-fel.md §5.12), and it holds
+/// without the decoder ever blocking on the GPU or the delivery queue while
+/// holding its own lock.
+///
+/// **`resetAsync`/`barrier`: the same guarantee, callable under a lock.**
+/// `reset` cannot be called while `DualLayerVideoDecoder.lock` is held — it
+/// would block a `queue.sync` under a lock, the exact shape I8 forbids — but
+/// `flush()`/`close()` still need the epoch bump ordered *with* the ticket
+/// issuance it retires (a ticket for the new epoch, issued the instant the lock that raised it is
+/// released, must never be able to reach `fulfil` before the matching reset
+/// has even been enqueued). ``resetAsync(epoch:nextTicket:)`` is the
+/// non-blocking half — a plain `queue.async`, safe to call from inside a
+/// lock — and ``barrier()`` is the wait, called after the lock is released.
+/// Because both the reset and the racing ticket's eventual `fulfil` can only
+/// reach `queue` in an order `lock` already fixed (nothing can issue a
+/// ticket for the new epoch until the critical section that called
+/// `resetAsync` has unlocked), FIFO ordering on `queue` does the rest: the
+/// reset is always ahead of it. `reset` itself is just
+/// `resetAsync` + an immediate `barrier()`, kept for callers (tests, mainly)
+/// that have no lock to hold and want the old synchronous call.
+///
+/// **Stall guard.** A ticket that never arrives (a bug, or a completion that
+/// silently failed) would otherwise stall every later frame forever, since
+/// `nextToEmit` never finds it. Once more than `maxFramesInFlight + K + 2`
+/// frames are backed up behind the head of the line — more than could ever be
+/// legitimately in flight at once — the missing ticket is skipped and logged.
+/// A lost ticket costs one frame, not the session.
+final class OrderedDelivery: @unchecked Sendable {
+
+    private static let signpostLog = OSLog(subsystem: EngineLog.subsystem, category: "dovi.delivery")
+
+    private let queue: DispatchQueue
+
+    // Confined to `queue`: no lock. Nothing outside this class ever reads or
+    // writes these, including the decoder that owns this instance.
+    private var epoch: UInt64 = 0
+    private var nextToEmit: UInt64 = 0
+    private var pending: [UInt64: PendingEntry] = [:]
+    private var onFrame: DecodedFrameHandler?
+    /// One-shot-per-stall latch so a run of consecutive missing tickets logs
+    /// once for the event rather than once per skipped ticket.
+    private var stallLogPending = false
+
+    private let pendingCountLock = NSLock()
+    private var pendingCount: Int = 0
+    private var peakPendingCount: Int = 0
+
+    private struct PendingEntry {
+        let frame: DeliveredFrame
+        let signpostID: OSSignpostID
+    }
+
+    /// A ticket that has waited this many frames behind the head of the line
+    /// with no sign of arriving is presumed lost (dolby-vision-fel.md §5.7): sized off the
+    /// most frames that can legitimately be outstanding at once — GPU slots
+    /// plus pairing skew — with two more of margin.
+    private let stallThreshold: Int
+
+    init(maxFramesInFlight: Int, maxLayerSkew: Int, label: String = "de.superuser404.dovi.delivery") {
+        self.queue = DispatchQueue(label: label, qos: .userInteractive)
+        self.stallThreshold = maxFramesInFlight + maxLayerSkew + 2
+    }
+
+    /// Installs (or, at `close()`, clears) the host callback. Runs on `queue`
+    /// so it is ordered against in-flight `fulfil` calls exactly like every
+    /// other piece of state here — a handler installed before any frame is
+    /// paired is guaranteed to be in place before the first `emit`, and one
+    /// cleared by `close()` cannot race a frame still draining out of the
+    /// queue.
+    ///
+    /// This is `queue.async`, not `queue.sync`: `close()` (and
+    /// `DualLayerVideoDecoder.onFrame`'s setter) can return before `onFrame`
+    /// is actually cleared here. That is harmless: nothing can reach `emit` after `close()`'s own
+    /// `reset`/`barrier` pair has returned, old-epoch or new, so there is no
+    /// window in which a stale handler could still fire; this call clearing
+    /// a beat later just means the closure is retained a beat longer.
+    func setOnFrame(_ handler: DecodedFrameHandler?) {
+        queue.async { [self] in
+            onFrame = handler
+        }
+    }
+
+    /// Hands one frame's place in line to the queue. Callable from any thread
+    /// — a VideoToolbox output thread for a bypass, Metal's completion queue
+    /// for a composition — with no lock held on either side of the call.
+    ///
+    /// `epoch` is read by the caller under the decoder's lock at the moment
+    /// the ticket was issued (dolby-vision-fel.md §5.7: "a ticket carries the epoch it was
+    /// issued in"). It is compared here, on `queue`, against the epoch
+    /// `reset` last installed; a mismatch means a flush or close happened in
+    /// between and this frame predates it.
+    func fulfil(ticket: UInt64, epoch callerEpoch: UInt64, _ frame: DeliveredFrame) {
+        let signpostID = OSSignpostID(log: Self.signpostLog)
+        os_signpost(.begin, log: Self.signpostLog, name: "Delivery", signpostID: signpostID,
+                    "ticket=%{public}llu", ticket)
+        queue.async { [self] in
+            guard callerEpoch == epoch, ticket >= nextToEmit else {
+                os_signpost(.end, log: Self.signpostLog, name: "Delivery", signpostID: signpostID, "dropped")
+                return
+            }
+            pending[ticket] = PendingEntry(frame: frame, signpostID: signpostID)
+            updatePendingCounts()
+            drainReady()
+        }
+    }
+
+    /// Bumps the epoch and fast-forwards the head of the line to `nextTicket`,
+    /// dropping anything still pending behind it. Enqueues the work
+    /// (`queue.async`) rather than waiting for it, so this is safe to call
+    /// while holding a lock — see the type doc's "resetAsync/barrier"
+    /// section and ``barrier()``.
+    ///
+    /// The caller is responsible for the ordering guarantee this depends on:
+    /// nothing that could produce a ticket for `newEpoch` may be able to run
+    /// until *after* the call to this method has returned (in
+    /// `DualLayerVideoDecoder`, that is what holding `lock` across this call
+    /// provides — pairing cannot issue a new-epoch ticket until the same
+    /// critical section that calls this has unlocked). Given that, FIFO
+    /// ordering on `queue` guarantees this reset always runs before any
+    /// `fulfil` for the epoch it installs, however soon that `fulfil` is
+    /// called after this method returns.
+    func resetAsync(epoch newEpoch: UInt64, nextTicket: UInt64) {
+        queue.async { [self] in
+            for entry in pending.values {
+                os_signpost(.end, log: Self.signpostLog, name: "Delivery", signpostID: entry.signpostID, "reset")
+            }
+            epoch = newEpoch
+            nextToEmit = nextTicket
+            pending.removeAll()
+            stallLogPending = false
+            pendingCountLock.lock()
+            pendingCount = 0
+            peakPendingCount = 0
+            pendingCountLock.unlock()
+        }
+    }
+
+    /// Blocks until everything enqueued on `queue` ahead of this call —
+    /// every `fulfil` and `resetAsync` already running or waiting, in
+    /// particular the one a caller just enqueued — has finished running.
+    ///
+    /// This is `reset`'s wait, split out so `resetAsync` can be enqueued
+    /// under a lock and this can be called after releasing it: waiting here
+    /// while still holding `DualLayerVideoDecoder.lock` would be exactly the
+    /// blocking-wait-under-a-lock shape I8 forbids. The precondition catches
+    /// the one way to defeat the wait itself: calling this from inside
+    /// `onFrame`, which would deadlock the queue against its own
+    /// synchronous wait.
+    func barrier() {
+        dispatchPrecondition(condition: .notOnQueue(queue))
+        queue.sync {}
+    }
+
+    /// `resetAsync` followed immediately by `barrier()`: bumps the epoch and
+    /// fast-forwards the head of the line to `nextTicket`, and does not
+    /// return until that has actually happened — nothing after this call
+    /// returns can reach `onFrame` under the old epoch (invariant I3,
+    /// dolby-vision-fel.md §5.8). For callers with no lock to hold across the two halves (tests,
+    /// mainly); `DualLayerVideoDecoder.flush()`/`close()` call `resetAsync`
+    /// and `barrier()` separately so the wait happens outside `lock`.
+    func reset(epoch newEpoch: UInt64, nextTicket: UInt64) {
+        resetAsync(epoch: newEpoch, nextTicket: nextTicket)
+        barrier()
+    }
+
+    /// Emits every ticket that has become the head of the line, in order,
+    /// applying the stall guard when the head is missing and a bound number
+    /// of frames have backed up behind it. Runs on `queue`.
+    private func drainReady() {
+        defer { updatePendingCounts() }
+        while true {
+            if let entry = pending.removeValue(forKey: nextToEmit) {
+                nextToEmit &+= 1
+                stallLogPending = false
+                emit(entry.frame)
+                os_signpost(.end, log: Self.signpostLog, name: "Delivery", signpostID: entry.signpostID)
+                continue
+            }
+            guard pending.count > stallThreshold else { break }
+            // The ticket at the head is not coming: skip it so the frames
+            // already backed up behind it are not stalled forever
+            // (dolby-vision-fel.md §5.7). This costs exactly the one frame at `nextToEmit`.
+            if !stallLogPending {
+                EngineLog.emit(
+                    "[OrderedDelivery] stall guard: ticket \(nextToEmit) never arrived with \(pending.count) frames pending; skipping",
+                    category: .swPlayback)
+                stallLogPending = true
+            }
+            nextToEmit &+= 1
+        }
+    }
+
+    /// Attaches the Dolby Vision display metadata and hands the frame to the
+    /// host (see `dolby-vision-fel.md §4.1`). Runs on `queue`, holding no lock of this
+    /// type's. `onFrame` may take the decoder's lock for a moment; that cannot deadlock because
+    /// no caller of `fulfil`/`resetAsync` holds a lock while waiting on `queue` (only `barrier()`
+    /// and `reset()` wait, and they are called with no decoder lock held).
+    private func emit(_ frame: DeliveredFrame) {
+        #if DEBUG
+        dispatchPrecondition(condition: .onQueue(queue))
+        #endif
+        DoviDisplayMetadata.attach(rpuNAL: frame.dmNAL, to: frame.buffer.value)
+        onFrame?(frame.buffer.value, frame.pts, frame.hdr10Data)
+    }
+
+    private func updatePendingCounts() {
+        pendingCountLock.lock()
+        let count = pending.count
+        pendingCount = count
+        if count > peakPendingCount {
+            peakPendingCount = count
+        }
+        pendingCountLock.unlock()
+    }
+
+    /// Peak count of pending frames waiting in the delivery queue since the last read.
+    /// Resets the peak to the current pending count for the next interval (dolby-vision-fel.md §5.11).
+    func takePeakPendingCount() -> Int {
+        pendingCountLock.lock()
+        defer { pendingCountLock.unlock() }
+        let peak = peakPendingCount
+        peakPendingCount = pendingCount
+        return peak
+    }
+
+    /// Current count of pending frames waiting in the delivery queue without blocking `queue`.
+    var currentPendingCount: Int {
+        pendingCountLock.lock()
+        defer { pendingCountLock.unlock() }
+        return pendingCount
+    }
+
+    // MARK: - Test seams
+
+    /// `queue.sync` reads for `DualLayerVideoDecoder.stateSnapshotForTesting`
+    /// and its `onFrame` getter (never on a hot path — nothing in production
+    /// reads the handler back, only assigns it).
+    ///
+    /// Every accessor below is
+    /// `queue.sync`, same as `reset`/`barrier`. Reading any of them — in
+    /// particular `currentOnFrame`, which backs `DualLayerVideoDecoder.
+    /// onFrame`'s getter — from inside a closure already running on `queue`
+    /// (i.e. from inside `emit`, or a host `onFrame` implementation that
+    /// reads the decoder's own `onFrame` back) deadlocks, the same
+    /// `dispatchPrecondition(.notOnQueue)` violation `reset`/`barrier` guard
+    /// against explicitly. Nothing in this codebase does that today — the
+    /// getter exists for the host to read what it itself assigned, not for
+    /// `onFrame`'s body to call back into — so there is no precondition
+    /// here, only this note.
+    var pendingCountForTesting: Int { queue.sync { pending.count } }
+    var nextToEmitForTesting: UInt64 { queue.sync { nextToEmit } }
+    var hasOnFrameForTesting: Bool { queue.sync { onFrame != nil } }
+    var currentOnFrame: DecodedFrameHandler? { queue.sync { onFrame } }
+}
diff --git a/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift b/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift
index c724255af..89c8eb5ae 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift
@@ -4,7 +4,7 @@ import AetherLibavcodec
 import AetherLibavutil
 
 /// Extract VPS/SPS/PPS NALs from hvcC extradata (22-byte header + numOfArrays arrays). Returns raw NAL bytes without length prefix or start code.
-private func parseHVCCParameterSets(_ ed: UnsafePointer<UInt8>, _ size: Int) -> [[UInt8]] {
+func parseHVCCParameterSets(_ ed: UnsafePointer<UInt8>, _ size: Int) -> [[UInt8]] {
     guard size > 23 else { return [] }
     var out: [[UInt8]] = []
     let numArrays = Int(ed[22])
diff --git a/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift b/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift
new file mode 100644
index 000000000..49dfa5ff1
--- /dev/null
+++ b/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift
@@ -0,0 +1,155 @@
+import Foundation
+
+/// H.265 picture order count (ITU-T H.265 §8.3.1) for one layer, read from the parameter sets and
+/// the first slice segment header of each picture. Nothing is decoded: the POC is what puts a
+/// picture in display order, and the two layers of a Dolby Vision profile 7 stream are paired by it.
+///
+/// Feed every NAL of the layer in decode order. Anything it cannot follow (a slice whose PPS or SPS
+/// it has not seen, a truncated header, pictures before the first IRAP) answers nil rather than a guess.
+struct HEVCPictureOrderCount {
+
+    struct Picture: Equatable {
+        let poc: Int
+        /// An IRAP with NoRaslOutputFlag = 1 (IDR, BLA, or a CRA that opens the bitstream, follows an
+        /// end of sequence, or follows a seek): POC numbering restarts here.
+        let startsSequence: Bool
+    }
+
+    private struct SPS { let pocLsbBits: Int; let separateColourPlane: Bool }
+    private struct PPS { let sps: Int; let outputFlagPresent: Bool; let extraSliceHeaderBits: Int }
+
+    private var sps: [Int: SPS] = [:]
+    private var pps: [Int: PPS] = [:]
+    private var prevTid0POC = 0
+    /// True until an IRAP has opened a sequence; set again by `reset()` and by an end of sequence.
+    private var awaitingIRAP = true
+    /// True while the most recent IRAP had NoRaslOutputFlag = 1 and can have RASL pictures: those
+    /// reference pictures before the IRAP that a decoder starting here never had, so they are not
+    /// output (§8.1.3) and get no POC here. A CRA that follows a picture in the same sequence has
+    /// NoRaslOutputFlag = 0, and its RASL pictures are ordinary output pictures.
+    private var skippingRASL = false
+
+    /// After a seek: the next IRAP is handled as the first picture of the bitstream (HandleCraAsBlaFlag)
+    /// and pictures before it get no POC. Parameter sets are kept.
+    mutating func reset() {
+        awaitingIRAP = true
+    }
+
+    /// Feeds one NAL (2-byte header included, emulation prevention bytes intact). Returns the POC when
+    /// the NAL is the first slice segment of a picture.
+    mutating func feed(_ nal: UnsafePointer<UInt8>, _ len: Int) -> Picture? {
+        guard len > 2 else { return nil }
+        let type = Int((nal[0] >> 1) & 0x3F)
+        switch type {
+        case 33: parseSPS(nal, len); return nil
+        case 34: parsePPS(nal, len); return nil
+        case 36, 37: awaitingIRAP = true; return nil      // end of sequence / end of bitstream
+        case 0...9, 16...21: return parseSlice(type: type, temporalId: Int(nal[1] & 7) - 1, nal, len)
+        default: return nil
+        }
+    }
+
+    /// Parameter sets carried outside the stream (the hvcC arrays).
+    mutating func feedParameterSets(_ nals: [[UInt8]]) {
+        for nal in nals {
+            nal.withUnsafeBufferPointer { b in
+                if let base = b.baseAddress { _ = feed(base, b.count) }
+            }
+        }
+    }
+
+    // MARK: - Parsing
+
+    private static func reader(_ nal: UnsafePointer<UInt8>, _ len: Int, limit: Int) -> H264SPS.BitReader {
+        // The fields read here sit well inside the first bytes; cap the unescape at `limit`.
+        H264SPS.BitReader(A53SEIParser.unescapeRBSP(nal + 2, min(len, limit) - 2))
+    }
+
+    private mutating func parseSPS(_ nal: UnsafePointer<UInt8>, _ len: Int) {
+        var r = Self.reader(nal, len, limit: 256)
+        guard r.u(4) != nil, let subLayers = r.u(3), r.u(1) != nil,
+              r.skip(88), r.skip(8) else { return }             // general profile_tier_level, level_idc
+        var present: [(profile: Bool, level: Bool)] = []
+        for _ in 0..<subLayers {
+            guard let p = r.flag(), let l = r.flag() else { return }
+            present.append((p, l))
+        }
+        if subLayers > 0 { guard r.skip(2 * (8 - subLayers)) else { return } }
+        for p in present {
+            guard r.skip(p.profile ? 88 : 0), r.skip(p.level ? 8 : 0) else { return }
+        }
+        guard let id = r.ue(), let chroma = r.ue() else { return }
+        var separate = false
+        if chroma == 3 { guard let f = r.flag() else { return }; separate = f }
+        guard r.ue() != nil, r.ue() != nil, let window = r.flag() else { return }   // width, height
+        if window { for _ in 0..<4 { guard r.ue() != nil else { return } } }
+        guard r.ue() != nil, r.ue() != nil, let lsb = r.ue(), lsb <= 12 else { return }   // bit depths
+        sps[id] = SPS(pocLsbBits: lsb + 4, separateColourPlane: separate)
+    }
+
+    private mutating func parsePPS(_ nal: UnsafePointer<UInt8>, _ len: Int) {
+        var r = Self.reader(nal, len, limit: 32)
+        guard let id = r.ue(), let spsID = r.ue(), r.flag() != nil,   // dependent_slice_segments_enabled
+              let outputFlag = r.flag(), let extra = r.u(3) else { return }
+        pps[id] = PPS(sps: spsID, outputFlagPresent: outputFlag, extraSliceHeaderBits: extra)
+    }
+
+    private mutating func parseSlice(type: Int, temporalId: Int, _ nal: UnsafePointer<UInt8>, _ len: Int) -> Picture? {
+        let irap = (16...23).contains(type)
+        var r = Self.reader(nal, len, limit: 64)
+        guard r.flag() == true else { return nil }                    // first_slice_segment_in_pic_flag
+        if irap { guard r.flag() != nil else { return nil } }        // no_output_of_prior_pics_flag
+        guard let ppsID = r.ue(), let p = pps[ppsID], let s = sps[p.sps] else { return nil }
+        guard r.skip(p.extraSliceHeaderBits), r.ue() != nil else { return nil }   // slice_reserved_flag, slice_type
+        if p.outputFlagPresent { guard r.flag() != nil else { return nil } }
+        if s.separateColourPlane { guard r.skip(2) else { return nil } }
+
+        let idr = type == 19 || type == 20
+        var lsb = 0
+        if !idr { guard let v = r.u(s.pocLsbBits) else { return nil }; lsb = v }
+
+        if awaitingIRAP && !irap { return nil }                       // not decodable before an IRAP
+        let startsSequence = idr || (16...18).contains(type) || (irap && awaitingIRAP)
+        // NoRaslOutputFlag of an IRAP is 1 for IDR, BLA and a CRA that starts the sequence; an IDR
+        // has no RASL pictures at all. RASL_N / RASL_R (8, 9) of such an IRAP are skipped.
+        if irap { skippingRASL = startsSequence && !idr }
+        if skippingRASL && (type == 8 || type == 9) { return nil }
+        let msb: Int
+        if startsSequence {
+            msb = 0
+            awaitingIRAP = false
+        } else {
+            let maxLsb = 1 << s.pocLsbBits
+            let prevLsb = prevTid0POC & (maxLsb - 1)
+            let prevMsb = prevTid0POC - prevLsb
+            if lsb < prevLsb && prevLsb - lsb >= maxLsb / 2 {
+                msb = prevMsb + maxLsb
+            } else if lsb > prevLsb && lsb - prevLsb > maxLsb / 2 {
+                msb = prevMsb - maxLsb
+            } else {
+                msb = prevMsb
+            }
+        }
+        let poc = msb + lsb
+        // prevTid0Pic: TemporalId 0 and not a RASL, RADL or sub-layer non-reference picture.
+        let leading = (6...9).contains(type)
+        let subLayerNonReference = type <= 14 && type % 2 == 0
+        if temporalId == 0 && !leading && !subLayerNonReference {
+            prevTid0POC = poc
+        }
+        return Picture(poc: poc, startsSequence: startsSequence)
+    }
+}
+
+extension H264SPS.BitReader {
+    /// Skips `n` bits; false when that runs past the end.
+    mutating func skip(_ n: Int) -> Bool {
+        var left = n
+        while left > 0 {
+            let step = min(left, 32)
+            guard u(step) != nil else { return false }
+            left -= step
+        }
+        return true
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift b/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift
new file mode 100644
index 000000000..5fdb46267
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift
@@ -0,0 +1,170 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// `DualLayerPictureAlignment` on hand-built access units, so the leading-picture rules run without
+/// the real clips `DualLayerPictureAlignmentTests` needs. Each access unit holds one base-layer
+/// slice and one enhancement-layer slice (wrapped in NAL type 63, as in a profile 7 packet); the
+/// enhancement layer's picture order is chosen to differ from the base layer's, so a restamp shows
+/// as a changed time.
+struct DualLayerPictureAlignmentSyntheticTests {
+
+    typealias B = HEVCSyntheticBitstream
+    typealias T = HEVCSyntheticBitstream.T
+
+    /// One access unit: base slice, then the enhancement layer's slice (and, when `parameterSets`,
+    /// its SPS/PPS, which have no other way in).
+    private static func unit(bl: [UInt8], el: [UInt8], parameterSets: Bool = false) -> [UInt8] {
+        var nals = [bl]
+        if parameterSets {
+            nals.append(B.wrappedEL(B.sps(pocLsbBits: 8)))
+            nals.append(B.wrappedEL(B.pps()))
+        }
+        nals.append(B.wrappedEL(el))
+        return B.accessUnit(nals)
+    }
+
+    private static func slice(_ type: Int, poc: Int) -> [UInt8] {
+        B.slice(type: type, pocLsb: poc & 0xFF, pocLsbBits: 8)
+    }
+
+    private struct Result: Equatable { let pts: Int64; let placed: Bool }
+
+    private static func run(_ a: inout DualLayerPictureAlignment, _ data: [UInt8], pts: Int64) -> Result {
+        let out = data.withUnsafeBufferPointer {
+            a.enhancementPTS($0.baseAddress!, $0.count, framing: .lengthPrefixed(size: 4), pts: pts)
+        }
+        return Result(pts: out, placed: a.lastEnhancementPlaced)
+    }
+
+    private static func seeded() -> DualLayerPictureAlignment {
+        var a = DualLayerPictureAlignment()
+        a.seedBaseParameterSets([B.sps(pocLsbBits: 8), B.pps()])
+        return a
+    }
+
+    // MARK: - After a seek onto a CRA
+
+    /// x265's default open GOP: a seek lands on a CRA followed by RASL pictures that reference what
+    /// came before it. A decoder starting there does not output them. They used to knock the layer's
+    /// offset out ("a picture below the opener's POC"), and with it the alignment, for the rest of the
+    /// session.
+    @Test("a seek onto a CRA with RASL pictures keeps the alignment: the RASL pictures are skipped, the rest still restamp")
+    func craWithRaslAfterSeek() {
+        var a = Self.seeded()
+        a.reset()
+        // Display order: RASL 6, RASL 7, CRA 8, 9, 10. PTS follows display order, one frame = 1000.
+        let u0 = Self.run(&a, Self.unit(bl: Self.slice(T.cra, poc: 8), el: Self.slice(T.cra, poc: 8), parameterSets: true), pts: 2000)
+        #expect(u0 == Result(pts: 2000, placed: true))
+
+        // The RASL pictures are not output: no slot for either layer, and the unit keeps its own time
+        let u1 = Self.run(&a, Self.unit(bl: Self.slice(T.raslN, poc: 6), el: Self.slice(T.raslN, poc: 6)), pts: 0)
+        let u2 = Self.run(&a, Self.unit(bl: Self.slice(T.raslR, poc: 7), el: Self.slice(T.raslR, poc: 7)), pts: 1000)
+        #expect(u1 == Result(pts: 0, placed: false))
+        #expect(u2 == Result(pts: 1000, placed: false))
+
+        // The enhancement layer codes picture 10 before 9 (B-frames); the base layer does not.
+        // Slot of POC p is p - 8 for both layers. EL picture 10 pairs with the base picture of POC 10,
+        // which has not arrived yet: its time is extrapolated from the time per slot (1000).
+        let u3 = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 9), el: Self.slice(T.trailR, poc: 10)), pts: 3000)
+        #expect(u3 == Result(pts: 4000, placed: true), "alignment must survive the RASL pictures")
+        // EL picture 9 pairs with the base picture of POC 9, which came out one unit earlier
+        let u4 = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 10), el: Self.slice(T.trailR, poc: 9)), pts: 4000)
+        #expect(u4 == Result(pts: 3000, placed: true))
+        #expect(a.reorderedUnits == 2)
+    }
+
+    @Test("a CRA in the middle of a stream keeps its RASL pictures in the numbering")
+    func craWithRaslMidStream() {
+        var a = Self.seeded()
+        _ = Self.run(&a, Self.unit(bl: Self.slice(T.idrNLP, poc: 0), el: Self.slice(T.idrNLP, poc: 0), parameterSets: true), pts: 0)
+        for i in 1...4 {
+            _ = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: i), el: Self.slice(T.trailR, poc: i)), pts: Int64(i) * 1000)
+        }
+        // CRA at POC 7 with RASL 5 and 6 (decoded after it, shown before it): all output pictures.
+        // Slots are POC (offset 0). The EL shows 6 where the BL has 5 and vice versa.
+        _ = Self.run(&a, Self.unit(bl: Self.slice(T.cra, poc: 7), el: Self.slice(T.cra, poc: 7)), pts: 7000)
+        let r5 = Self.run(&a, Self.unit(bl: Self.slice(T.raslR, poc: 5), el: Self.slice(T.raslR, poc: 6)), pts: 5000)
+        #expect(r5.placed)
+        // slot 6 is on the unit's own display side of the CRA: the base layer's POC 6 comes next
+        let r6 = Self.run(&a, Self.unit(bl: Self.slice(T.raslR, poc: 6), el: Self.slice(T.raslR, poc: 5)), pts: 6000)
+        #expect(r6 == Result(pts: 5000, placed: true))
+    }
+
+    // MARK: - IDR with RADL
+
+    @Test("RADL pictures, whose POC is below their IDR's, keep the layer's offset instead of discarding it")
+    func idrWithRadl() {
+        var a = Self.seeded()
+        a.reset()
+        // Display order: RADL -2, RADL -1, IDR 0, 1, 2. PTS follows display order.
+        let u0 = Self.run(&a, Self.unit(bl: Self.slice(T.idrWRADL, poc: 0), el: Self.slice(T.idrWRADL, poc: 0), parameterSets: true), pts: 2000)
+        #expect(u0 == Result(pts: 2000, placed: true))
+        let u1 = Self.run(&a, Self.unit(bl: Self.slice(T.radlR, poc: -2), el: Self.slice(T.radlR, poc: -2)), pts: 0)
+        let u2 = Self.run(&a, Self.unit(bl: Self.slice(T.radlR, poc: -1), el: Self.slice(T.radlR, poc: -1)), pts: 1000)
+        #expect(u1 == Result(pts: 0, placed: true), "same frame in both layers: unchanged, but placed by its slot")
+        #expect(u2 == Result(pts: 1000, placed: true))
+
+        let u3 = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 1), el: Self.slice(T.trailR, poc: 2)), pts: 3000)
+        #expect(u3 == Result(pts: 4000, placed: true), "alignment must survive the RADL pictures")
+        let u4 = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 2), el: Self.slice(T.trailR, poc: 1)), pts: 4000)
+        #expect(u4 == Result(pts: 3000, placed: true))
+    }
+
+    // MARK: - Baselines the fix must not change
+
+    @Test("layers with the same GOP keep every unit's own time")
+    func sameGopUnchanged() {
+        var a = Self.seeded()
+        a.reset()
+        _ = Self.run(&a, Self.unit(bl: Self.slice(T.idrNLP, poc: 0), el: Self.slice(T.idrNLP, poc: 0), parameterSets: true), pts: 0)
+        for i in 1...20 {
+            let r = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: i), el: Self.slice(T.trailR, poc: i)), pts: Int64(i) * 1000)
+            #expect(r == Result(pts: Int64(i) * 1000, placed: true))
+        }
+        #expect(a.reorderedUnits == 0)
+    }
+
+    @Test("POC that does not step one per frame is not trusted: the layer falls back to access-unit pairing")
+    func slotFurtherThanDpbIsNotTrusted() {
+        var a = Self.seeded()
+        a.reset()
+        _ = Self.run(&a, Self.unit(bl: Self.slice(T.idrNLP, poc: 0), el: Self.slice(T.idrNLP, poc: 0), parameterSets: true), pts: 0)
+        // The EL jumps 40 pictures ahead in one unit: further than any DPB
+        let r = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 1), el: Self.slice(T.trailR, poc: 41)), pts: 1000)
+        #expect(r == Result(pts: 1000, placed: false))
+    }
+
+    // MARK: - Restamp distance the pairing can absorb
+
+    @Test("an enhancement picture restamped further back than the owner's skew bound is not placed; one within it is")
+    func restampBeyondSkewBoundIsNotPlaced() {
+        var a = Self.seeded()
+        a.maxBackwardRestamp = 2   // DualLayerVideoDecoder.maxLayerSkewFrames (3) - 1
+        a.reset()
+        _ = Self.run(&a, Self.unit(bl: Self.slice(T.idrNLP, poc: 0), el: Self.slice(T.idrNLP, poc: 0), parameterSets: true), pts: 0)
+        for i in 1...4 {
+            _ = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: i), el: Self.slice(T.trailR, poc: i)), pts: Int64(i) * 1000)
+        }
+        // Unit 5, EL shows picture 3: two back, the partner (base picture 3) is still waiting
+        let within = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 5), el: Self.slice(T.trailR, poc: 3)), pts: 5000)
+        #expect(within == Result(pts: 3000, placed: true))
+        #expect(a.unabsorbableRestamps == 0)
+        // Unit 6, EL shows picture 3 again: three back, its partner has been bypassed by then
+        let beyond = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 6), el: Self.slice(T.trailR, poc: 3)), pts: 6000)
+        #expect(beyond == Result(pts: 6000, placed: false))
+        #expect(a.unabsorbableRestamps == 1)
+    }
+
+    @Test("the default bound is the DPB bound: restamps up to 16 back are placed")
+    func defaultBoundAbsorbsDpbDepth() {
+        var a = Self.seeded()
+        a.reset()
+        _ = Self.run(&a, Self.unit(bl: Self.slice(T.idrNLP, poc: 0), el: Self.slice(T.idrNLP, poc: 0), parameterSets: true), pts: 0)
+        for i in 1...20 {
+            _ = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: i), el: Self.slice(T.trailR, poc: i)), pts: Int64(i) * 1000)
+        }
+        let r = Self.run(&a, Self.unit(bl: Self.slice(T.trailR, poc: 21), el: Self.slice(T.trailR, poc: 6)), pts: 21000)
+        #expect(r == Result(pts: 6000, placed: true))
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift b/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
new file mode 100644
index 000000000..dcd78572f
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
@@ -0,0 +1,137 @@
+import Testing
+import Foundation
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// The enhancement-layer restamp on real profile 7 files. One of the test clips codes its EL with B-frames
+/// and its BL without, so 2822 of its access units carry an EL picture of another frame
+/// (counting from the decoded POCs gives 2823: that also counts the last unit, whose EL is a lone IDR
+/// that pairs with its own BL picture but ranks two places off because two EL-less units precede it);
+/// the others share one GOP.
+struct DualLayerPictureAlignmentTests {
+
+    struct Walk {
+        var units: [(pts: Int64, el: Int64?)] = []
+        var reordered = 0
+    }
+
+    static func walk(_ name: String, seekTo seconds: Double? = nil, limit: Int = .max) throws -> Walk {
+        let demuxer = Demuxer()
+        try demuxer.open(url: DoviFelRealFileTests.url(name))
+        defer { demuxer.close() }
+        let index = demuxer.videoStreamIndex
+        let par = try #require(demuxer.stream(at: index)?.pointee.codecpar?.pointee)
+        var alignment = DualLayerPictureAlignment()
+        if let ed = par.extradata, par.extradata_size > 23, ed[0] == 1 {
+            alignment.seedBaseParameterSets(parseHVCCParameterSets(ed, Int(par.extradata_size)))
+        }
+        if let seconds {
+            try #require(demuxer.seek(to: seconds), "seek failed")
+            alignment.reset()
+        }
+        var out = Walk()
+        while out.units.count < limit, let pkt = try demuxer.readPacket() {
+            defer { av_packet_unref(pkt); var o: UnsafeMutablePointer<AVPacket>? = pkt; trackedPacketFree(&o) }
+            guard pkt.pointee.stream_index == Int32(index), let data = pkt.pointee.data else { continue }
+            var hasEL = false
+            A53SEIParser.forEachNAL(data, Int(pkt.pointee.size), .lengthPrefixed(size: 4)) { nal, _ in
+                if (nal[0] >> 1) & 0x3F == 63 { hasEL = true }
+            }
+            let el = alignment.enhancementPTS(data, Int(pkt.pointee.size), framing: .lengthPrefixed(size: 4), pts: pkt.pointee.pts)
+            out.units.append((pkt.pointee.pts, hasEL ? el : nil))
+        }
+        out.reordered = alignment.reorderedUnits
+        return out
+    }
+
+    /// Every restamped EL picture lands on exactly one base-layer picture's time (within 3 ms).
+    static func unmatched(_ w: Walk, base basePTS: [Int64]? = nil) -> (missing: Int, shared: Int) {
+        let base = (basePTS ?? w.units.map(\.pts)).sorted()
+        var used = Set<Int>()
+        var missing = 0, shared = 0
+        for case let el? in w.units.map(\.el) {
+            var lo = 0, hi = base.count
+            while lo < hi { let mid = (lo + hi) / 2; if base[mid] < el { lo = mid + 1 } else { hi = mid } }
+            let near = [lo - 1, lo].filter { base.indices.contains($0) }.min { abs(base[$0] - el) < abs(base[$1] - el) }
+            guard let i = near, abs(base[i] - el) <= 3 else { missing += 1; continue }
+            if !used.insert(i).inserted { shared += 1 }
+        }
+        return (missing, shared)
+    }
+
+    /// The two clips whose layers share one GOP, when present.
+    static let sharedGOPClips = [
+        "fel-clip-b.mkv",
+        "fel-clip-c.mp4",
+    ].filter(DoviFelRealFileTests.available)
+
+    @Test("an EL coded with B-frames over a BL without is paired by POC",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips))
+    func reorderedEnhancementLayer() throws {
+        let name = DoviFelRealFileTests.fixtures[0]
+        let w = try Self.walk(name)
+        #expect(w.reordered == 2822)
+        let moved = w.units.compactMap { u in u.el.map { $0 - u.pts } }.filter { $0 != 0 }
+        #expect(moved.count == 2822)
+        #expect(moved.allSatisfy { abs($0) <= 3 * 42 }, "offsets beyond two frames")
+        let m = Self.unmatched(w)
+        #expect(m.missing == 0 && m.shared == 0, "\(m)")
+    }
+
+    @Test("after a seek the layers realign at the first IRAP",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips))
+    func realignsAfterSeek() throws {
+        let name = DoviFelRealFileTests.fixtures[0]
+        let w = try Self.walk(name, seekTo: 90, limit: 600)
+        #expect(w.reordered > 0)
+        // Until the EL's first sequence-opening IRAP after the seek, each EL picture keeps its own unit's
+        // time (access-unit pairing), and the first restamped pictures can then land on base slots those
+        // units already took (on this clip, two). That stretch is short. From the first restamp on, every EL
+        // picture lands on exactly one base picture. The last few may belong to base frames past the window.
+        let firstRestamp = try #require(w.units.firstIndex { $0.el != nil && $0.el != $0.pts })
+        #expect(firstRestamp < 30, "access-unit pairing lasted \(firstRestamp) units")
+        #expect(w.units.prefix(firstRestamp).allSatisfy { $0.el == nil || $0.el == $0.pts })
+        let realigned = Walk(units: Array(w.units[firstRestamp...].dropLast(3)), reordered: 0)
+        let m = Self.unmatched(realigned, base: w.units.map(\.pts))
+        #expect(m.missing == 0 && m.shared == 0, "\(m)")
+        // That clip's EL opens a sequence roughly every 100 units, so by the second half of the window it has
+        // realigned: from there each stamp is the one an unbroken walk from the start gives the same unit.
+        let linear = Dictionary(try Self.walk(name).units.map { ($0.pts, $0.el) }, uniquingKeysWith: { a, _ in a })
+        let late = w.units.dropFirst(300).dropLast(3)
+        #expect(late.count > 200, "too few units left to compare")
+        let differing = late.filter { linear[$0.pts] != .some($0.el) }.count
+        #expect(differing == 0, "\(differing) of \(late.count) units stamped unlike the linear walk")
+    }
+
+    @Test("layers with one GOP keep their access unit's time",
+          .enabled(if: !DualLayerPictureAlignmentTests.sharedGOPClips.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DualLayerPictureAlignmentTests.sharedGOPClips)
+    func sharedGOPUntouched(name: String) throws {
+        let w = try Self.walk(name)
+        #expect(w.units.contains { $0.el != nil }, "no EL found")
+        #expect(w.reordered == 0)
+        #expect(w.units.allSatisfy { $0.el == nil || $0.el == $0.pts })
+    }
+
+    @Test("extrapolating from crafted timestamps declines instead of trapping")
+    func extremeTimestampsDoNotOverflow() {
+        // Ordinary case still extrapolates: 10 ticks per slot, three slots ahead.
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (0, 0), latest: (4, 40), slot: 7) == 70)
+
+        let big = Int64.max
+        let small = Int64.min + 1
+        // latest.pts - origin.pts overflows.
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (0, small), latest: (4, big), slot: 6) == nil)
+        // The slot distances overflow.
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (Int.min, 0), latest: (Int.max, 10), slot: 0) == nil)
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (0, 0), latest: (1, 10), slot: Int.min) == nil)
+        // The extrapolated offset does not fit an Int64, and neither does the sum.
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (0, 0), latest: (1, big / 2), slot: Int.max) == nil)
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (0, 0), latest: (1, big - 5), slot: 3) == nil)
+        // Time running backwards or standing still has no rate to extrapolate.
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (0, 100), latest: (4, 40), slot: 6) == nil)
+        #expect(DualLayerPictureAlignment.extrapolate(origin: (3, 0), latest: (3, 40), slot: 6) == nil)
+    }
+}
diff --git a/Tests/AetherEngineTests/FrameSideDataRingTests.swift b/Tests/AetherEngineTests/FrameSideDataRingTests.swift
new file mode 100644
index 000000000..4ca82368b
--- /dev/null
+++ b/Tests/AetherEngineTests/FrameSideDataRingTests.swift
@@ -0,0 +1,152 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+@Suite("FrameSideDataRing unit tests")
+struct FrameSideDataRingTests {
+
+    @Test("matches within ±300 ticks")
+    func matchesWithinTolerance() {
+        var ring = FrameSideDataRing()
+        let dmNAL: [UInt8] = [0x7C, 0x01, 0x01]
+        ring.insert(key: 10_000, params: DoviMetalParams(), dmNAL: dmNAL)
+
+        // Exact match
+        #expect(ring.find(key: 10_000) != nil)
+        #expect(ring.find(key: 10_000)?.key == 10_000)
+
+        // Positive boundary: +300 ticks
+        #expect(ring.find(key: 10_300) != nil)
+        #expect(ring.find(key: 10_300)?.key == 10_000)
+
+        // Negative boundary: -300 ticks
+        #expect(ring.find(key: 9_700) != nil)
+        #expect(ring.find(key: 9_700)?.key == 10_000)
+
+        // Intermediate offset: +150 ticks
+        #expect(ring.find(key: 10_150) != nil)
+        #expect(ring.find(key: 10_150)?.key == 10_000)
+    }
+
+    @Test("misses at 301 ticks")
+    func missesAt301() {
+        var ring = FrameSideDataRing()
+        ring.insert(key: 10_000, params: DoviMetalParams(), dmNAL: [0x01])
+
+        // +301 ticks: strictly outside ±300 tolerance
+        #expect(ring.find(key: 10_301) == nil)
+
+        // -301 ticks: strictly outside ±300 tolerance
+        #expect(ring.find(key: 9_699) == nil)
+
+        // Far away
+        #expect(ring.find(key: 20_000) == nil)
+    }
+
+    @Test("overwrites the oldest entry when capacity 32 is exceeded")
+    func overwritesOldest() {
+        var ring = FrameSideDataRing()
+        #expect(FrameSideDataRing.capacity == 32)
+
+        // Insert 32 items, keys 1_000, 2_000, ..., 32_000 (well separated, > 300 apart)
+        for i in 1...32 {
+            ring.insert(key: Int64(i * 1_000), params: DoviMetalParams(), dmNAL: [UInt8(i)])
+        }
+
+        #expect(ring.count == 32)
+        #expect(ring.find(key: 1_000) != nil)
+        #expect(ring.find(key: 32_000) != nil)
+
+        // Insert 33rd item: key 33_000
+        ring.insert(key: 33_000, params: DoviMetalParams(), dmNAL: [33])
+
+        // Total count stays capped at 32
+        #expect(ring.count == 32)
+
+        // The oldest entry (key 1_000) was overwritten and is now gone
+        #expect(ring.find(key: 1_000) == nil)
+
+        // Key 2_000 is now the oldest surviving entry
+        #expect(ring.find(key: 2_000) != nil)
+
+        // Key 33_000 is present
+        #expect(ring.find(key: 33_000) != nil)
+    }
+
+    @Test("selects nearest entry when multiple entries are within ±300 ticks")
+    func selectsNearest() {
+        var ring = FrameSideDataRing()
+        ring.insert(key: 1_000, params: DoviMetalParams(), dmNAL: [1])
+        ring.insert(key: 1_200, params: DoviMetalParams(), dmNAL: [2])
+
+        // Query 1_050: distance to 1_000 is 50, distance to 1_200 is 150 -> selects 1_000
+        #expect(ring.find(key: 1_050)?.key == 1_000)
+
+        // Query 1_180: distance to 1_200 is 20, distance to 1_000 is 180 -> selects 1_200
+        #expect(ring.find(key: 1_180)?.key == 1_200)
+
+        // Query 1_100: exact midpoint (distance 100 to both) -> picks first encountered
+        #expect(ring.find(key: 1_100) != nil)
+    }
+
+    @Test("display metadata and parameters can be removed independently")
+    func independentRemoval() {
+        var ring = FrameSideDataRing()
+        let nal: [UInt8] = [0x7C, 0x01, 0xAA]
+        ring.insert(key: 5_000, params: DoviMetalParams(), dmNAL: nal)
+
+        #expect(ring.dmNALCount == 1)
+        #expect(ring.paramsCount == 1)
+
+        // Remove display metadata first
+        let extractedNAL = ring.removeDisplayMetadata(key: 5_050)
+        #expect(extractedNAL == nal)
+        #expect(ring.dmNALCount == 0)
+        #expect(ring.paramsCount == 1)
+
+        // Second removal of display metadata returns nil
+        #expect(ring.removeDisplayMetadata(key: 5_000) == nil)
+
+        // Parameters are still intact and can be removed
+        let extractedParams = ring.removeParams(key: 4_950)
+        #expect(extractedParams != nil)
+        #expect(ring.paramsCount == 0)
+
+        // Second removal of parameters returns nil
+        #expect(ring.removeParams(key: 5_000) == nil)
+    }
+
+    @Test("inserting for identical key updates in place without consuming a slot")
+    func inPlaceUpdate() {
+        var ring = FrameSideDataRing()
+        ring.insert(key: 5_000, params: DoviMetalParams(), dmNAL: nil)
+        #expect(ring.count == 1)
+        #expect(ring.paramsCount == 1)
+        #expect(ring.dmNALCount == 0)
+
+        let nal: [UInt8] = [0x7C, 0x01, 0xBB]
+        ring.insert(key: 5_000, params: nil, dmNAL: nal)
+        #expect(ring.count == 1)
+        #expect(ring.paramsCount == 1)
+        #expect(ring.dmNALCount == 1)
+
+        #expect(ring.removeDisplayMetadata(key: 5_000) == nal)
+        #expect(ring.removeParams(key: 5_000) != nil)
+    }
+
+    @Test("removeAll clears all entries")
+    func removeAll() {
+        var ring = FrameSideDataRing()
+        ring.insert(key: 1_000, params: DoviMetalParams(), dmNAL: [1])
+        ring.insert(key: 2_000, params: DoviMetalParams(), dmNAL: [2])
+        #expect(!ring.isEmpty)
+        #expect(ring.count == 2)
+
+        ring.removeAll()
+        #expect(ring.isEmpty)
+        #expect(ring.count == 0)
+        #expect(ring.paramsCount == 0)
+        #expect(ring.dmNALCount == 0)
+        #expect(ring.find(key: 1_000) == nil)
+    }
+}
diff --git a/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift b/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift
new file mode 100644
index 000000000..0826c231e
--- /dev/null
+++ b/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift
@@ -0,0 +1,321 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// `HEVCPictureOrderCount` against hand-built parameter sets and slice headers: every expected POC
+/// below is worked out from H.265 §8.3.1 by hand, not by running the reader. (The real-clip tests
+/// in `DualLayerPictureAlignmentTests` need files that are not in the repository.)
+struct HEVCPictureOrderCountTests {
+
+    typealias B = HEVCSyntheticBitstream
+    typealias T = HEVCSyntheticBitstream.T
+
+    /// A counter with SPS 0 / PPS 0 loaded, 4-bit POC LSB (MaxPicOrderCntLsb = 16) unless told otherwise.
+    private static func counter(pocLsbBits: Int = 4, pps: [UInt8]? = nil, sps: [UInt8]? = nil) -> HEVCPictureOrderCount {
+        var c = HEVCPictureOrderCount()
+        c.feedParameterSets([sps ?? B.sps(pocLsbBits: pocLsbBits), pps ?? B.pps()])
+        return c
+    }
+
+    private static func feed(_ c: inout HEVCPictureOrderCount, _ nal: [UInt8]) -> HEVCPictureOrderCount.Picture? {
+        nal.withUnsafeBufferPointer { c.feed($0.baseAddress!, $0.count) }
+    }
+
+    private static func slice(_ type: Int, lsb: Int = 0, tid: Int = 0, bits: Int = 4) -> [UInt8] {
+        B.slice(type: type, temporalId: tid, pocLsb: lsb, pocLsbBits: bits)
+    }
+
+    // MARK: - MSB wrap
+
+    @Test("POC MSB wraps forward: LSB falling by half the range or more adds MaxPicOrderCntLsb")
+    func msbWrapsForward() {
+        var c = Self.counter()
+        #expect(Self.feed(&c, Self.slice(T.idrNLP)) == .init(poc: 0, startsSequence: true))
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 5))?.poc == 5)
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 10))?.poc == 10)
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 15))?.poc == 15)
+        // prevLsb 15, lsb 4: 15 - 4 = 11 >= 8, so MSB += 16 -> 16 + 4
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 4))?.poc == 20)
+        // And a second wrap
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 9))?.poc == 25)
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 14))?.poc == 30)
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 3))?.poc == 35)
+    }
+
+    @Test("POC MSB wraps backward: LSB rising by more than half the range subtracts MaxPicOrderCntLsb")
+    func msbWrapsBackward() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 6))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 12))
+        // prevTid0 = 12 (lsb 12, msb 0); lsb 4 -> 12 - 4 = 8 >= 8: wraps forward to 20
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 4))?.poc == 20)
+        // prevTid0 = 20 (lsb 4, msb 16); lsb 15: 15 - 4 = 11 > 8 -> MSB = 16 - 16 = 0 -> 15 (a picture
+        // displayed before the one at 20, as a B-frame under a wrap would be)
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 15))?.poc == 15)
+    }
+
+    @Test("a half-range step is a wrap one way and not the other (the spec's strict and non-strict comparisons)")
+    func halfRangeBoundary() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 8))
+        // lsb 0, prev 8: prev - lsb = 8 >= 8, wraps forward -> 16
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 0))?.poc == 16)
+        // lsb 8, prev 0 (of 16): lsb - prev = 8, not > 8, so no wrap -> 24
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 8))?.poc == 24)
+    }
+
+    // MARK: - Sequence starts
+
+    @Test("IDR and BLA start a sequence at MSB 0; BLA keeps its LSB")
+    func idrAndBlaStartSequences() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrWRADL))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 7))
+        let bla = Self.feed(&c, Self.slice(T.blaWLP, lsb: 9))
+        #expect(bla == .init(poc: 9, startsSequence: true))
+        // POC numbering restarts: the next picture is relative to the BLA, not to the IDR's sequence
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 10))?.poc == 10)
+    }
+
+    @Test("a CRA in the middle of a sequence continues the numbering; after reset() it starts one (CRA handled as BLA)")
+    func craAsBlaAfterReset() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 7))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 15))
+        // Mid-sequence CRA: NoRaslOutputFlag = 0, POC continues across the wrap (16 + 3)
+        #expect(Self.feed(&c, Self.slice(T.cra, lsb: 3)) == .init(poc: 19, startsSequence: false))
+
+        c.reset()
+        // Pictures before the first IRAP after a seek are not decodable: no POC
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 4)) == nil)
+        // The CRA opens a sequence (HandleCraAsBlaFlag): MSB 0, so POC = LSB
+        #expect(Self.feed(&c, Self.slice(T.cra, lsb: 3)) == .init(poc: 3, startsSequence: true))
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 5))?.poc == 5)
+    }
+
+    @Test("end of sequence and end of bitstream NALs make the next IRAP a sequence start and hide what precedes it")
+    func endOfSequenceAndBitstream() {
+        for eosType in [T.eos, T.eob] {
+            var c = Self.counter()
+            _ = Self.feed(&c, Self.slice(T.idrNLP))
+            _ = Self.feed(&c, Self.slice(T.trailR, lsb: 5))
+            #expect(Self.feed(&c, B.nal(type: eosType, rbsp: [0x80])) == nil)
+            #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 6)) == nil, "no picture is decodable between the end of sequence and the next IRAP")
+            // A CRA after the end of sequence has NoRaslOutputFlag = 1
+            #expect(Self.feed(&c, Self.slice(T.cra, lsb: 11)) == .init(poc: 11, startsSequence: true))
+            #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 12))?.poc == 12)
+        }
+    }
+
+    // MARK: - prevTid0Pic
+
+    /// prevTid0Pic is the previous TemporalId-0 picture that is not RASL, RADL or a sub-layer
+    /// non-reference picture. Each excluded kind is fed with an LSB that would change the result
+    /// if it had been taken as the reference.
+    @Test("RASL, RADL, sub-layer non-reference pictures and TemporalId > 0 are not prevTid0Pic",
+          arguments: [T.trailN, T.tsaN, T.radlN, T.radlR, T.raslN, T.raslR])
+    func excludedFromPrevTid0(type: Int) {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 2))?.poc == 2)          // prevTid0 = 2
+        // The excluded picture: POC 9 relative to prevTid0 = 2 (9 - 2 = 7, no wrap)
+        #expect(Self.feed(&c, Self.slice(type, lsb: 9))?.poc == 9)
+        // If it had become prevTid0 (9), lsb 14 would be poc 14. Relative to 2 it is 14 - 2 = 12 > 8,
+        // a backward wrap: 14 - 16 = -2.
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 14))?.poc == -2)
+    }
+
+    @Test("a picture with TemporalId > 0 is not prevTid0Pic")
+    func higherTemporalLayerExcluded() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 2))
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 9, tid: 1))?.poc == 9)
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 14))?.poc == -2)
+    }
+
+    @Test("a reference picture at TemporalId 0 is prevTid0Pic")
+    func referencePictureIsPrevTid0() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 2))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 9))
+        // prevTid0 = 9: lsb 14 is 14 - 9 = 5 ahead, no wrap
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 14))?.poc == 14)
+    }
+
+    // MARK: - Leading pictures after a sequence-opening CRA
+
+    @Test("RASL pictures of a CRA that opens a sequence get no POC; RADL and trailing pictures do")
+    func raslSkippedAfterOpeningCra() {
+        for rasl in [T.raslN, T.raslR] {
+            var c = Self.counter()
+            c.reset()
+            #expect(Self.feed(&c, Self.slice(T.cra, lsb: 8))?.startsSequence == true)
+            #expect(Self.feed(&c, Self.slice(rasl, lsb: 6)) == nil, "RASL of a CRA with NoRaslOutputFlag = 1 is not output")
+            #expect(Self.feed(&c, Self.slice(T.radlR, lsb: 7))?.poc == 7, "RADL is decodable and output before the CRA")
+            #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 9))?.poc == 9)
+        }
+    }
+
+    @Test("RASL pictures of a CRA in the middle of a sequence are ordinary pictures")
+    func raslKeptAfterMidStreamCra() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.trailR, lsb: 4))
+        #expect(Self.feed(&c, Self.slice(T.cra, lsb: 8))?.startsSequence == false)
+        #expect(Self.feed(&c, Self.slice(T.raslR, lsb: 6))?.poc == 6)
+    }
+
+    @Test("an IDR clears the RASL skip a previous CRA set")
+    func idrClearsRaslSkip() {
+        var c = Self.counter()
+        c.reset()
+        _ = Self.feed(&c, Self.slice(T.cra, lsb: 8))
+        _ = Self.feed(&c, Self.slice(T.idrWRADL))
+        // Not a legal stream (an IDR has no RASL), but the skip must not outlive its IRAP
+        #expect(Self.feed(&c, Self.slice(T.raslN, lsb: 1))?.poc == 1)
+    }
+
+    @Test("the RASL skip ends at the next IRAP; BLA also opens it")
+    func blaSkipsRasl() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        _ = Self.feed(&c, Self.slice(T.blaWLP, lsb: 8))
+        #expect(Self.feed(&c, Self.slice(T.raslN, lsb: 6)) == nil)
+        _ = Self.feed(&c, Self.slice(T.cra, lsb: 12))      // mid-sequence CRA: RASL are output again
+        #expect(Self.feed(&c, Self.slice(T.raslN, lsb: 10))?.poc == 10)
+    }
+
+    // MARK: - Header syntax
+
+    @Test("emulation prevention bytes inside the parameter sets and the slice header are removed before parsing")
+    func emulationPrevention() {
+        // The SPS carries 6 zero bytes of constraint flags, which always needs escaping
+        let sps = B.sps(pocLsbBits: 16)
+        #expect(sps.contains(0x03))
+        #expect(Array(sps).windows3.contains { $0 == [0, 0, 3] })
+        // Slice: first_slice 1, no_output 0, pps ue(0) = 1, two extra bits 00, slice_type ue(2) = 011
+        // makes byte 0 = 10100011; a 16-bit POC LSB of 0 then gives two zero bytes, and the following
+        // 00000001 byte makes the sequence 00 00 01, which must be escaped to 00 00 03 01.
+        let pps = B.pps(extraSliceHeaderBits: 2)
+        let cra = B.slice(type: T.cra, extraBits: 2, pocLsb: 0, pocLsbBits: 16, afterPOC: (1, 8))
+        #expect(cra.windows3.contains { $0 == [0, 0, 3] }, "the slice must actually contain an escape")
+        var c = HEVCPictureOrderCount()
+        c.feedParameterSets([sps, pps])
+        c.reset()
+        #expect(Self.feed(&c, cra) == .init(poc: 0, startsSequence: true))
+        let trail = B.slice(type: T.trailR, extraBits: 2, pocLsb: 0x0003, pocLsbBits: 16)
+        #expect(Self.feed(&c, trail)?.poc == 3)
+    }
+
+    @Test("num_extra_slice_header_bits shifts where slice_type and the POC LSB sit")
+    func extraSliceHeaderBits() {
+        for extra in [0, 1, 3, 7] {
+            var c = HEVCPictureOrderCount()
+            c.feedParameterSets([B.sps(pocLsbBits: 6), B.pps(extraSliceHeaderBits: extra)])
+            _ = Self.feed(&c, B.slice(type: T.idrNLP, extraBits: extra, extraBitsValue: (1 << extra) - 1, pocLsbBits: 6))
+            let p = Self.feed(&c, B.slice(type: T.trailR, extraBits: extra, extraBitsValue: (1 << extra) - 1,
+                                          pocLsb: 20, pocLsbBits: 6))
+            #expect(p?.poc == 20, "extra bits = \(extra)")
+        }
+    }
+
+    @Test("pic_output_flag is read when output_flag_present_flag is set, and only then")
+    func outputFlagPresent() {
+        var with = HEVCPictureOrderCount()
+        with.feedParameterSets([B.sps(pocLsbBits: 8), B.pps(outputFlagPresent: true)])
+        _ = Self.feed(&with, B.slice(type: T.idrNLP, outputFlag: true, pocLsbBits: 8))
+        // A picture with pic_output_flag = 0 still has a POC, and still moves prevTid0Pic
+        #expect(Self.feed(&with, B.slice(type: T.trailR, outputFlag: false, pocLsb: 77, pocLsbBits: 8))?.poc == 77)
+        #expect(Self.feed(&with, B.slice(type: T.trailR, outputFlag: true, pocLsb: 78, pocLsbBits: 8))?.poc == 78)
+
+        // Without the flag in the PPS, a slice that does not carry it parses the same LSB
+        var without = HEVCPictureOrderCount()
+        without.feedParameterSets([B.sps(pocLsbBits: 8), B.pps(outputFlagPresent: false)])
+        _ = Self.feed(&without, B.slice(type: T.idrNLP, pocLsbBits: 8))
+        #expect(Self.feed(&without, B.slice(type: T.trailR, pocLsb: 77, pocLsbBits: 8))?.poc == 77)
+    }
+
+    @Test("colour_plane_id is read when separate_colour_plane_flag is set (4:4:4 coded as three planes)")
+    func separateColourPlane() {
+        var c = HEVCPictureOrderCount()
+        c.feedParameterSets([B.sps(pocLsbBits: 8, chromaFormatIdc: 3, separateColourPlane: true), B.pps()])
+        _ = Self.feed(&c, B.slice(type: T.idrNLP, colourPlane: 0, pocLsbBits: 8))
+        #expect(Self.feed(&c, B.slice(type: T.trailR, colourPlane: 1, pocLsb: 41, pocLsbBits: 8))?.poc == 41)
+
+        // 4:4:4 with the planes together has no colour_plane_id
+        var joint = HEVCPictureOrderCount()
+        joint.feedParameterSets([B.sps(pocLsbBits: 8, chromaFormatIdc: 3, separateColourPlane: false), B.pps()])
+        _ = Self.feed(&joint, B.slice(type: T.idrNLP, pocLsbBits: 8))
+        #expect(Self.feed(&joint, B.slice(type: T.trailR, pocLsb: 41, pocLsbBits: 8))?.poc == 41)
+    }
+
+    @Test("sub-layer profile/level flags in the SPS are skipped correctly")
+    func spsWithSubLayers() {
+        var c = HEVCPictureOrderCount()
+        c.feedParameterSets([B.sps(pocLsbBits: 9, subLayers: 3), B.pps()])
+        _ = Self.feed(&c, B.slice(type: T.idrNLP, pocLsbBits: 9))
+        #expect(Self.feed(&c, B.slice(type: T.trailR, pocLsb: 200, pocLsbBits: 9))?.poc == 200)
+    }
+
+    // MARK: - Missing or unusable input
+
+    @Test("a slice whose PPS or SPS has not been seen has no POC; it gets one once they arrive")
+    func missingParameterSets() {
+        var c = HEVCPictureOrderCount()
+        let idr = B.slice(type: T.idrNLP, pocLsbBits: 8)
+        #expect(Self.feed(&c, idr) == nil, "no PPS, no SPS")
+        _ = Self.feed(&c, B.pps(id: 0, spsID: 0))
+        #expect(Self.feed(&c, idr) == nil, "PPS refers to an SPS that has not been seen")
+        _ = Self.feed(&c, B.sps(id: 0, pocLsbBits: 8))
+        #expect(Self.feed(&c, B.slice(type: T.idrNLP, ppsID: 5, pocLsbBits: 8)) == nil, "PPS id 5 was never sent")
+        #expect(Self.feed(&c, idr) == .init(poc: 0, startsSequence: true))
+    }
+
+    @Test("a picture that is not the first slice segment is ignored and does not disturb state")
+    func nonFirstSliceIgnored() {
+        var c = Self.counter()
+        _ = Self.feed(&c, Self.slice(T.idrNLP))
+        #expect(Self.feed(&c, B.slice(type: T.trailR, firstSliceSegment: false, pocLsb: 9, pocLsbBits: 4)) == nil)
+        // prevTid0 is still 0: lsb 9 is 9 > 8 ahead, a backward wrap -> -7. Had the second slice
+        // been taken as a picture (prevTid0 = 9) it would read 9 -> 9.
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 9))?.poc == -7)
+    }
+
+    @Test("pictures before the first IRAP, truncated headers and junk NALs answer nil")
+    func rejectsWhatItCannotFollow() {
+        var c = Self.counter()
+        #expect(Self.feed(&c, Self.slice(T.trailR, lsb: 3)) == nil, "no IRAP yet")
+        #expect(Self.feed(&c, Array(Self.slice(T.idrNLP).prefix(2))) == nil, "a bare NAL header")
+        #expect(Self.feed(&c, [0x02]) == nil)
+        #expect(Self.feed(&c, B.nal(type: 39, rbsp: [0x00, 0x01])) == nil, "an SEI is not a picture")
+        #expect(Self.feed(&c, B.nal(type: 32, rbsp: [0x0C, 0x01])) == nil, "nor is a VPS")
+        // The decoder still works afterwards
+        #expect(Self.feed(&c, Self.slice(T.idrNLP))?.poc == 0)
+        // A slice header cut off inside the POC LSB, after an IRAP so that the truncation is the only
+        // reason to answer nil: the same header complete is a picture
+        let trail = Self.slice(T.trailR, lsb: 5)
+        #expect(Self.feed(&c, Array(trail.prefix(3))) == nil)
+        #expect(Self.feed(&c, trail)?.poc == 5)
+    }
+
+    @Test("an SPS with an out-of-range POC LSB width is not stored")
+    func rejectsOversizedLsbWidth() {
+        var c = HEVCPictureOrderCount()
+        // log2_max_pic_order_cnt_lsb_minus4 = 13 (> 12) is outside what the spec allows
+        c.feedParameterSets([B.sps(pocLsbBits: 17), B.pps()])
+        #expect(Self.feed(&c, B.slice(type: T.idrNLP, pocLsbBits: 17)) == nil)
+    }
+}
+
+private extension Array where Element == UInt8 {
+    /// Every run of three consecutive bytes.
+    var windows3: [[UInt8]] {
+        guard count >= 3 else { return [] }
+        return (0...(count - 3)).map { Array(self[$0..<$0 + 3]) }
+    }
+}
diff --git a/Tests/AetherEngineTests/HEVCSyntheticBitstream.swift b/Tests/AetherEngineTests/HEVCSyntheticBitstream.swift
new file mode 100644
index 000000000..3e0e8fffb
--- /dev/null
+++ b/Tests/AetherEngineTests/HEVCSyntheticBitstream.swift
@@ -0,0 +1,127 @@
+import Foundation
+@testable import AetherEngine
+
+/// Hand-built HEVC parameter sets and slice segment headers, just deep enough for
+/// `HEVCPictureOrderCount` and `DualLayerPictureAlignment` to read: no picture data, no real
+/// profile. Every field the reader consumes is written from a named argument, so a test states
+/// the stream it means (POC LSB width, extra slice header bits, output flag, colour planes) and
+/// the expected POC follows from the spec, not from running the code under test.
+enum HEVCSyntheticBitstream {
+
+    /// MSB-first bit writer with Exp-Golomb.
+    struct BitWriter {
+        private(set) var bits: [UInt8] = []
+
+        mutating func u(_ value: Int, _ count: Int) {
+            for i in stride(from: count - 1, through: 0, by: -1) { bits.append(UInt8((value >> i) & 1)) }
+        }
+        mutating func flag(_ on: Bool) { bits.append(on ? 1 : 0) }
+        mutating func ue(_ value: Int) {
+            let v = value + 1
+            let width = Int.bitWidth - v.leadingZeroBitCount
+            u(0, width - 1)
+            u(v, width)
+        }
+        /// The bytes written so far, padded with a stop bit and zeros to a byte boundary
+        /// (rbsp_trailing_bits), followed by `tail` verbatim.
+        func rbsp(tail: [UInt8] = []) -> [UInt8] {
+            var all = bits
+            all.append(1)
+            while all.count % 8 != 0 { all.append(0) }
+            var out: [UInt8] = []
+            for i in stride(from: 0, to: all.count, by: 8) {
+                out.append(all[i..<i + 8].reduce(0) { ($0 << 1) | $1 })
+            }
+            return out + tail
+        }
+    }
+
+    /// Inserts emulation prevention bytes (00 00 {00..03} becomes 00 00 03 {..}).
+    static func escape(_ rbsp: [UInt8]) -> [UInt8] {
+        var out: [UInt8] = []
+        var zeros = 0
+        for b in rbsp {
+            if zeros >= 2 && b <= 3 { out.append(3); zeros = 0 }
+            out.append(b)
+            zeros = b == 0 ? zeros + 1 : 0
+        }
+        return out
+    }
+
+    /// NAL unit: 2-byte header, then the escaped payload.
+    static func nal(type: Int, temporalId: Int = 0, rbsp: [UInt8]) -> [UInt8] {
+        [UInt8(type << 1), UInt8(temporalId + 1)] + escape(rbsp)
+    }
+
+    static func sps(id: Int = 0, pocLsbBits: Int = 8, chromaFormatIdc: Int = 1,
+                    separateColourPlane: Bool = false, subLayers: Int = 1) -> [UInt8] {
+        var w = BitWriter()
+        w.u(0, 4)                         // sps_video_parameter_set_id
+        w.u(subLayers - 1, 3)             // sps_max_sub_layers_minus1
+        w.flag(true)                      // temporal_id_nesting
+        w.u(0, 2); w.flag(false); w.u(2, 5)   // profile_space, tier, profile_idc (Main 10)
+        w.u(0x20000000, 32)               // compatibility flags
+        w.u(0, 48)                        // constraint flags: a long run of zero bytes, which is what
+                                          // makes emulation prevention show up in every SPS
+        w.u(120, 8)                       // general_level_idc
+        for _ in 0..<(subLayers - 1) { w.flag(false); w.flag(false) }   // sub_layer profile/level absent
+        if subLayers > 1 { w.u(0, 2 * (8 - (subLayers - 1))) }
+        w.ue(id)
+        w.ue(chromaFormatIdc)
+        if chromaFormatIdc == 3 { w.flag(separateColourPlane) }
+        w.ue(3840); w.ue(2160)
+        w.flag(false)                     // conformance_window_flag
+        w.ue(2); w.ue(2)                  // bit depths (10)
+        w.ue(pocLsbBits - 4)              // log2_max_pic_order_cnt_lsb_minus4
+        return nal(type: 33, rbsp: w.rbsp(tail: [0x40]))
+    }
+
+    static func pps(id: Int = 0, spsID: Int = 0, outputFlagPresent: Bool = false,
+                    extraSliceHeaderBits: Int = 0) -> [UInt8] {
+        var w = BitWriter()
+        w.ue(id); w.ue(spsID)
+        w.flag(false)                     // dependent_slice_segments_enabled_flag
+        w.flag(outputFlagPresent)
+        w.u(extraSliceHeaderBits, 3)
+        return nal(type: 34, rbsp: w.rbsp(tail: [0x40]))
+    }
+
+    /// First (or later) slice segment of a picture. `pocLsb` is ignored for IDR (19, 20), which
+    /// carry none. `tail` stands in for the rest of the header and the slice data.
+    static func slice(type: Int, temporalId: Int = 0, firstSliceSegment: Bool = true,
+                      ppsID: Int = 0, extraBits: Int = 0, extraBitsValue: Int = 0,
+                      outputFlag: Bool? = nil, colourPlane: Int? = nil,
+                      pocLsb: Int = 0, pocLsbBits: Int = 8, afterPOC: (value: Int, bits: Int)? = nil,
+                      tail: [UInt8] = [0xAA]) -> [UInt8] {
+        var w = BitWriter()
+        w.flag(firstSliceSegment)
+        if (16...23).contains(type) { w.flag(false) }     // no_output_of_prior_pics_flag
+        w.ue(ppsID)
+        w.u(extraBitsValue, extraBits)                    // slice_reserved_flag[]
+        w.ue(2)                                           // slice_type
+        if let outputFlag { w.flag(outputFlag) }
+        if let colourPlane { w.u(colourPlane, 2) }
+        if type != 19 && type != 20 { w.u(pocLsb, pocLsbBits) }
+        if let afterPOC { w.u(afterPOC.value, afterPOC.bits) }   // whatever header field follows
+        return nal(type: type, temporalId: temporalId, rbsp: w.rbsp(tail: tail))
+    }
+
+    /// NAL type numbers used by the tests.
+    enum T {
+        static let trailN = 0, trailR = 1, tsaN = 2, radlN = 6, radlR = 7, raslN = 8, raslR = 9
+        static let blaWLP = 16, blaWRADL = 17, blaNLP = 18, idrWRADL = 19, idrNLP = 20, cra = 21
+        static let eos = 36, eob = 37
+    }
+
+    // MARK: - Access units for DualLayerPictureAlignment
+
+    /// Length-prefixed (4 bytes) access unit.
+    static func accessUnit(_ nals: [[UInt8]]) -> [UInt8] {
+        nals.flatMap { n in
+            [UInt8((n.count >> 24) & 0xFF), UInt8((n.count >> 16) & 0xFF), UInt8((n.count >> 8) & 0xFF), UInt8(n.count & 0xFF)] + n
+        }
+    }
+
+    /// An enhancement-layer NAL as it rides in the base-layer packet: wrapped in NAL type 63.
+    static func wrappedEL(_ inner: [UInt8]) -> [UInt8] { [UInt8(63 << 1), 0x01] + inner }
+}
diff --git a/Tests/AetherEngineTests/OrderedDeliveryTests.swift b/Tests/AetherEngineTests/OrderedDeliveryTests.swift
new file mode 100644
index 000000000..03958ebc5
--- /dev/null
+++ b/Tests/AetherEngineTests/OrderedDeliveryTests.swift
@@ -0,0 +1,247 @@
+import Testing
+import CoreMedia
+import CoreVideo
+import Foundation
+@testable import AetherEngine
+
+/// `OrderedDelivery` is one serial `.userInteractive` queue,
+/// owned by the decoder, that both composed and bypassed frames go through on
+/// their way to `onFrame`. These tests drive it directly — no decoder, no
+/// GPU — to pin its three load-bearing guarantees: ticket order survives any
+/// arrival order, an epoch bump (`reset`) is what makes flush/close's "nothing
+/// from before this returns after" invariant (I3) hold, and a ticket that
+/// never arrives costs exactly the one frame at the stall-guard threshold,
+/// not the rest of the session.
+@Suite(.serialized, .timeLimit(.minutes(1)))
+struct OrderedDeliveryTests {
+
+    private static func makeBuffer() -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, 4, 4,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [:] as CFDictionary, &out)
+        return status == kCVReturnSuccess ? out : nil
+    }
+
+    /// Encodes an identifying number into a frame's PTS so a test can tell
+    /// which ticket a delivery corresponds to without `DeliveredFrame`
+    /// carrying the ticket itself (it deliberately does not — `emit` has no
+    /// use for it).
+    private static func frame(_ buffer: CVPixelBuffer, tag: Int64) -> DeliveredFrame {
+        DeliveredFrame(buffer: SendableBuffer(value: buffer), pts: CMTime(value: tag, timescale: 1), hdr10Data: nil, dmNAL: nil)
+    }
+
+    private final class Recorder: @unchecked Sendable {
+        private let lock = NSLock()
+        private var tags: [Int64] = []
+        func record(_ pts: CMTime) { lock.lock(); tags.append(pts.value); lock.unlock() }
+        var snapshot: [Int64] { lock.lock(); defer { lock.unlock() }; return tags }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return tags.count }
+    }
+
+    @Test("frames reach onFrame in ticket order no matter what order fulfil is called in")
+    func deliversInTicketOrder() async throws {
+        let buffer = try #require(Self.makeBuffer())
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.order")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+
+        // Deliberately out of arrival order — this is what a composition that
+        // finishes on the GPU out of order, or a bypass that races ahead of a
+        // slower composition, looks like from `fulfil`'s point of view.
+        for ticket in [3, 1, 0, 4, 2] {
+            delivery.fulfil(ticket: UInt64(ticket), epoch: 0, Self.frame(buffer, tag: Int64(ticket)))
+        }
+
+        try await waitFor { recorder.count == 5 }
+        #expect(recorder.snapshot == [0, 1, 2, 3, 4])
+    }
+
+    @Test("bypass-shaped and compose-shaped fulfil calls interleave through the same order, indistinguishably")
+    func bypassAndComposeShareOneOrder() async throws {
+        let buffer = try #require(Self.makeBuffer())
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.mixed")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+
+        // A "bypass" is just a `fulfil` called synchronously on the pairing
+        // thread; a "compose" is the same call from Metal's completion queue,
+        // later. `OrderedDelivery` has no notion of which is which, so there is
+        // one ordering mechanism, not two.
+        delivery.fulfil(ticket: 0, epoch: 0, Self.frame(buffer, tag: 0)) // bypass, ticket 0
+        delivery.fulfil(ticket: 2, epoch: 0, Self.frame(buffer, tag: 2)) // bypass, ticket 2, arrives immediately
+        // Both have been handled before the "compose" for ticket 1 finishes: ticket 2 is pending.
+        delivery.barrier()
+        let lateFrame = Self.frame(buffer, tag: 1) // built outside the closure: `DeliveredFrame` is Sendable, `CVPixelBuffer` is not
+        // A dedicated thread, not the global pool: blocking tests elsewhere in a full run can
+        // starve GCD's workers for seconds, which made this test time out rather than reorder.
+        Thread.detachNewThread {
+            // "Compose" for ticket 1 finishes late, off a different thread.
+            delivery.fulfil(ticket: 1, epoch: 0, lateFrame)
+        }
+
+        try await waitFor { recorder.count == 3 }
+        #expect(recorder.snapshot == [0, 1, 2], "ticket 2 must wait behind the late ticket 1, whichever path produced it")
+    }
+
+    @Test("a ticket that is never fulfilled costs exactly one frame (the stall guard)")
+    func stallGuardCostsExactlyOneFrame() async throws {
+        let buffer = try #require(Self.makeBuffer())
+        // Threshold = maxFramesInFlight + maxLayerSkew + 2 = 3 + 3 + 2 = 8,
+        // matching production (`DoviFelComposer.maxFramesInFlight`,
+        // `DualLayerVideoDecoder.maxLayerSkewFrames`).
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.stall")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+
+        // Ticket 0 is never fulfilled — the composition it belonged to failed
+        // to call back at all, the one failure mode a ticket, rather than a
+        // bypass, cannot self-report. Tickets 1...12 arrive normally.
+        for ticket in 1...12 {
+            delivery.fulfil(ticket: UInt64(ticket), epoch: 0, Self.frame(buffer, tag: Int64(ticket)))
+        }
+
+        try await waitFor { recorder.count == 12 }
+        #expect(recorder.count == 12, "every ticket but the missing one must still be delivered")
+        #expect(recorder.snapshot == Array(1...12), "delivery order is unaffected beyond the one skipped ticket")
+    }
+
+    @Test("reset drops a stale-epoch delivery that is already pending when reset runs")
+    func resetDropsStaleEpoch() async throws {
+        let buffer = try #require(Self.makeBuffer())
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.epoch")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+
+        // Ticket 0 never arrives (as if its base layer were still waiting for
+        // a partner when a seek lands), so tickets 1 and 2 — tagged with the
+        // pre-seek epoch — sit pending behind it.
+        delivery.fulfil(ticket: 1, epoch: 0, Self.frame(buffer, tag: 1))
+        delivery.fulfil(ticket: 2, epoch: 0, Self.frame(buffer, tag: 2))
+        delivery.barrier() // both are now in `pending`
+
+        // The seek: bump the epoch and fast-forward past every ticket issued
+        // so far. `reset` is `queue.sync`, so this line does not return until
+        // both `fulfil` calls above have already run to completion (they
+        // deliver nothing, since ticket 0 is still missing and below the new
+        // stall threshold) — this is invariant I3's mechanism, exercised
+        // directly rather than through `DualLayerVideoDecoder.flush()`.
+        delivery.reset(epoch: 1, nextTicket: 10)
+
+        // A composition for the OLD epoch retiring late — e.g. a GPU command
+        // buffer that was already committed before the seek — must never
+        // reach `onFrame`, even though its ticket number (11) is not below
+        // the new base ticket: only the epoch tells it from a live one.
+        delivery.fulfil(ticket: 11, epoch: 0, Self.frame(buffer, tag: 11))
+        // A fresh, post-seek ticket at `nextTicket` with the NEW epoch must
+        // deliver normally. Ticket 11 would follow it if the epoch were ignored.
+        delivery.fulfil(ticket: 10, epoch: 1, Self.frame(buffer, tag: 10))
+
+        delivery.barrier()
+        #expect(recorder.snapshot == [10], "only the post-reset ticket may reach onFrame; tickets 1 and 2 predate the reset and ticket 11 carries the old epoch")
+    }
+
+    @Test("a new-epoch ticket fulfilled before reset is (visibly) delivered is not lost")
+    func newEpochTicketFulfilledBeforeResetIsDeliveredIsNotLost() async throws {
+        // The sequence `fulfil(0...4, e0)`, `fulfil(5, e1)`, `reset(e1, 5)`,
+        // `fulfil(6...13, e1)` loses ticket 5 and stalls 6...13 until the
+        // stall guard skips it if `flush()` calls `reset` (synchronously,
+        // `queue.sync`) only after a concurrent caller could already have
+        // reached `fulfil` for the new epoch.
+        //
+        // `DualLayerVideoDecoder.flush()`/`close()` (see the comment atop
+        // `flush()`) therefore call `resetAsync` — the non-blocking
+        // half of `reset` — from INSIDE the same lock that makes issuing a
+        // new-epoch ticket possible in the first place, so the reset is
+        // always enqueued before any ticket that could race it. This test
+        // drives that exact ordering directly against `OrderedDelivery`,
+        // with no decoder involved: `resetAsync` is called first, and
+        // `fulfil(5, epoch: 1, ...)` is called immediately after — before
+        // anything has waited for `resetAsync`'s block to actually run, i.e.
+        // "fulfilled before reset is delivered" — and ticket 5 must still
+        // arrive, with nothing behind it held back either.
+        //
+        // Tickets 0...4 (epoch 0) are expected to drain and reach `onFrame`
+        // normally before any of this runs — they were enqueued strictly
+        // before `resetAsync`, so FIFO order alone (with no epoch mismatch
+        // to drop them) delivers them first. The property under
+        // test is only about ticket 5 onward.
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.post-flush-ticket")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+        let buffer = try #require(Self.makeBuffer())
+
+        for ticket in 0...4 {
+            delivery.fulfil(ticket: UInt64(ticket), epoch: 0, Self.frame(buffer, tag: Int64(ticket)))
+        }
+        delivery.resetAsync(epoch: 1, nextTicket: 5)
+        delivery.fulfil(ticket: 5, epoch: 1, Self.frame(buffer, tag: 5))
+        for ticket in 6...13 {
+            delivery.fulfil(ticket: UInt64(ticket), epoch: 1, Self.frame(buffer, tag: Int64(ticket)))
+        }
+
+        try await waitFor { recorder.count == 14 }
+        #expect(recorder.snapshot == Array(0...13), "ticket 5 must not be lost, and 6...13 must not be held back waiting for it")
+    }
+
+    @Test("exactly the stall threshold's worth of pending frames does not trigger the stall guard")
+    func stallGuardBoundaryDoesNotSkipAtExactlyTheThreshold() async throws {
+        let buffer = try #require(Self.makeBuffer())
+        // Threshold = maxFramesInFlight + maxLayerSkew + 2 = 3 + 3 + 2 = 8.
+        // `drainReady`'s guard is `pending.count > stallThreshold` (strictly
+        // greater), so exactly 8 pending behind the missing head-of-line
+        // ticket must not be enough to skip it.
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.stall-boundary-no-skip")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+
+        for ticket in 1...8 {
+            delivery.fulfil(ticket: UInt64(ticket), epoch: 0, Self.frame(buffer, tag: Int64(ticket)))
+        }
+        // Every arrival has been handled, so ticket 0 would already have been (wrongly) skipped
+        // while draining 1...8; there is no ninth arrival to trigger it.
+        delivery.barrier()
+        #expect(recorder.count == 0, "nothing may deliver while ticket 0, the head of the line, is still missing")
+
+        delivery.fulfil(ticket: 0, epoch: 0, Self.frame(buffer, tag: 0))
+        try await waitFor { recorder.count == 9 }
+        #expect(recorder.snapshot == Array(0...8), "ticket 0 must not have been skipped at exactly 8 pending behind it")
+    }
+
+    @Test("a ticket that arrives late, but before the stall threshold is exceeded, still delivers in order")
+    func lateTicketWithinThresholdDeliversInOrder() async throws {
+        let buffer = try #require(Self.makeBuffer())
+        let delivery = OrderedDelivery(maxFramesInFlight: 3, maxLayerSkew: 3, label: "test.ordered-delivery.late-ticket-in-order")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+
+        // 7 pending behind the missing ticket 0 — one short of the 8-pending
+        // stall-guard threshold — then ticket 0 arrives late, well inside
+        // the window the guard tolerates.
+        for ticket in 1...7 {
+            delivery.fulfil(ticket: UInt64(ticket), epoch: 0, Self.frame(buffer, tag: Int64(ticket)))
+        }
+        delivery.barrier()
+        delivery.fulfil(ticket: 0, epoch: 0, Self.frame(buffer, tag: 0))
+
+        try await waitFor { recorder.count == 8 }
+        #expect(recorder.snapshot == Array(0...7), "a late ticket within the stall threshold must still deliver, in order")
+    }
+
+    @Test("DEBUG: emit only ever runs on OrderedDelivery's own queue")
+    func emitRunsOnItsOwnQueue() async throws {
+        // `emit`'s `dispatchPrecondition(.onQueue(queue))` (DEBUG-only) traps
+        // if this is ever violated. Driving a normal delivery through to
+        // completion without crashing, from a suite that runs this alongside
+        // every other `fulfil` call above, is the running proof that it never
+        // fires — there is no path to `emit` except through `queue.async`/
+        // `queue.sync` inside this class.
+        let buffer = try #require(Self.makeBuffer())
+        let delivery = OrderedDelivery(maxFramesInFlight: 1, maxLayerSkew: 0, label: "test.ordered-delivery.onqueue")
+        let recorder = Recorder()
+        delivery.setOnFrame { _, pts, _ in recorder.record(pts) }
+        delivery.fulfil(ticket: 0, epoch: 0, Self.frame(buffer, tag: 0))
+        try await waitFor { recorder.count == 1 }
+        #expect(recorder.snapshot == [0])
+    }
+}

From bf5716ccc3b2e253893e1f66cbb24108f93f85a5 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:25:09 +0100
Subject: [PATCH 010/132] fix(dovi): refuse hostile RPUs before libdovi can
 abort the process

libdovi is built panic=abort, so a single panic ends the host process. A
CRC-valid but hostile Dolby Vision RPU could reach one on the native
Profile 7 -> 8.1 conversion.

Adds DoviRpuGuard: it checks the RPU CRC and pre-scans the payload for the
inputs that make libdovi 3.4 panic or allocate without bound (linear
interpolation pieces, polynomial/MMR mixes that break the writer, pivot and
block counts the payload cannot hold, undefined display-management block
lengths). The existing paths now check each RPU with it before parsing: the Profile 8.1
conversion in DoviRpuConverter (convertPacketToProfile81), the
enhancement-layer-type probe, and the DolbyVisionRecordAudit RPU read. The
mode 2 convert -> write pair on a parsed RPU is factored into
DoviRpuConverter.convertedUnspec62 so the tests drive production's own entry
point. A rejected RPU degrades the frame to the HDR10 base exactly as a
libdovi failure already did (#135).

This hardens the existing native 8.1 conversion; it changes no routing and
adds no Dolby Vision FEL code. The guard knows the paths listed above; it
does not prove there are no others.

Tests: DoviRpuGuardTests (crafted RPUs, verdicts, conversion round trip) and
a DolbyVisionRecordAudit case. The CRC-valid mutation fuzz and the
real-file guard test arrive with the composer, whose parameter walk they
also exercise.
---
 CHANGELOG.md                                  |   1 +
 .../Video/DolbyVisionRecordAudit.swift        |   3 +-
 .../AetherEngine/Video/DoviRpuConverter.swift |  17 +-
 Sources/AetherEngine/Video/DoviRpuGuard.swift | 252 +++++++++
 .../DolbyVisionRecordAuditTests.swift         |   8 +
 .../DoviRpuConverterTests.swift               |  57 +-
 .../AetherEngineTests/DoviRpuGuardTests.swift | 531 ++++++++++++++++++
 7 files changed, 863 insertions(+), 6 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/DoviRpuGuard.swift
 create mode 100644 Tests/AetherEngineTests/DoviRpuGuardTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c97a6da1d..189c9f9fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -436,6 +436,7 @@ the public-API contract.
 - **A play or pause pressed during any session rebuild decides how it comes back.** An audio or disc-title switch, `reloadAtCurrentPosition()` or an engine-raised rebuild came back in the transport state it started from, so a pause pressed while it ran was lost. `play()` and `pause()` now write the transport the rebuild settles from, `transportIntentUnderReconstruction` (#464 round 3), while one runs. #711 had added this for audio picks in a field of its own; the two are one now.
 - **Video routing asks for the AV1 hardware decoder only for AV1 sources (#708).** It registered the supplemental decoder on every first load, H.264 and HEVC included. Contributed by yucelokan.
 - **The #243 fetch-tally test tolerates a parallel session start.** A session start zeroes the process-wide tally, so an engine test loading in parallel failed it on CI. Test-only.
+- **A CRC-valid but hostile Dolby Vision RPU no longer aborts the process on any path found so far, in parse, convert or write.** libdovi is built panic=abort, so one panic ends the process. `DoviRpuGuard` checks the CRC and pre-scans each RPU for the inputs that make libdovi 3.4 panic or allocate unbounded: a polynomial piece with linear interpolation (`unimplemented!` in the parser and the writer), a reshaping curve that mixes polynomial and MMR pieces (it parses, and a MEL or residual-free RPU keeps its mapping through the mode 2 conversion, so `dovi_write_unspec62_nalu` then indexes out of bounds), pivot and block counts the payload cannot hold, and display-management block lengths the spec does not define (`unreachable!`). It also refuses an Exp-Golomb value of 2^32 - 1 or more anywhere it reads one (libdovi reads 64 leading zeros differently from a plain shift, so a crafted `mapping_idc` could slip past, and its writer allocates about 0.5 GB to write such an id back). The guard knows these paths; it does not prove there are no others.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
index bbfbabc50..386de2e58 100644
--- a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
+++ b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
@@ -31,7 +31,8 @@ public enum DolbyVisionRecordAudit {
         var result: Int?
         A53SEIParser.forEachNAL(data, size, framing) { nal, len in
             guard result == nil, (nal[0] >> 1) & 0x3F == nalTypeRPU else { return }
-            guard let rpu = dovi_parse_unspec62_nalu(nal, len) else { return }
+            // Behind the CRC and panic-path checks: libdovi aborts the process on some malformed RPUs.
+            guard let rpu = DoviRpuGuard.parse(nal, len) else { return }
             defer { dovi_rpu_free(rpu) }
             guard let hdr = dovi_rpu_get_header(rpu) else { return }
             defer { dovi_rpu_free_header(hdr) }
diff --git a/Sources/AetherEngine/Video/DoviRpuConverter.swift b/Sources/AetherEngine/Video/DoviRpuConverter.swift
index 2dd68515e..a99b55b8c 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter.swift
@@ -20,6 +20,15 @@ public enum DoviRpuConverter {
         }
     }
 
+    /// The Profile 8.1 form of a parsed RPU (`dovi_convert_rpu_with_mode`, mode 2) written back as an
+    /// unspec62 NAL unit, or nil when libdovi refuses either step. The caller frees the result with
+    /// `dovi_data_free`. This is the pair of calls the library can abort in, so everything that feeds it
+    /// goes through `DoviRpuGuard.parse` first, and the tests drive it through this one entry point.
+    static func convertedUnspec62(_ rpu: OpaquePointer) -> UnsafePointer<DoviData>? {
+        guard dovi_convert_rpu_with_mode(rpu, 2) == 0 else { return nil }
+        return dovi_write_unspec62_nalu(rpu)
+    }
+
     /// Returns `false` when a libdovi conversion fails (or on an internal allocation failure).
     /// On a libdovi failure the offending RPU (and EL) are dropped so the frame degrades to the
     /// clean HDR10 base, rather than shipping a P7 RPU inside a container already declared 8.1
@@ -63,13 +72,12 @@ public enum DoviRpuConverter {
             case nalTypeRPU:
                 // Any libdovi failure drops the RPU (degraded) instead of muxing a stale P7 RPU
                 // inside a container already declared 8.1 (mixed-profile hazard, #135).
-                guard let rpu = dovi_parse_unspec62_nalu(nal, len) else {
+                guard let rpu = DoviRpuGuard.parse(nal, len) else {
                     degraded = true
                     return
                 }
                 defer { dovi_rpu_free(rpu) }
-                guard dovi_convert_rpu_with_mode(rpu, 2) == 0,
-                      let out = dovi_write_unspec62_nalu(rpu) else {
+                guard let out = Self.convertedUnspec62(rpu) else {
                     degraded = true
                     return
                 }
@@ -153,7 +161,8 @@ public enum DoviRpuConverter {
         var result: String?
         A53SEIParser.forEachNAL(data, size, framing) { nal, len in
             guard result == nil, (nal[0] >> 1) & 0x3F == nalTypeRPU else { return }
-            guard let rpu = dovi_parse_unspec62_nalu(nal, len) else { return }
+            // Behind the CRC and panic-path checks: libdovi aborts the process on some malformed RPUs.
+            guard let rpu = DoviRpuGuard.parse(nal, len) else { return }
             defer { dovi_rpu_free(rpu) }
             guard let hdr = dovi_rpu_get_header(rpu) else { return }
             defer { dovi_rpu_free_header(hdr) }
diff --git a/Sources/AetherEngine/Video/DoviRpuGuard.swift b/Sources/AetherEngine/Video/DoviRpuGuard.swift
new file mode 100644
index 000000000..76fecb89b
--- /dev/null
+++ b/Sources/AetherEngine/Video/DoviRpuGuard.swift
@@ -0,0 +1,252 @@
+import Foundation
+import Dovi
+
+/// libdovi is built panic=abort and parses before it checks the CRC, so a corrupt RPU that
+/// reaches an `unimplemented!()` / `unreachable!()` branch (libdovi 3.4 has no `todo!()` on these
+/// paths) kills the process. Every RPU is CRC-checked here first; a
+/// payload with a bad CRC never reaches the Rust parser. A crafted RPU with a valid CRC can still
+/// reach a panic in the parser or, after `dovi_convert_rpu_with_mode`, in the writer;
+/// `reachesUnimplementedPath` refuses the ones that are known (see there).
+enum DoviRpuGuard {
+
+    private static let crcTable: [UInt32] = (0..<256).map { i in
+        var c = UInt32(i) << 24
+        for _ in 0..<8 { c = c & 0x8000_0000 != 0 ? (c << 1) ^ 0x04C1_1DB7 : c << 1 }
+        return c
+    }
+
+    /// `nal` starts at the 2-byte HEVC NAL header (type 62), emulation prevention still in place.
+    /// Returns the unescaped RPU (header included) when its CRC32 is right, else nil.
+    /// Layout after unescaping: header(2) 0x19 payload... crc32(4) 0x80.
+    static func verifiedUnescaped(_ nal: UnsafePointer<UInt8>, _ len: Int) -> [UInt8]? {
+        guard len >= 8 else { return nil }
+        var u = [UInt8]()
+        u.reserveCapacity(len)
+        var zeros = 0
+        for i in 0..<len {
+            let b = nal[i]
+            if zeros >= 2 && b == 3 { zeros = 0; continue }
+            u.append(b)
+            zeros = b == 0 ? zeros + 1 : 0
+        }
+        while let last = u.last, last == 0 { u.removeLast() }   // cabac_zero_words / trailing zeros
+        guard u.count >= 8, u[2] == 0x19, u[u.count - 1] == 0x80 else { return nil }
+        let tailAt = u.count - 5
+        var crc: UInt32 = 0xFFFF_FFFF
+        for i in 3..<tailAt { crc = (crc << 8) ^ crcTable[Int((crc >> 24) ^ UInt32(u[i]))] }
+        let stored = (UInt32(u[tailAt]) << 24) | (UInt32(u[tailAt + 1]) << 16)
+            | (UInt32(u[tailAt + 2]) << 8) | UInt32(u[tailAt + 3])
+        return crc == stored ? u : nil
+    }
+
+    static func crcIsValid(_ nal: UnsafePointer<UInt8>, _ len: Int) -> Bool {
+        verifiedUnescaped(nal, len) != nil
+    }
+
+    /// MSB-first bit reader. Every read returns nil past the end instead of trapping.
+    private struct Bits {
+        let bytes: [UInt8]
+        let end: Int          // in bits
+        var pos: Int
+
+        mutating func bit() -> UInt64? {
+            guard pos < end else { return nil }
+            let v = (bytes[pos >> 3] >> UInt8(7 - (pos & 7))) & 1
+            pos += 1
+            return UInt64(v)
+        }
+        mutating func bits(_ n: Int) -> UInt64? {
+            guard n >= 0, n <= 64, pos + n <= end else { return nil }
+            var v: UInt64 = 0
+            for _ in 0..<n { v = (v << 1) | bit()! }
+            return v
+        }
+        /// Set when an Exp-Golomb code has `hostileLeadingZeros` or more leading zeros, i.e. a value of
+        /// 2^32 - 1 or more. No RPU field comes near that (ids are 0...15, depths and counts are tiny,
+        /// the widest is `el_bit_depth_minus8` with its 8 extension bits above 8 bits). libdovi decodes
+        /// such a code without complaint but does not survive it: at exactly 64 zeros its release-mode
+        /// shift wraps where a plain Swift shift does not, so the two readers disagree on the value, and
+        /// `write_ue(u64::MAX)` unary-codes 2^32 - 1 zeros, an allocation of about 0.5 GB. The reader
+        /// stops there and flags the RPU as hostile instead of guessing at the value.
+        var hostile = false
+        static let hostileLeadingZeros = 32
+
+        mutating func ue() -> UInt64? {
+            var zeros = 0
+            while true {
+                guard let b = bit() else { return nil }   // out of bits: libdovi errors on the same read
+                if b == 1 { break }
+                zeros += 1
+                if zeros >= Self.hostileLeadingZeros { hostile = true; return nil }
+            }
+            guard let rest = bits(zeros) else { return nil }
+            return ((UInt64(1) << UInt64(zeros)) - 1) + rest   // zeros < 32: no overflow
+        }
+        mutating func skipSE() -> Bool { ue() != nil }
+    }
+
+    /// True when the RPU steers libdovi 3.4 into a panic, which aborts the process because the library is
+    /// built panic=abort. Mirrors `RpuDataHeader::parse`, `RpuDataMapping::parse` and the DM payload far
+    /// enough to see these, each of which parses and survives to the writer or aborts in the parser:
+    ///
+    /// - a polynomial piece with `poly_order_minus1 == 0 && linear_interp_flag` (`unimplemented!()` in
+    ///   both the parser and the writer);
+    /// - a curve whose pieces do not all share one `mapping_idc`. The parser accepts the mix and keeps
+    ///   one coefficient list per method, but the writer emits the curve's last `mapping_idc` for every
+    ///   piece and indexes the polynomial list per piece, which is shorter than the piece count:
+    ///   an out-of-bounds panic in `dovi_write_unspec62_nalu`. Mode 2 conversion drops the mapping only
+    ///   for an FEL stream, so a MEL or residual-free RPU reaches the writer with the mix intact;
+    /// - a pivot or block count the payload cannot hold (an allocation abort), and a level 8, 9 or 10
+    ///   block of a length the spec does not define (`unreachable!()` in `required_bits`).
+    ///
+    /// An Exp-Golomb code with 32 or more leading zeros anywhere the scan reads one is hostile (see
+    /// `Bits.hostile`) and answers true.
+    ///
+    /// Otherwise conservative, and every `false` is on a path where libdovi itself returns an error
+    /// before reaching any panic: running out of bits (libdovi's reads fail on the same field, the
+    /// scan mirrors its read order), a value libdovi's header or mapping parser rejects with `ensure!`
+    /// or `bail!` (`rpu_type`, `coefficient_data_type`, the bit depths and denominator checked by
+    /// `RpuDataHeader::validate`, `mapping_idc` other than 0 or 1, `poly_order_minus1` above 1,
+    /// `mmr_order_minus1` above 2, a non-zero `nlq_method_idc`), or a DM block level the CM version
+    /// does not allow.
+    static func reachesUnimplementedPath(_ u: [UInt8]) -> Bool {
+        // libdovi's reader runs to the end of the trimmed data, CRC and final byte included, so a mutated
+        // piece count can make it read the linear flag out of the CRC bytes. Mirror that bound.
+        var r = Bits(bytes: u, end: u.count * 8, pos: 3 * 8)   // after NAL header + 0x19
+        return scan(&r) || r.hostile
+    }
+
+    private static func scan(_ r: inout Bits) -> Bool {
+        guard r.bits(6) == 2, let format = r.bits(11) else { return false }
+        guard r.bits(4) != nil, r.bits(4) != nil, let seqInfo = r.bit() else { return false }
+        guard seqInfo == 1 else { return false }
+        guard r.bit() != nil, let dataType = r.bits(2) else { return false }
+        var denom: UInt64 = 0
+        if dataType == 0 { guard let d = r.ue() else { return false }; denom = d }
+        guard r.bits(2) != nil, r.bit() != nil else { return false }
+        var blDepth: UInt64 = 0, elDepth: UInt64 = 0, reserved3: UInt64 = 0
+        var disableResidual = false
+        if format & 0x700 == 0 {
+            guard let bl = r.ue(), let el = r.ue(), r.ue() != nil, r.bit() != nil, let res = r.bits(3),
+                  r.bit() != nil, let dr = r.bit() else { return false }
+            blDepth = bl
+            elDepth = el & 0xFF
+            reserved3 = res
+            disableResidual = dr == 1
+        }
+        let coefLen: Int
+        if dataType == 0 { guard denom <= 32 else { return false }; coefLen = Int(denom) }
+        else if dataType == 1 { coefLen = 32 } else { return false }
+        // libdovi rejects anything but 10-bit base layers and denom > 23 before reading the mapping.
+        guard blDepth == 2, denom <= 23 else { return false }
+        guard let dmPresent = r.bit(), let usePrev = r.bit() else { return false }
+        if usePrev == 1 {
+            // libdovi reads prev_vdr_rpu_id and skips only the mapping (curves and NLQ); the DM payload
+            // is still parsed when vdr_dm_metadata_present_flag is set, so an invalid block must be
+            // caught here too.
+            guard r.ue() != nil, dmPresent == 1 else { return false }
+            return reachesInvalidDmBlock(&r, compressed: reserved3 == 1)
+        }
+        guard r.ue() != nil, r.ue() != nil, r.ue() != nil else { return false }
+        let depth = Int(blDepth) + 8
+        var pieces = [Int](repeating: 0, count: 3)
+        for c in 0..<3 {
+            guard let n = r.ue() else { return false }
+            // libdovi sizes its pivot and piece vectors from this count before reading them, so a count the
+            // payload cannot hold aborts on allocation instead of failing: reject it here.
+            if n > UInt64(r.end - r.pos) / UInt64(depth) { return true }
+            pieces[c] = Int(n) + 1
+            for _ in 0..<(Int(n) + 2) { guard r.bits(depth) != nil else { return false } }
+        }
+        if format & 0x700 == 0 && !disableResidual {
+            guard r.bits(3) == 0 else { return false }
+            for _ in 0..<2 { guard r.bits(depth) != nil else { return false } }   // NLQ_NUM_PIVOTS == 2 (guarded by the bounds above)
+        }
+        guard r.ue() != nil, r.ue() != nil else { return false }
+        for c in 0..<3 {
+            var curveIdc: UInt64?
+            for _ in 0..<pieces[c] {
+                guard let idc = r.ue() else { return false }
+                // The writer cannot represent a curve that mixes methods (see above).
+                if let curveIdc, idc <= 1, idc != curveIdc { return true }
+                curveIdc = idc
+                if idc == 0 {
+                    guard let order = r.ue(), order <= 1 else { return false }
+                    if order == 0 {
+                        guard let linear = r.bit() else { return false }
+                        if linear == 1 { return true }
+                    }
+                    for _ in 0..<(Int(order) + 2) {
+                        if dataType == 0 { guard r.skipSE() else { return false } }
+                        guard r.bits(coefLen) != nil else { return false }
+                    }
+                } else if idc == 1 {
+                    guard let order = r.bits(2), order <= 2 else { return false }
+                    if dataType == 0 { guard r.skipSE() else { return false } }
+                    guard r.bits(coefLen) != nil else { return false }
+                    for _ in 0...Int(order) {
+                        for _ in 0..<7 {   // MMR_MAX_COEFFS
+                            if dataType == 0 { guard r.skipSE() else { return false } }
+                            guard r.bits(coefLen) != nil else { return false }
+                        }
+                    }
+                } else { return false }
+            }
+        }
+        // NLQ parameters (profile 7 with a residual).
+        if format & 0x700 == 0 && !disableResidual {
+            guard elDepth == 2 else { return false }
+            for _ in 0..<3 {
+                guard r.bits(Int(elDepth) + 8) != nil else { return false }
+                if dataType == 0 { guard r.skipSE() else { return false } }
+                guard r.bits(coefLen) != nil else { return false }
+                for _ in 0..<2 {   // deadzone slope, threshold
+                    if dataType == 0 { guard r.skipSE() else { return false } }
+                    guard r.bits(coefLen) != nil else { return false }
+                }
+            }
+        }
+        guard dmPresent == 1 else { return false }
+        return reachesInvalidDmBlock(&r, compressed: reserved3 == 1)
+    }
+
+    /// libdovi's `required_bits()` for level 8, 9 and 10 blocks is `unreachable!()` for any length the
+    /// spec does not define, and the parser only checks the length against itself, so a CRC-valid RPU
+    /// with such a block aborts the process. Walks the DM payload (CM v2.9 list, then CM v4.0 list)
+    /// far enough to see every block's level and length.
+    private static func reachesInvalidDmBlock(_ r: inout Bits, compressed: Bool) -> Bool {
+        guard r.ue() != nil, r.ue() != nil, r.ue() != nil else { return false }
+        if !compressed {   // fixed fields of VdrDmData::parse
+            guard r.pos + 509 <= r.end else { return false }
+            r.pos += 509
+        }   // fixed fields of VdrDmData::parse
+        for section in 0..<2 {
+            if section == 1 && r.end - r.pos < 56 { return false }   // DM_DATA_PAYLOAD2_MIN_BITS
+            guard let count = r.ue() else { return false }
+            if count > UInt64(r.end - r.pos) / 9 { return true }   // allocated up front by libdovi, like the pivot count
+            while r.pos & 7 != 0 { guard r.bit() != nil else { return false } }
+            for _ in 0..<count {
+                guard let length = r.ue(), let level = r.bits(8) else { return false }
+                if section == 1 {
+                    switch level {
+                    case 8: if ![10, 12, 13, 19, 25].contains(length) { return true }
+                    case 9: if ![1, 17].contains(length) { return true }
+                    case 10: if ![5, 21].contains(length) { return true }
+                    case 3, 11, 254: break
+                    default: return false   // libdovi errors on the rest
+                    }
+                } else if ![1, 2, 4, 5, 6, 255].contains(level) { return false }
+                guard length < 1 << 20, r.pos + Int(length) * 8 <= r.end else { return false }
+                r.pos += Int(length) * 8
+            }
+        }
+        return false
+    }
+
+    /// `dovi_parse_unspec62_nalu` behind the CRC check and the panic-path check; nil when the
+    /// RPU is corrupt or would abort the library.
+    static func parse(_ nal: UnsafePointer<UInt8>, _ len: Int) -> OpaquePointer? {
+        guard let u = verifiedUnescaped(nal, len), !reachesUnimplementedPath(u) else { return nil }
+        return dovi_parse_unspec62_nalu(nal, len)
+    }
+}
diff --git a/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift b/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift
index 2d7afba61..55e88dce7 100644
--- a/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift
+++ b/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift
@@ -101,6 +101,14 @@ struct DolbyVisionRecordAuditTests {
         #expect(DolbyVisionRecordAudit.rpuProfile(pkt) == nil)
     }
 
+    @Test("an RPU the guard rejects is never handed to libdovi, which would abort the process")
+    func rpuThatWouldAbortLibdoviSaysNothing() {
+        let rpu = DoviRpuGuardTests.craft(linearOnComponent: 1)
+        let pkt = Self.avccPacket([Self.hevcNAL(type: 1, payload: [0xAA]), rpu])
+        defer { Self.free(pkt) }
+        #expect(DolbyVisionRecordAudit.rpuProfile(pkt) == nil)
+    }
+
     // MARK: - When the RPU is worth reading
 
     @Test("a Profile 5 record over a BT.2020 YCbCr PQ VUI is worth auditing")
diff --git a/Tests/AetherEngineTests/DoviRpuConverterTests.swift b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
index 2942a60d4..7e33a1789 100644
--- a/Tests/AetherEngineTests/DoviRpuConverterTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
@@ -71,6 +71,61 @@ struct DoviRpuConverterTests {
         #expect(nalTypes(pkt) == [1])
     }
 
+    /// CRC-valid RPUs that reach a panic or an unbounded allocation in libdovi, and one with a wrong CRC.
+    /// Handing any of them to libdovi aborts the test process, so passing is the point.
+    typealias Hostile = (name: String, rpu: [UInt8])
+    static let hostileRPUs: [Hostile] = {
+        typealias G = DoviRpuGuardTests
+        let poly: [[G.Piece]] = [[.polynomial], [.polynomial], [.polynomial]]
+        return [
+            ("linear interpolation", G.craft(linearOnComponent: 1)),
+            ("polynomial and MMR mix, no residual", G.craft(pieces: [[.polynomial, .mmr], [.polynomial], [.polynomial]])),
+            ("polynomial and MMR mix, MEL", G.craft(pieces: [[.mmr, .polynomial], [.polynomial], [.polynomial]], residual: .mel)),
+            ("polynomial and MMR mix, FEL", G.craft(pieces: [[.polynomial], [.polynomial], [.polynomial, .mmr]], residual: .fel)),
+            ("pivot count beyond the payload", G.craft(pieces: poly, pivotCount: (UInt64(1) << 32) - 2)),
+            ("mapping_idc with 64 leading zeros", G.craft(pieces: [[.linear], [.polynomial], [.polynomial]],
+                                                          firstMappingIdc: { $0.ueRaw(zeros: 64, rest: 0) })),
+            ("vdr_rpu_id with 40 leading zeros", G.craft(pieces: poly, vdrRpuId: { $0.ueRaw(zeros: 40, rest: G.maxRest(40)) })),
+            ("undefined level 8 block length", G.craftUsePrev(cmv40Block: (11, 8))),
+            ("bad CRC", G.withBadCRC(G.craft(linearOnComponent: nil), crcByte: 1)),
+        ]
+    }()
+
+    @Test("A hostile or corrupt RPU is refused on the real conversion paths: HDR10 fallback, no abort",
+          arguments: Array(DoviRpuConverterTests.hostileRPUs.indices), [VideoNALFraming.lengthPrefixed(size: 4), .annexB])
+    func hostileRPUDegradesOnEveryEntryPoint(index: Int, framing: VideoNALFraming) {
+        let (name, rpu) = Self.hostileRPUs[index]
+        let nals = [hevcNAL(type: 1, payload: [0xAA, 0xBB]), rpu, hevcNAL(type: 63, payload: [0xCC])]
+        let bytes = framed(nals, framing)
+
+        // The probes read the packet and must come back empty-handed.
+        let probe = packet(from: bytes)
+        defer { free(probe) }
+        #expect(DoviRpuConverter.enhancementLayerType(probe, framing: framing) == nil, Comment(rawValue: name))
+        #expect(DolbyVisionRecordAudit.rpuProfile(probe, framing: framing) == nil, Comment(rawValue: name))
+
+        // The conversion reports the failure and drops the RPU and the EL, keeping the base layer.
+        let pkt = packet(from: bytes)
+        defer { free(pkt) }
+        #expect(DoviRpuConverter.convertPacketToProfile81(pkt, framing: framing) == false, Comment(rawValue: name))
+        let expected = framed([nals[0]], framing)
+        #expect(packetBytes(pkt) == expected, Comment(rawValue: name))
+    }
+
+    @Test("A well-formed crafted RPU takes the same paths and converts, so the refusals above are the guard's")
+    func craftedRPUConvertsOnTheSamePaths() {
+        let rpu = DoviRpuGuardTests.craft(pieces: [[.polynomial], [.mmr], [.mmr]], residual: .fel)
+        let bytes = framed([hevcNAL(type: 1, payload: [0xAA, 0xBB]), rpu, hevcNAL(type: 63, payload: [0xCC])],
+                           .lengthPrefixed(size: 4))
+        let probe = packet(from: bytes)
+        defer { free(probe) }
+        #expect(DoviRpuConverter.enhancementLayerType(probe) == "FEL")
+        let pkt = packet(from: bytes)
+        defer { free(pkt) }
+        #expect(DoviRpuConverter.convertPacketToProfile81(pkt) == true)
+        #expect(nalTypes(pkt) == [1, 62])
+    }
+
     @Test("A non-DV packet is left untouched")
     func leavesNonDVUntouched() {
         let bl = hevcNAL(type: 1, payload: [0xAA, 0xBB])
@@ -258,7 +313,7 @@ struct DoviRpuConverterTests {
             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 }
+                    guard let rpu = DoviRpuGuard.parse(nal, len) else { degraded = true; return }   // as production: the guard first, libdovi is panic=abort
                     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 {
diff --git a/Tests/AetherEngineTests/DoviRpuGuardTests.swift b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
new file mode 100644
index 000000000..2f5616a7d
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
@@ -0,0 +1,531 @@
+import Testing
+import Foundation
+import Dovi
+@testable import AetherEngine
+
+/// libdovi aborts the process on a polynomial piece with linear interpolation. The guard must
+/// see that coming for an RPU whose CRC is perfectly valid, and must not flag real ones.
+struct DoviRpuGuardTests {
+
+    struct BitWriter {
+        var bits: [Bool] = []
+        mutating func put(_ v: UInt64, _ n: Int) { for i in stride(from: n - 1, through: 0, by: -1) { bits.append((v >> UInt64(i)) & 1 == 1) } }
+        mutating func ue(_ v: UInt64) {
+            let x = v + 1
+            let len = 64 - x.leadingZeroBitCount
+            put(0, len - 1); put(x, len)
+        }
+        mutating func se(_ v: Int64) { ue(v > 0 ? UInt64(2 * v - 1) : UInt64(-2 * v)) }
+        /// An Exp-Golomb code with exactly `zeros` leading zeros and `rest` as its suffix, however large
+        /// the value that makes (`ue` cannot write above 2^64 - 2). libdovi reads it as `rest + 2^zeros - 1`,
+        /// wrapping: its release build masks a shift by 64, so 64 zeros read as just `rest`.
+        mutating func ueRaw(zeros: Int, rest: UInt64) {
+            put(0, zeros); put(1, 1); put(rest, zeros)
+        }
+        var bytes: [UInt8] {
+            var out = [UInt8](repeating: 0, count: (bits.count + 7) / 8)
+            for (i, b) in bits.enumerated() where b { out[i >> 3] |= UInt8(0x80 >> (i & 7)) }
+            return out
+        }
+    }
+
+    static func crc(_ data: ArraySlice<UInt8>) -> UInt32 {
+        var c: UInt32 = 0xFFFF_FFFF
+        for byte in data {
+            c ^= UInt32(byte) << 24
+            for _ in 0..<8 { c = c & 0x8000_0000 != 0 ? (c << 1) ^ 0x04C1_1DB7 : c << 1 }
+        }
+        return c
+    }
+
+    enum Piece {
+        case polynomial, mmr
+        /// A polynomial piece with `linear_interp_flag` set, which libdovi 3.4 cannot represent.
+        case linear
+    }
+
+    enum Residual {
+        /// Profile 8 shape: `disable_residual_flag` set, no NLQ.
+        case none
+        /// Profile 7 with the minimal enhancement layer's NLQ values.
+        case mel
+        /// Profile 7 with non-trivial NLQ values.
+        case fel
+    }
+
+    /// A structurally valid RPU with a valid CRC, one entry of `pieces` per component (luma, Cb, Cr),
+    /// each listing that curve's pieces in order. No DM metadata, so the mapping is all there is to parse
+    /// and to write back. Residual-free by default (profile 8 shape); `residual` makes it a Profile 7 RPU.
+    /// One display-management payload: the ids, the optional fixed fields, then the CM v2.9 list and the
+    /// CM v4.0 list. Each list holds at most one block (zero payload bytes) followed, in the v4.0 list, by
+    /// the mandatory level 254 block.
+    struct DMPayload {
+        /// `reserved_zero_3bits == 1`: only the three ids precede the block lists. Otherwise the 509-bit
+        /// fixed field set of `VdrDmData::parse` follows them.
+        var compressed = true
+        var currentDmMetadataId: ((inout BitWriter) -> Void)?
+        /// The declared CM v2.9 block count, used only when `cmv29Block` is nil (no block follows it).
+        var cmv29Count: UInt64 = 0
+        var cmv29Block: (length: UInt64, level: UInt64)?
+        var cmv40Block: (length: UInt64, level: UInt64)?
+    }
+
+    static func writeDM(_ w: inout BitWriter, _ dm: DMPayload) {
+        w.ue(0)                                  // affected_dm_metadata_id
+        if let id = dm.currentDmMetadataId { id(&w) } else { w.ue(0) }
+        w.ue(0)                                  // scene_refresh_flag
+        if !dm.compressed {                      // 509 bits, valid per libdovi's validate
+            for _ in 0..<9 { w.put(0, 16) }      // ycc_to_rgb_coef
+            for _ in 0..<3 { w.put(0, 32) }      // ycc_to_rgb_offset
+            for _ in 0..<9 { w.put(0, 16) }      // rgb_to_lms_coef
+            w.put(65535, 16); w.put(0, 16); w.put(0, 16); w.put(0, 32)   // signal_eotf (65535 with no params)
+            w.put(10, 5); w.put(0, 2); w.put(0, 2); w.put(0, 2)          // depth, color space, chroma, range
+            w.put(0, 12); w.put(0, 12); w.put(0, 10)                     // min/max pq, diagonal
+        }
+        if let block = dm.cmv29Block {
+            w.ue(1)
+            while w.bits.count % 8 != 0 { w.bits.append(false) }
+            w.ue(block.length); w.put(block.level, 8)
+            for _ in 0..<block.length { w.put(0, 8) }
+            // No alignment after the block: the next list's count follows it bit for bit.
+        } else {
+            w.ue(dm.cmv29Count)
+            while w.bits.count % 8 != 0 { w.bits.append(false) }
+        }
+        if let block = dm.cmv40Block {
+            w.ue(2)
+            while w.bits.count % 8 != 0 { w.bits.append(false) }
+            w.ue(block.length); w.put(block.level, 8)
+            for _ in 0..<block.length { w.put(0, 8) }
+            w.ue(2); w.put(254, 8)               // the required level 254 block
+            for _ in 0..<2 { w.put(0, 8) }
+        } else {
+            w.ue(0)
+        }
+        while w.bits.count % 8 != 0 { w.bits.append(false) }
+    }
+
+    /// `body` is the payload after the 0x19 prefix: CRC, final byte and emulation prevention are added.
+    static func seal(_ payload: [UInt8]) -> [UInt8] {
+        var body: [UInt8] = [0x19] + payload
+        let crc = crc(body[1...])
+        body += [UInt8(crc >> 24), UInt8(crc >> 16 & 0xFF), UInt8(crc >> 8 & 0xFF), UInt8(crc & 0xFF), 0x80]
+        return escape(body)
+    }
+
+    /// `body` is 0x19, the payload, the CRC and the final byte; the NAL header, emulation prevention and
+    /// the padding are added.
+    static func escape(_ body: [UInt8]) -> [UInt8] {
+        var out: [UInt8] = [0x7C, 0x01]
+        var zeros = 0
+        for b in body {
+            if zeros >= 2 && b <= 3 { out.append(3); zeros = 0 }
+            out.append(b)
+            zeros = b == 0 ? zeros + 1 : 0
+        }
+        // libdovi refuses an input under 25 bytes before it looks at anything else; trailing zero bytes
+        // are trimmed by both it and the guard, so they pad a short RPU without changing it.
+        while out.count < 26 { out.append(0) }
+        return out
+    }
+
+    /// `coefficientDataType` 1 (32-bit coefficients, no integer part, no denominator) is residual-free only.
+    /// `pivotCount` replaces luma's `num_pivots_minus2` (the pivots written stay the real ones),
+    /// `firstMappingIdc` the encoding of luma's first `mapping_idc`, `vdrRpuId` the mapping's id and `dm`
+    /// appends a display-management payload after the mapping and NLQ.
+    static func craft(pieces: [[Piece]], residual: Residual = .none, coefficientDataType: Int = 0,
+                      pivotCount: UInt64? = nil, firstMappingIdc: ((inout BitWriter) -> Void)? = nil,
+                      vdrRpuId: ((inout BitWriter) -> Void)? = nil, dm: DMPayload? = nil) -> [UInt8] {
+        precondition(coefficientDataType == 0 || residual == .none)
+        var w = BitWriter()
+        w.put(2, 6); w.put(18, 11)           // rpu_type, rpu_format (libdovi checks the 0x08 0x09 start)
+        w.put(1, 4); w.put(0, 4)             // vdr_rpu_profile 1, level 0
+        w.put(1, 1)                          // vdr_seq_info_present
+        w.put(0, 1); w.put(UInt64(coefficientDataType), 2)   // chroma filter flag, coefficient_data_type
+        if coefficientDataType == 0 { w.ue(23) }             // denom
+        w.put(0, 2); w.put(0, 1)             // normalized idc, full range
+        w.ue(2); w.ue(2); w.ue(4)            // bl, el, vdr depth - 8
+        w.put(0, 1)                          // spatial resampling flag
+        w.put(dm?.compressed == true ? 1 : 0, 3)   // reserved_zero_3bits, 1 selects compressed DM data
+        w.put(residual == .none ? 0 : 1, 1)  // el_spatial_resampling_filter_flag (with the residual: profile 7)
+        w.put(residual == .none ? 1 : 0, 1)  // disable_residual
+        w.put(dm == nil ? 0 : 1, 1)          // vdr_dm_metadata_present
+        w.put(0, 1)                          // use_prev_vdr_rpu
+        if let vdrRpuId { vdrRpuId(&w) } else { w.ue(0) }
+        w.ue(0); w.ue(0)                     // color space, chroma format
+        for (c, curve) in pieces.enumerated() {
+            if c == 0, let pivotCount { w.ue(pivotCount) } else { w.ue(UInt64(curve.count) - 1) }   // num_pivots_minus2
+            for k in 0...curve.count { w.put(UInt64(k * 1023 / curve.count), 10) }
+        }
+        if residual != .none { w.put(0, 3); w.put(0, 10); w.put(1023, 10) }   // NLQ method, pivots
+        w.ue(0); w.ue(0)                     // partitions
+        /// One coefficient: signed integer part and 23 fraction bits, or (type 1) 32 plain bits.
+        func coef(_ w: inout BitWriter, _ int: Int64) {
+            if coefficientDataType == 0 { w.se(int); w.put(0, 23) } else { w.put(0, 32) }
+        }
+        for (c, curve) in pieces.enumerated() {
+            for (k, piece) in curve.enumerated() {
+                let idc = { (w: inout BitWriter, v: UInt64) in
+                    if c == 0 && k == 0, let firstMappingIdc { firstMappingIdc(&w) } else { w.ue(v) }
+                }
+                switch piece {
+                case .mmr:
+                    idc(&w, 1); w.put(0, 2)  // MMR, order 1
+                    coef(&w, 0)
+                    for _ in 0..<7 { coef(&w, 0) }
+                case .linear:
+                    idc(&w, 0); w.ue(0); w.put(1, 1)
+                case .polynomial:
+                    idc(&w, 0)               // polynomial
+                    w.ue(0)                  // poly_order_minus1
+                    w.put(0, 1)              // linear_interp_flag
+                    for k in 0..<2 { coef(&w, k == 1 ? 1 : 0) }
+                }
+            }
+        }
+        if residual != .none {
+            for c in 0..<3 {                 // NLQ parameters; all zero but vdr_in_max_int is the MEL signature
+                let fel = residual == .fel
+                w.put(fel ? UInt64(40 + 8 * c) : 0, 10)
+                w.ue(fel ? 0 : 1); w.put(fel ? 1 << 20 : 0, 23)
+                w.ue(0); w.put(fel ? 3 << 18 : 0, 23)
+                w.ue(0); w.put(fel ? 1 << 19 : 0, 23)
+            }
+        }
+        if let dm { writeDM(&w, dm) }
+        while w.bits.count % 8 != 0 { w.bits.append(false) }
+        return seal(w.bytes)
+    }
+
+    /// One piece per component, polynomial unless named: the shape most tests here build.
+    static func craft(linearOnComponent: Int?, mmrOnComponent: Int? = nil) -> [UInt8] {
+        craft(pieces: (0..<3).map { c in
+            [c == linearOnComponent ? Piece.linear : c == mmrOnComponent ? .mmr : .polynomial]
+        })
+    }
+
+    /// `nal` with one bit of its stored CRC32 flipped (`crcByte` 0 is the first CRC byte) or, for
+    /// `payloadByte`, one bit of the payload flipped under the CRC that was computed for the original.
+    static func withBadCRC(_ nal: [UInt8], crcByte: Int? = nil, payloadByte: Int? = nil) -> [UInt8] {
+        var u: [UInt8] = []
+        var zeros = 0
+        for b in nal {
+            if zeros >= 2 && b == 3 { zeros = 0; continue }
+            u.append(b)
+            zeros = b == 0 ? zeros + 1 : 0
+        }
+        while u.last == 0 { u.removeLast() }
+        var body = Array(u.dropFirst(2))   // 0x19, payload, crc32(4), 0x80
+        if let crcByte { body[body.count - 5 + crcByte] ^= 0x01 }
+        if let payloadByte { body[1 + payloadByte] ^= 0x10 }
+        return escape(body)
+    }
+
+    static func verdict(_ nal: [UInt8]) -> (crc: Bool, flagged: Bool) {
+        nal.withUnsafeBufferPointer { p in
+            guard let u = DoviRpuGuard.verifiedUnescaped(p.baseAddress!, p.count) else { return (false, false) }
+            return (true, DoviRpuGuard.reachesUnimplementedPath(u))
+        }
+    }
+
+    @Test("a crafted structurally valid RPU parses in libdovi, so the scanner is tracking a real layout")
+    func craftedBaselineParses() {
+        let nal = Self.craft(linearOnComponent: nil)
+        #expect(Self.verdict(nal) == (true, false))
+        let rpu = nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        #expect(rpu != nil, "libdovi should accept the crafted RPU")
+        if let rpu {
+            // A handle comes back even on a parse failure; the error is what says it was accepted.
+            #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")")
+            dovi_rpu_free(rpu)
+        }
+    }
+
+    @Test("an RPU whose CRC is wrong is refused before libdovi sees it",
+          arguments: [(0 as Int?, nil as Int?), (3, nil), (nil, 0), (nil, 10)])
+    func badCRCIsRefused(crcByte: Int?, payloadByte: Int?) {
+        let good = Self.craft(linearOnComponent: nil)
+        Self.expectAccepted(good)
+        let bad = Self.withBadCRC(good, crcByte: crcByte, payloadByte: payloadByte)
+        #expect(bad != good)
+        #expect(Self.verdict(bad) == (false, false))
+        #expect(bad.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) } == nil)
+        // The CRC is checked before the scan, so a hostile RPU with a wrong CRC is refused on the CRC.
+        let hostile = Self.withBadCRC(Self.craft(linearOnComponent: 1), crcByte: 2)
+        #expect(Self.verdict(hostile) == (false, false))
+        #expect(hostile.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) } == nil)
+    }
+
+    @Test("an MMR piece is walked past without a false positive")
+    func mmrIsSkipped() {
+        for c in 0..<3 {
+            let nal = Self.craft(linearOnComponent: nil, mmrOnComponent: c)
+            #expect(Self.verdict(nal) == (true, false), "MMR on component \(c)")
+        }
+    }
+
+    @Test("linear interpolation on any component is caught before libdovi sees it",
+          arguments: [0, 1, 2])
+    func linearInterpIsRejected(component: Int) {
+        let nal = Self.craft(linearOnComponent: component)
+        #expect(Self.verdict(nal) == (true, true))
+        let rpu = nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        #expect(rpu == nil)
+    }
+
+    @Test("linear interpolation after an MMR piece is still caught")
+    func linearAfterMmr() {
+        // MMR on component 0, linear on component 2
+        let nal = Self.craft(linearOnComponent: 2, mmrOnComponent: 0)
+        #expect(Self.verdict(nal) == (true, true))
+        #expect(nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) } == nil)
+    }
+
+    /// A Profile 8-shaped RPU with `use_prev_vdr_rpu_flag` set and DM metadata: no mapping follows the
+    /// header, only the DM payload. `cmv40Block` is one (length, level) extended block followed by the
+    /// mandatory level 254 block, `cmv29Count` the declared CM v2.9 block count (no blocks follow it, so only 0 parses).
+    /// `prevRpuId` replaces the `prev_vdr_rpu_id` encoding.
+    static func craftUsePrev(cmv29Count: UInt64 = 0, cmv29Block: (length: UInt64, level: UInt64)? = nil,
+                             cmv40Block: (length: UInt64, level: UInt64)?, compressed: Bool = true,
+                             currentDmMetadataId: ((inout BitWriter) -> Void)? = nil,
+                             prevRpuId: ((inout BitWriter) -> Void)? = nil) -> [UInt8] {
+        var w = BitWriter()
+        w.put(2, 6); w.put(18, 11)
+        w.put(1, 4); w.put(0, 4)
+        w.put(1, 1)
+        w.put(0, 1); w.put(0, 2)
+        w.ue(23)
+        w.put(0, 2); w.put(0, 1)
+        w.ue(2); w.ue(2); w.ue(4)
+        w.put(0, 1); w.put(compressed ? 1 : 0, 3); w.put(0, 1)   // reserved_zero_3bits == 1 selects compressed DM data
+        w.put(1, 1)                          // disable_residual
+        w.put(1, 1)                          // vdr_dm_metadata_present
+        w.put(1, 1)                          // use_prev_vdr_rpu
+        if let prevRpuId { prevRpuId(&w) } else { w.ue(0) }   // prev_vdr_rpu_id
+        writeDM(&w, DMPayload(compressed: compressed, currentDmMetadataId: currentDmMetadataId,
+                              cmv29Count: cmv29Count, cmv29Block: cmv29Block, cmv40Block: cmv40Block))
+        return seal(w.bytes)
+    }
+
+    @Test("a use_prev RPU with valid DM blocks parses in libdovi and is not flagged")
+    func usePrevBaselineParses() {
+        let nal = Self.craftUsePrev(cmv40Block: (10, 8))
+        #expect(Self.verdict(nal) == (true, false))
+        let rpu = nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        #expect(rpu != nil)
+        if let rpu {
+            #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")")
+            dovi_rpu_free(rpu)
+        }
+    }
+
+    @Test("use_prev does not skip the DM check: an invalid level 8 length is caught")
+    func usePrevInvalidLevel8Length() {
+        let nal = Self.craftUsePrev(cmv40Block: (11, 8))
+        #expect(Self.verdict(nal) == (true, true))
+        let rpu = nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        #expect(rpu == nil)
+    }
+
+    @Test("use_prev does not skip the DM check: an oversized extended block count is caught")
+    func usePrevHugeBlockCount() {
+        let nal = Self.craftUsePrev(cmv29Count: 1 << 30, cmv40Block: nil)
+        #expect(Self.verdict(nal) == (true, true))
+        let rpu = nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        #expect(rpu == nil)
+    }
+
+    // MARK: - Hostile encodings and the display-management walk
+
+    /// The guard refuses `nal`: CRC-valid, flagged, and `parse` answers nil without calling libdovi.
+    /// Never call libdovi directly on an RPU passed here: it is built panic=abort and the ones these
+    /// tests build reach a panic or an allocation abort in it.
+    static func expectRejected(_ nal: [UInt8], _ note: String = "", sourceLocation: SourceLocation = #_sourceLocation) {
+        #expect(verdict(nal) == (true, true), Comment(rawValue: note), sourceLocation: sourceLocation)
+        #expect(nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) } == nil,
+                Comment(rawValue: note), sourceLocation: sourceLocation)
+    }
+
+    /// The guard lets `nal` through and libdovi parses it without an error (parsing alone is safe for
+    /// these; they are not hostile).
+    static func expectAccepted(_ nal: [UInt8], _ note: String = "", sourceLocation: SourceLocation = #_sourceLocation) {
+        #expect(verdict(nal) == (true, false), Comment(rawValue: note), sourceLocation: sourceLocation)
+        let rpu = nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) }
+        #expect(rpu != nil, Comment(rawValue: note), sourceLocation: sourceLocation)
+        if let rpu {
+            #expect(dovi_rpu_get_error(rpu) == nil,
+                    Comment(rawValue: "\(note) \(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")"),
+                    sourceLocation: sourceLocation)
+            dovi_rpu_free(rpu)
+        }
+    }
+
+    /// The largest suffix an Exp-Golomb code with `zeros` leading zeros can carry.
+    static func maxRest(_ zeros: Int) -> UInt64 { zeros >= 64 ? .max : (1 << UInt64(zeros)) - 1 }
+
+    @Test("a mapping_idc coded with 64 leading zeros is rejected, not misread as rest - 1")
+    func mappingIdcWithSixtyFourLeadingZeros() {
+        // libdovi's release-mode `read_ue` masks the shift `1 << 64` to `1 << 0`, so it reads this code as
+        // rest = 0, i.e. mapping_idc 0 (polynomial), then poly_order_minus1 0 and the linear flag: the
+        // `unimplemented!()` abort. A plain Swift shift gives 0 and `0 - 1` wrapped is not 0 or 1, so a
+        // scan that trusted it walked away from the RPU and let it through.
+        let nal = Self.craft(pieces: [[.linear], [.polynomial], [.polynomial]],
+                             firstMappingIdc: { $0.ueRaw(zeros: 64, rest: 0) })
+        Self.expectRejected(nal)
+    }
+
+    @Test("an Exp-Golomb code of 32 or more leading zeros is rejected wherever the scan reads one",
+          arguments: [32, 33, 48, 64])
+    func oversizeExpGolombIsRejected(zeros: Int) {
+        let rest = Self.maxRest(zeros)
+        // current_dm_metadata_id is written back as is by the conversion: write_ue(u64::MAX) unary-codes
+        // 2^32 - 1 zeros, a ~0.5 GB allocation. prev_vdr_rpu_id (header) and vdr_rpu_id (mapping) are
+        // written the same way and, like the DM id, not range-checked by libdovi.
+        Self.expectRejected(Self.craftUsePrev(cmv40Block: nil, currentDmMetadataId: { $0.ueRaw(zeros: zeros, rest: rest) }),
+                            "current_dm_metadata_id")
+        Self.expectRejected(Self.craftUsePrev(cmv40Block: nil, prevRpuId: { $0.ueRaw(zeros: zeros, rest: rest) }),
+                            "prev_vdr_rpu_id")
+        Self.expectRejected(Self.craft(pieces: [[.polynomial], [.polynomial], [.polynomial]], vdrRpuId: { $0.ueRaw(zeros: zeros, rest: rest) }),
+                            "vdr_rpu_id")
+        Self.expectRejected(Self.craft(pieces: [[.polynomial], [.polynomial], [.polynomial]],
+                                       firstMappingIdc: { $0.ueRaw(zeros: zeros, rest: rest) }),
+                            "mapping_idc")
+    }
+
+    @Test("an Exp-Golomb code just under the bound (31 leading zeros) is still read normally")
+    func largestInBoundExpGolombIsAccepted() {
+        let nal = Self.craftUsePrev(cmv40Block: nil, currentDmMetadataId: { $0.ueRaw(zeros: 31, rest: Self.maxRest(31)) })
+        Self.expectAccepted(nal)
+    }
+
+    @Test("a pivot count the payload cannot hold is rejected before libdovi sizes its vectors from it",
+          arguments: [UInt64(1) << 31, (UInt64(1) << 32) - 2])
+    func pivotCountBeyondPayload(count: UInt64) {
+        // libdovi allocates `vec![0; num_pivots_minus2 + 2]` per curve before it reads one pivot.
+        Self.expectRejected(Self.craft(pieces: [[.polynomial], [.polynomial], [.polynomial]], pivotCount: count))
+    }
+
+    @Test("an uncompressed DM payload is skipped by its 509 fixed bits and the blocks behind it are checked")
+    func uncompressedDmPayload() {
+        // VdrDmData::parse reads three ids then 509 bits of fixed fields; the guard must land exactly on
+        // the CM v2.9 block count behind them, or the level 8 block below is never seen.
+        Self.expectAccepted(Self.craftUsePrev(cmv40Block: (10, 8), compressed: false), "valid level 8, uncompressed")
+        Self.expectRejected(Self.craftUsePrev(cmv40Block: (11, 8), compressed: false), "level 8 length 11, uncompressed")
+    }
+
+    @Test("a non-empty CM v2.9 block list is walked to the CM v4.0 list behind it")
+    func cmv29BlockWalk() {
+        // Level 1 is a 5-byte CM v2.9 block.
+        Self.expectAccepted(Self.craftUsePrev(cmv29Block: (5, 1), cmv40Block: (10, 8)), "valid")
+        Self.expectRejected(Self.craftUsePrev(cmv29Block: (5, 1), cmv40Block: (11, 8)), "level 8 length 11 behind a level 1 block")
+        Self.expectRejected(Self.craftUsePrev(cmv29Block: (5, 1), cmv40Block: (11, 8), compressed: false), "same, uncompressed")
+    }
+
+    @Test("level 9 and level 10 blocks of an undefined length are rejected, the defined ones are not",
+          arguments: [(1, 9, true), (17, 9, true), (0, 9, false), (2, 9, false), (16, 9, false), (18, 9, false),
+                      (5, 10, true), (21, 10, true), (0, 10, false), (4, 10, false), (6, 10, false), (20, 10, false)])
+    func level9And10Lengths(length: Int, level: Int, valid: Bool) {
+        // `required_bits()` is `unreachable!()` for any other length, and the parser only compares the
+        // length with the block's own, so libdovi aborts after a clean parse.
+        let nal = Self.craftUsePrev(cmv40Block: (UInt64(length), UInt64(level)))
+        if valid {
+            Self.expectAccepted(nal, "level \(level) length \(length)")
+        } else {
+            Self.expectRejected(nal, "level \(level) length \(length)")
+        }
+    }
+
+    @Test("level 8 lengths: the five defined ones pass, their neighbours are rejected",
+          arguments: [(10, true), (12, true), (13, true), (19, true), (25, true),
+                      (0, false), (11, false), (14, false), (20, false), (24, false), (26, false)])
+    func level8Lengths(length: Int, valid: Bool) {
+        let nal = Self.craftUsePrev(cmv40Block: (UInt64(length), 8))
+        if valid { Self.expectAccepted(nal, "length \(length)") } else { Self.expectRejected(nal, "length \(length)") }
+    }
+
+    @Test("coefficient_data_type 1 (32-bit coefficients, no integer parts): the walk stays in step")
+    func coefficientDataTypeOne() {
+        // With type 1 libdovi reads 32 bits per coefficient and no signed integer part; a scan that kept
+        // the type-0 layout would drift and miss the linear piece on the last component.
+        let ok = Self.craft(pieces: [[.polynomial], [.mmr], [.mmr]], coefficientDataType: 1)
+        Self.expectAccepted(ok)
+        for component in 0..<3 {
+            var pieces: [[Piece]] = [[.polynomial], [.mmr], [.mmr]]
+            pieces[component] = [.linear]
+            Self.expectRejected(Self.craft(pieces: pieces, coefficientDataType: 1), "linear on component \(component)")
+        }
+        Self.expectRejected(Self.craft(pieces: [[.polynomial, .mmr], [.mmr], [.mmr]], coefficientDataType: 1), "mixed curve")
+    }
+
+    @Test("a Profile 7 RPU's NLQ parameters are walked to the DM payload behind them",
+          arguments: [Residual.mel, .fel], [true, false])
+    func nlqFollowedByDm(residual: Residual, compressed: Bool) throws {
+        let pieces: [[Piece]] = [[.polynomial], [.mmr], [.mmr]]
+        func dm(_ length: UInt64) -> DMPayload { DMPayload(compressed: compressed, cmv40Block: (length, 8)) }
+        let good = Self.craft(pieces: pieces, residual: residual, dm: dm(10))
+        Self.expectAccepted(good, "\(residual) compressed \(compressed)")
+        // The DM survives the conversion and write like production does.
+        let written = try #require(Self.convertedBytes(good))
+        #expect(!written.isEmpty)
+        Self.expectRejected(Self.craft(pieces: pieces, residual: residual, dm: dm(11)),
+                            "level 8 length 11, \(residual) compressed \(compressed)")
+    }
+
+    // MARK: - Write path
+
+    /// What production does with an RPU the guard let through: `DoviRpuConverter.convertedUnspec62`, the
+    /// mode 2 conversion and the write. nil when the guard or libdovi refuses; reaching the end at all is
+    /// the assertion, because libdovi is built panic=abort and a panic here kills the test process.
+    static func convertedBytes(_ nal: [UInt8]) -> [UInt8]? {
+        guard let rpu = nal.withUnsafeBufferPointer({ DoviRpuGuard.parse($0.baseAddress!, $0.count) }) else { return nil }
+        defer { dovi_rpu_free(rpu) }
+        guard let out = DoviRpuConverter.convertedUnspec62(rpu) else { return nil }
+        defer { dovi_data_free(out) }
+        guard let data = out.pointee.data else { return nil }
+        return [UInt8](UnsafeBufferPointer(start: data, count: out.pointee.len))
+    }
+
+    @Test("a curve that mixes polynomial and MMR pieces is rejected: the writer indexes the polynomial list per piece",
+          arguments: [0, 1, 2], [true, false])
+    func mixedCurveIsRejected(component: Int, polynomialFirst: Bool) {
+        var pieces = [[Piece]](repeating: [.polynomial], count: 3)
+        pieces[component] = polynomialFirst ? [.polynomial, .mmr] : [.mmr, .polynomial]
+        for residual in [Residual.none, .mel, .fel] {
+            let nal = Self.craft(pieces: pieces, residual: residual)
+            #expect(Self.verdict(nal) == (true, true), "component \(component), residual \(residual)")
+            #expect(nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) } == nil)
+        }
+    }
+
+    @Test("the same pieces without the mix are accepted, and convert and write like production does",
+          arguments: [Residual.none, .mel, .fel])
+    func unmixedMultiPieceCurvesConvertAndWrite(residual: Residual) throws {
+        for pieces in [
+            [[Piece.polynomial, .polynomial], [.polynomial, .polynomial], [.polynomial, .polynomial]],
+            [[.polynomial, .polynomial], [.mmr, .mmr], [.mmr, .mmr]],
+            [[.polynomial], [.mmr], [.mmr]],
+        ] {
+            let nal = Self.craft(pieces: pieces, residual: residual)
+            #expect(Self.verdict(nal) == (true, false), "\(pieces)")
+            let written = try #require(Self.convertedBytes(nal), "\(pieces)")
+            // The output is a Profile 8.1 RPU libdovi itself reads back.
+            let reread = written.withUnsafeBufferPointer { dovi_parse_unspec62_nalu($0.baseAddress!, $0.count) }
+            defer { reread.map { dovi_rpu_free($0) } }
+            #expect(reread != nil && dovi_rpu_get_error(reread) == nil, "\(pieces)")
+        }
+    }
+
+    @Test("a crafted Profile 7 RPU is classified from its NLQ values and converts to 8.1",
+          arguments: [Residual.mel, .fel])
+    func craftedProfile7Classification(residual: Residual) throws {
+        let nal = Self.craft(pieces: [[.polynomial], [.mmr], [.mmr]], residual: residual)
+        let rpu = try #require(nal.withUnsafeBufferPointer { DoviRpuGuard.parse($0.baseAddress!, $0.count) })
+        defer { dovi_rpu_free(rpu) }
+        #expect(dovi_rpu_get_error(rpu) == nil)
+        let header = try #require(dovi_rpu_get_header(rpu))
+        defer { dovi_rpu_free_header(header) }
+        let elType = String(cString: try #require(header.pointee.el_type))
+        #expect(elType == (residual == .fel ? "FEL" : "MEL"))
+        #expect(Self.convertedBytes(nal) != nil)
+    }
+}

From 242a12f11ca47f0bf0ec284ac707e4f0383f649f Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:26:24 +0100
Subject: [PATCH 011/132] feat(renderer): bounded video look-ahead gate and
 display-order PTS for reordered streams

Adds the SampleBufferRenderer pieces the dual-layer Dolby Vision path needs
for pacing, as inert, opt-in additions:

- felVideoLookaheadFrames (9) and mayEnqueueVideoFrame / setFELLookahead:
  a gate that runs BEFORE decode and refuses a compressed frame more than
  nine frame intervals ahead of the playback clock, so composed 4K frames
  (about 25 MB each) cannot pile up behind Apple's readiness gate alone.
- displayOrderPTS: estimates a packet's display-order PTS in decode order
  from the largest amount a later packet fell below the highest PTS seen,
  so B-frame streams do not swing the cap with the position in the GOP. A
  gap larger than HEVC's 16-picture reorder ceiling is treated as a
  timestamp discontinuity and does not poison the learned lead.

Nothing calls the gate yet and it is off unless setFELLookahead(enabled:)
is called, so non-FEL pacing is unchanged. The decoder and the host wiring
come in later PRs; the composer-side pool sizing that follows this cap
(DoviFelComposer.outputPoolAllocationThreshold) is pinned in the composer PR.

Tests: SampleBufferRendererLookaheadTests, SampleBufferRendererReorderDepthTests.
---
 .../Renderer/SampleBufferRenderer.swift       |  95 +++++++++
 .../SampleBufferRendererLookaheadTests.swift  | 189 ++++++++++++++++++
 2 files changed, 284 insertions(+)
 create mode 100644 Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift

diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 22ec80131..1a9df1de3 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -61,6 +61,99 @@ final class SampleBufferRenderer: @unchecked Sendable {
         return reorderBuffer.count
     }
 
+    /// How many frame intervals of compressed video may be admitted ahead of the playback clock on
+    /// the FEL path. The gate runs BEFORE decode, so the decode + EL + compose latency (a few frames)
+    /// comes out of this budget: 5 left a displayed lead of ~0 and the layer dropped 9 frames/s
+    /// on device, against 0.5 s and no drops with no cap. A composed 4K frame costs ~25 MB, and
+    /// Apple's readiness gate alone allowed ~12 of them. Includes frames held in our reorder buffer, which is
+    /// `hardwareDecoderReorderDepth` deep on this path too: the held frames sit inside the window, so a
+    /// composer output pool sized from this cap does not grow with the reorder depth, but they
+    /// are frames the display layer has not been handed, so the lead it holds is that much smaller.
+    static let felVideoLookaheadFrames = 9
+    private var felFrameRate: Double?  // guarded by reorderLock; nil leaves non-FEL pacing unchanged
+    /// Highest compressed-packet PTS the gate has seen, and the largest amount any later packet's PTS
+    /// fell below it. Packets arrive in decode order, so with B-frames a packet's PTS runs ahead of the
+    /// frames still waiting to be displayed; measured on the real fixtures that lead is up to 7 frames
+    /// (a hierarchical-B GOP of 8), 2 to 4 on other clips, 0 on a third. The gate subtracts it so the cap bounds
+    /// display-order look-ahead rather than swinging with the position in the GOP. Guarded by
+    /// `reorderLock`; reset on flush.
+    private var gateMaxPacketPTS: Double?
+    private var gateReorderLead: Double = 0
+    /// HEVC's ceiling on `sps_max_num_reorder_pics`; a bigger PTS gap than this many frames is not reordering.
+    static let maxReorderPictures: Double = 16
+    /// Ceiling on the learned reorder lead, in frames. A hierarchical-B GOP of 8 makes a packet trail the
+    /// highest PTS seen by up to 7 frames in decode order (measured on a UHD Blu-ray FEL remux; other
+    /// clips measured 2 to 4); 8 leaves one frame to spare. It is unrelated to `hardwareDecoderReorderDepth`,
+    /// which sizes the buffer behind the decoder. Without a ceiling one backward timestamp glitch inside
+    /// the 16-picture window would raise the lead, and so the admitted look-ahead, for the whole session.
+    static let maxLearnedReorderFrames: Double = 8
+
+    /// Display-order PTS estimate for a packet in decode order. Pure; the state is passed in.
+    ///
+    /// A gap below the highest PTS seen that is larger than `maxLead` cannot be B-frame reordering
+    /// (HEVC allows at most 16 pictures of it), so it is a timestamp discontinuity: the highest PTS
+    /// restarts from this packet and the learned lead is left alone, instead of absorbing the jump
+    /// into the lead and switching the look-ahead cap off for the rest of the session.
+    ///
+    /// The learned lead is also capped at `maxLearnedLead`: a backward step inside the 16-picture
+    /// window that is still a glitch (a 12-frame one, say) would otherwise raise the lead for the whole
+    /// session, and with it the look-ahead the gate admits. The gate passes `maxLearnedReorderFrames`.
+    static func displayOrderPTS(packetPTS: Double, maxSeenPTS: Double?, reorderLead: Double,
+                                maxLead: Double = .infinity, maxLearnedLead: Double = .infinity)
+        -> (pts: Double, maxSeen: Double, lead: Double) {
+        let seen = maxSeenPTS ?? packetPTS
+        if seen - packetPTS > maxLead {
+            return (packetPTS - reorderLead, packetPTS, reorderLead)
+        }
+        let maxSeen = max(seen, packetPTS)
+        let lead = min(maxLearnedLead, max(reorderLead, maxSeen - packetPTS))
+        return (packetPTS - lead, maxSeen, lead)
+    }
+
+    func setFELLookahead(enabled: Bool, frameRate: Double?) {
+        reorderLock.lock()
+        // Container avg_frame_rate -> r_frame_rate; use 24 fps if both are unavailable.
+        felFrameRate = enabled ? (frameRate.flatMap { $0.isFinite && $0 > 0 ? $0 : nil } ?? 24) : nil
+        // Whatever was learned belonged to the previous stream or setting.
+        gateMaxPacketPTS = nil
+        gateReorderLead = 0
+        reorderLock.unlock()
+    }
+
+    /// Combined queue-readiness and look-ahead gate, called BEFORE decode so excess frames stay compressed.
+    func mayEnqueueVideoFrame(ptsSeconds: Double, clockSeconds: Double, clockArmed: Bool) -> Bool {
+        reorderLock.lock()
+        let rate = felFrameRate
+        let frontier = _newestEnqueuedPtsSeconds
+        var gatePTS = ptsSeconds.isFinite ? ptsSeconds : frontier ?? .nan
+        if rate != nil, ptsSeconds.isFinite {
+            let d = Self.displayOrderPTS(packetPTS: ptsSeconds, maxSeenPTS: gateMaxPacketPTS,
+                                         reorderLead: gateReorderLead,
+                                         maxLead: Self.maxReorderPictures / (rate ?? 24),
+                                         maxLearnedLead: Self.maxLearnedReorderFrames / (rate ?? 24))
+            gateMaxPacketPTS = d.maxSeen
+            gateReorderLead = d.lead
+            gatePTS = d.pts
+        }
+        reorderLock.unlock()
+        return Self.mayEnqueueAnotherFrame(
+            rendererReady: isReadyForMoreMediaData, felFrameRate: rate,
+            framePTS: gatePTS,
+            clockSeconds: clockSeconds, clockArmed: clockArmed)
+    }
+
+    /// Pure admission decision. Before clock arming there is no meaningful lead: preserve startup
+    /// and the existing broken-audio arming fallback. Late frames remain eligible for catch-up.
+    static func mayEnqueueAnotherFrame(
+        rendererReady: Bool, felFrameRate: Double?, framePTS: Double,
+        clockSeconds: Double, clockArmed: Bool
+    ) -> Bool {
+        guard rendererReady else { return false }
+        guard let rate = felFrameRate, rate.isFinite, rate > 0,
+              clockArmed, clockSeconds.isFinite, framePTS.isFinite else { return true }
+        return framePTS - clockSeconds <= Double(felVideoLookaheadFrames) / rate
+    }
+
     /// Drop frames before this PTS after a seek (prevents keyframe-to-target fast-forward). Cleared after the first passing frame.
     private var skipUntilPTS: CMTime?
 
@@ -435,6 +528,8 @@ final class SampleBufferRenderer: @unchecked Sendable {
         // backward seek would keep reporting the pre-seek timestamp and read as a cushion of
         // however far the seek travelled.
         _newestEnqueuedPtsSeconds = nil
+        gateMaxPacketPTS = nil
+        gateReorderLead = 0   // a seek relearns the lead from the new position
         // #311: everything reported before this point describes frames that are now gone.
         _flushGeneration = SampleBufferRenderer.flushGenerations.next()
         // Invalidate the format description cache; the next load() may open a stream with different colorimetry at the same resolution.
diff --git a/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift b/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
new file mode 100644
index 000000000..e7257b402
--- /dev/null
+++ b/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
@@ -0,0 +1,189 @@
+import Testing
+@testable import AetherEngine
+
+@Suite("SampleBufferRenderer FEL look-ahead")
+struct SampleBufferRendererLookaheadTests {
+    @Test("FEL admits the capped number of frame intervals, parks the next, and resumes as the clock advances",
+          arguments: [24.0, 24000.0 / 1001.0, 30.0, 60.0])
+    func frameCap(rate: Double) {
+        let n = Double(SampleBufferRenderer.felVideoLookaheadFrames)
+        #expect(SampleBufferRenderer.felVideoLookaheadFrames == 9)
+        #expect(mayEnqueue(rate: rate, pts: n / rate, clock: 0))
+        #expect(!mayEnqueue(rate: rate, pts: (n + 1) / rate, clock: 0))
+        #expect(mayEnqueue(rate: rate, pts: (n + 1) / rate, clock: 2 / rate))
+        #expect(mayEnqueue(rate: rate, pts: 9, clock: 10))
+    }
+
+    @Test("Non-FEL pacing depends only on queue readiness")
+    func nonFEL() {
+        #expect(mayEnqueue(rate: nil, pts: 100, clock: 0))
+        #expect(!mayEnqueue(rate: nil, pts: 0, clock: 0, ready: false))
+    }
+
+    @Test("FEL still respects Apple's queue readiness")
+    func queueFull() {
+        #expect(!mayEnqueue(rate: 24, pts: 0, clock: 0, ready: false))
+        #expect(!mayEnqueue(rate: 24, pts: 0, clock: 0, ready: false, armed: false))
+    }
+
+    @Test("Startup and unavailable timing do not prevent clock arming")
+    func startup() {
+        #expect(mayEnqueue(rate: 24, pts: 100, clock: 0, armed: false))
+        #expect(mayEnqueue(rate: 24, pts: 100, clock: .nan))
+        #expect(mayEnqueue(rate: 24, pts: .nan, clock: 0))
+    }
+
+    @Test("Lead uses the source axis, including after a backward seek")
+    func sourceAxis() {
+        #expect(mayEnqueue(rate: 24, pts: 100.3, clock: 100))   // 9 frames = 0.375 s
+        #expect(!mayEnqueue(rate: 24, pts: 100.4, clock: 100))
+        #expect(mayEnqueue(rate: 24, pts: 10.3, clock: 10))
+        #expect(!mayEnqueue(rate: 24, pts: 10.4, clock: 10))
+    }
+
+    @Test("Enabling FEL applies the cap and disabling it restores queue-only pacing")
+    @MainActor func configuration() throws {
+        let renderer = SampleBufferRenderer()
+        // The negative checks below only mean something while Apple's readiness gate is open.
+        try #require(renderer.isReadyForMoreMediaData)
+        renderer.setFELLookahead(enabled: true, frameRate: 60)
+        #expect(!renderer.mayEnqueueVideoFrame(ptsSeconds: 0.2, clockSeconds: 0, clockArmed: true))   // 9 frames at 60 fps = 0.15 s
+        renderer.setFELLookahead(enabled: false, frameRate: 60)
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: 100, clockSeconds: 0, clockArmed: true)
+                == renderer.isReadyForMoreMediaData)
+        renderer.setFELLookahead(enabled: true, frameRate: nil)
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: 0.37, clockSeconds: 0, clockArmed: true)
+                == renderer.isReadyForMoreMediaData)   // nil rate falls back to 24 fps: 0.375 s
+        #expect(!renderer.mayEnqueueVideoFrame(ptsSeconds: 0.4, clockSeconds: 0, clockArmed: true))
+    }
+
+    @Test("Decode-order packet PTS is corrected by the measured reorder lead")
+    func displayOrder() {
+        // I P B B: PTS 0, 4, 2, 1 (in frames) arriving in decode order, 3-deep lead.
+        var maxSeen: Double? = nil
+        var lead = 0.0
+        var out: [Double] = []
+        for pts in [0.0, 4, 2, 1, 8, 6, 5] {
+            let d = SampleBufferRenderer.displayOrderPTS(packetPTS: pts, maxSeenPTS: maxSeen, reorderLead: lead)
+            maxSeen = d.maxSeen; lead = d.lead; out.append(d.pts)
+        }
+        #expect(lead == 3)
+        // Once the lead is known, the reference packet (PTS 8) is gated as the frame 5 ahead it must wait behind.
+        #expect(out[4] == 5)
+        // Monotonic streams are untouched.
+        let m = SampleBufferRenderer.displayOrderPTS(packetPTS: 3, maxSeenPTS: 2, reorderLead: 0)
+        #expect(m.pts == 3 && m.lead == 0)
+    }
+
+    @Test("A glitch inside the reorder window cannot grow the learned lead past the reorder depth")
+    func glitchLeadIsBounded() {
+        let frame = 1.0 / 24
+        let bound = SampleBufferRenderer.maxLearnedReorderFrames * frame
+        let maxLead = SampleBufferRenderer.maxReorderPictures * frame
+        // One packet 12 frames below the highest PTS: inside the 16-picture window, so not a discontinuity.
+        let d = SampleBufferRenderer.displayOrderPTS(packetPTS: 100 - 12 * frame, maxSeenPTS: 100, reorderLead: 0,
+                                                     maxLead: maxLead, maxLearnedLead: bound)
+        #expect(abs(d.lead - bound) < 1e-9)
+        // The gated PTS is therefore at most `bound` below the packet's own: the admitted look-ahead
+        // grows by at most 8 frames, not 12 (at the 24 fps used here).
+        #expect(abs(d.pts - (100 - 12 * frame - bound)) < 1e-9)
+        // And a later, ordinary packet does not raise it further.
+        let n = SampleBufferRenderer.displayOrderPTS(packetPTS: 100.5, maxSeenPTS: d.maxSeen, reorderLead: d.lead,
+                                                     maxLead: maxLead, maxLearnedLead: bound)
+        #expect(abs(n.lead - bound) < 1e-9)
+    }
+
+    @Test("The gate itself stays bounded after a 12-frame backward glitch")
+    @MainActor func gateGlitchIsBounded() throws {
+        let renderer = SampleBufferRenderer()
+        try #require(renderer.isReadyForMoreMediaData)
+        renderer.setFELLookahead(enabled: true, frameRate: 24)
+        let frame = 1.0 / 24
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: 100, clockSeconds: 100, clockArmed: true))
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: 100 - 12 * frame, clockSeconds: 100, clockArmed: true))
+        // The glitch teaches 8 frames (the bound, not 12): 9 + 8 = 17 frames ahead is admitted, 18 is not.
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: 100 + 17 * frame, clockSeconds: 100, clockArmed: true))
+        #expect(!renderer.mayEnqueueVideoFrame(ptsSeconds: 100 + 18 * frame, clockSeconds: 100, clockArmed: true))
+    }
+
+    /// Teaches the gate a 4-frame lead with the highest packet PTS at 100, then runs `interrupt`. If the
+    /// lead or the highest PTS survived it, the first packet below 100 would be read as reordering and
+    /// the 10-frame check would pass (stale lead 4 or 3: gated 6 or 7 frames ahead); with both forgotten
+    /// it is the first packet of a new stream and a frame 10 ahead is refused.
+    @MainActor private func expectGateForgotten(after interrupt: (SampleBufferRenderer) -> Void) throws {
+        let renderer = SampleBufferRenderer()
+        try #require(renderer.isReadyForMoreMediaData)
+        let frame = 1.0 / 24
+        renderer.setFELLookahead(enabled: true, frameRate: 24)
+        _ = renderer.mayEnqueueVideoFrame(ptsSeconds: 100, clockSeconds: 100, clockArmed: true)
+        _ = renderer.mayEnqueueVideoFrame(ptsSeconds: 100 - 4 * frame, clockSeconds: 100, clockArmed: true)   // learns 4 frames
+        interrupt(renderer)
+        let clock = 100 - 3 * frame
+        // 3 frames below the old highest PTS: a stale highest PTS would teach a lead of 3 here.
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: clock, clockSeconds: clock, clockArmed: true))
+        #expect(renderer.mayEnqueueVideoFrame(ptsSeconds: clock + 9 * frame, clockSeconds: clock, clockArmed: true))
+        #expect(!renderer.mayEnqueueVideoFrame(ptsSeconds: clock + 10 * frame, clockSeconds: clock, clockArmed: true))
+    }
+
+    @Test("Disabling and re-enabling the look-ahead forgets the learned lead and highest PTS")
+    @MainActor func disableResetsGateState() throws {
+        try expectGateForgotten { renderer in
+            renderer.setFELLookahead(enabled: false, frameRate: nil)
+            renderer.setFELLookahead(enabled: true, frameRate: 24)
+        }
+    }
+
+    @Test("A seek (flush) forgets the learned lead and highest PTS")
+    @MainActor func flushResetsGateState() throws {
+        try expectGateForgotten { renderer in renderer.flush(removingDisplayedImage: false) }
+    }
+
+    @Test("A hierarchical-B GOP of 8 learns a lead of exactly 7 frames, and a glitch is bounded at 8")
+    func hierarchicalBLead() {
+        let frame = 1.0 / 24
+        let maxLead = SampleBufferRenderer.maxReorderPictures * frame
+        let cap = SampleBufferRenderer.maxLearnedReorderFrames * frame
+        // Decode order I0 P8 B4 B2 B1 B3 B6 B5 B7, repeated every 8 frames.
+        var maxSeen: Double? = nil
+        var lead = 0.0
+        for gop in 0..<4 {
+            for offset in [0, 8, 4, 2, 1, 3, 6, 5, 7] where gop == 0 || offset != 0 {
+                let d = SampleBufferRenderer.displayOrderPTS(packetPTS: Double(gop * 8 + offset) * frame, maxSeenPTS: maxSeen,
+                                                             reorderLead: lead, maxLead: maxLead, maxLearnedLead: cap)
+                maxSeen = d.maxSeen; lead = d.lead
+            }
+        }
+        #expect(abs(lead - 7 * frame) < 1e-9)
+        // A 12-frame glitch inside the window is bounded at 8.
+        let g = SampleBufferRenderer.displayOrderPTS(packetPTS: (maxSeen ?? 0) - 12 * frame, maxSeenPTS: maxSeen,
+                                                     reorderLead: lead, maxLead: maxLead, maxLearnedLead: cap)
+        #expect(abs(g.lead - 8 * frame) < 1e-9)
+    }
+
+    @Test("A backward timestamp jump is a discontinuity, not reorder lead")
+    func discontinuityDoesNotGrowLead() {
+        // 24 fps, B-frame lead of 3 frames already learned.
+        let frame = 1.0 / 24
+        var maxSeen: Double? = 100
+        var lead = 3 * frame
+        let maxLead = SampleBufferRenderer.maxReorderPictures * frame
+        // A packet 10 s below the highest PTS seen.
+        let d = SampleBufferRenderer.displayOrderPTS(packetPTS: 90, maxSeenPTS: maxSeen, reorderLead: lead, maxLead: maxLead)
+        maxSeen = d.maxSeen; lead = d.lead
+        #expect(lead == 3 * frame)
+        #expect(maxSeen == 90)
+        // The gate still refuses a frame a second ahead of the clock, which a lead of 10 s would not.
+        let next = SampleBufferRenderer.displayOrderPTS(packetPTS: 90.5, maxSeenPTS: maxSeen, reorderLead: lead, maxLead: maxLead)
+        #expect(!mayEnqueue(rate: 24, pts: next.pts, clock: 89))
+        // Ordinary reordering inside the limit still teaches the lead.
+        let r = SampleBufferRenderer.displayOrderPTS(packetPTS: 90.5 - 4 * frame, maxSeenPTS: next.maxSeen, reorderLead: lead, maxLead: maxLead)
+        #expect(abs(r.lead - 4 * frame) < 1e-9)
+    }
+
+    private func mayEnqueue(rate: Double?, pts: Double, clock: Double,
+                            ready: Bool = true, armed: Bool = true) -> Bool {
+        SampleBufferRenderer.mayEnqueueAnotherFrame(
+            rendererReady: ready, felFrameRate: rate, framePTS: pts,
+            clockSeconds: clock, clockArmed: armed)
+    }
+}

From cf93b6a07a4313fa1a1e4186df095392a1fd2200 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Tue, 13 Oct 2026 20:55:32 +0100
Subject: [PATCH 012/132] fix(io): the VOD packet cache covers audio packets
 that carry no duration

Matroska TrueHD reaches the software read-ahead with no packet duration and millisecond timestamps
that repeat (0.83 ms frames on a 1/1000 time base). SoftwarePacketCoverage.insert rejects a zero
duration, so audio coverage stayed empty, the combined A/V frontier was nil, and no seek ever hit
the packet cache: every seek, even back to a spot just played, refetched from the source.

Audio arrives in presentation order, so a duration-less packet now proves coverage up to the next
packet's timestamp, as long as the gap is at most 0.5 s (a larger one is a hole). Packets with a
duration are unchanged.

Apple TV 4K, 4K Matroska with TrueHD 7.1 over HTTP, 5 seeks per run: cache hits went from 0/10 to
5/5 in every run; AC-3 and video-only already hit 10/10. The new test fails without the change.
---
 CHANGELOG.md                                  |  5 ++
 .../Native/SoftwarePacketReadAhead.swift      | 28 +++++-
 ...arePacketReadAheadAudioCoverageTests.swift | 89 +++++++++++++++++++
 3 files changed, 121 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AetherEngineTests/SoftwarePacketReadAheadAudioCoverageTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c97a6da1d..7a42e8e3f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,11 @@ the public-API contract.
 
 ### Fixed
 
+- **Seeks on Matroska TrueHD titles hit the software packet cache again.** TrueHD packets carry no
+  duration and repeat their millisecond timestamps, so the cache never counted the audio as stored,
+  and every seek on the software path, even back to a spot just played, refetched from the source.
+  A duration-less audio packet now covers up to the next one's timestamp (gaps up to 0.5 s).
+
 - **A live GOP longer than the sealed target duration no longer breaks the playlist.** RFC 8216 keeps
   `TARGETDURATION` fixed for a playlist's life, so a later segment above it made the playlist invalid
   for AVPlayer (-12642). The engine now retires that playlist URL with its original target and an
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 3a7ee53d2..4a6f4bd68 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -75,6 +75,8 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     private var consumedVideoSeconds: Double?
     private var videoCoverage: SoftwarePacketCoverage
     private var audioCoverage: SoftwarePacketCoverage
+    /// Newest audio timestamp stored this epoch, for duration-less packets. See `insertAudioCoverageLocked`.
+    private var lastAudioPTS: Int64?
     private var presentationCoverage: SoftwareVideoPacketCoverage?
     private struct Keyframe {
         let seconds: Double
@@ -404,6 +406,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         ended = false; failure = nil
         videoCoverage.reset(); audioCoverage.reset(); presentationCoverage?.reset()
         storedVideoSeconds = nil; consumedVideoSeconds = nil
+        lastAudioPTS = nil
         keyframes.removeAll(keepingCapacity: true)
     }
 
@@ -520,7 +523,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                             if audioCoverage.isFull, let tick = playheadTick(audio) {
                                 audioCoverage.prune(before: tick)
                             }
-                            audioCoverage.insert(pts: packet.pts, duration: packet.duration)
+                            insertAudioCoverageLocked(pts: packet.pts, duration: packet.duration, stream: audio)
                         }
                     }
                     condition.broadcast()
@@ -531,6 +534,29 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         } catch { recordFailure(error, token: token) }
     }
 
+    /// Widest gap between two duration-less audio packets that still counts as contiguous. Real
+    /// frame spacing is 0.8 ms (TrueHD) to ~100 ms (long AAC/Vorbis frames); a larger gap is a hole.
+    static let maxAudioSuccessorGapSeconds = 0.5
+
+    /// Audio arrives in presentation order, so a packet without a duration still proves coverage up
+    /// to the next packet's timestamp. Matroska TrueHD is the case that needs it: no packet carries
+    /// a duration and the millisecond timestamps repeat (0.83 ms frames), so the duration model
+    /// rejected every packet, the A/V frontier stayed nil, and no seek ever hit the cache: each one,
+    /// even back to a spot just played, refetched from the source.
+    private func insertAudioCoverageLocked(pts: Int64, duration: Int64, stream: Stream) {
+        guard pts != Int64.min else { return }
+        let previous = lastAudioPTS
+        if previous.map({ pts > $0 }) ?? true { lastAudioPTS = pts }
+        if duration > 0 {
+            audioCoverage.insert(pts: pts, duration: duration)
+            return
+        }
+        guard let previous, pts > previous, stream.numerator > 0, stream.denominator > 0,
+              Double(pts - previous) * Double(stream.numerator) / Double(stream.denominator)
+                <= Self.maxAudioSuccessorGapSeconds else { return }
+        audioCoverage.insert(pts: previous, duration: pts - previous)
+    }
+
     private func shouldParkLocked() -> Bool {
         // One source record can cross the budget. A consumed active chunk cannot be deleted before
         // cursor rollover, so residency also includes bounded protected chunk slack (not an
diff --git a/Tests/AetherEngineTests/SoftwarePacketReadAheadAudioCoverageTests.swift b/Tests/AetherEngineTests/SoftwarePacketReadAheadAudioCoverageTests.swift
new file mode 100644
index 000000000..0fb0070c5
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwarePacketReadAheadAudioCoverageTests.swift
@@ -0,0 +1,89 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Matroska TrueHD reaches the read-ahead with no packet duration and millisecond timestamps that
+/// repeat (0.83 ms frames on a 1/1000 time base). The duration model rejected every such packet, so
+/// audio coverage stayed empty, the combined A/V frontier was nil, and no seek ever hit the packet
+/// cache: on the TV every TrueHD seek, even back to a spot just played, refetched from the source.
+@Suite("Software VOD read-ahead audio coverage without durations")
+struct SoftwarePacketReadAheadAudioCoverageTests {
+
+    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 }
+    }
+
+    /// 25 fps video (40 ticks) interleaved with 1200 Hz audio frames on a 1/1000 time base, 4 s,
+    /// then EOF. `audioGapAt` (seconds) drops one second of audio there.
+    private func runToEnd(audioDuration: Int64, audioGapAt: Double? = nil) throws -> SoftwarePacketReadAhead {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("readahead-audio-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+
+        var packets: [SoftwareStoredPacket] = []
+        var audioFrame = 0
+        for picture in 0..<100 {
+            let videoPTS = Int64(picture * 40)
+            packets.append(SoftwareStoredPacket(
+                pts: videoPTS, dts: videoPTS, duration: 40, position: 0, streamIndex: 0, flags: 0x1,
+                timeBaseNumerator: 1, timeBaseDenominator: 1000, bytes: Data(repeating: 7, count: 64),
+                sideData: []))
+            // 48 audio frames of 1/1200 s per 40 ms picture.
+            for _ in 0..<48 {
+                let seconds = Double(audioFrame) / 1200
+                audioFrame += 1
+                if let gap = audioGapAt, seconds >= gap, seconds < gap + 1 { continue }
+                let audioPTS = Int64((seconds * 1000).rounded(.down))
+                packets.append(SoftwareStoredPacket(
+                    pts: audioPTS, dts: audioPTS, duration: audioDuration, position: 0, streamIndex: 1,
+                    flags: 0x1, timeBaseNumerator: 1, timeBaseDenominator: 1000,
+                    bytes: Data(repeating: 3, count: 16), sideData: []))
+            }
+        }
+        let counter = Counter()
+        let all = packets
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64 * 1024, retainConsumed: true,
+                                              parentDirectory: root)
+        let source = SoftwarePacketReadAhead(
+            video: .init(index: 0, numerator: 1, denominator: 1000),
+            audio: .init(index: 1, numerator: 1, denominator: 1000),
+            byteBudget: 64 << 20, forwardSeconds: 100, initialSourceClock: 0, fifo: fifo
+        ) { _ in
+            let index = counter.next() - 1
+            return index < all.count ? all[index] : nil
+        }
+        source.start()
+        let deadline = Date().addingTimeInterval(10)
+        while !source.snapshot.sourceEnded, Date() < deadline { Thread.sleep(forTimeInterval: 0.02) }
+        #expect(source.snapshot.sourceEnded)
+        return source
+    }
+
+    private func seekHits(_ source: SoftwarePacketReadAhead, to seconds: Double) throws -> Bool {
+        let token = source.beginSeek(to: seconds)
+        return try source.prepareSeek(token, to: seconds)
+    }
+
+    @Test("duration-less, repeating-millisecond audio still makes a retained seek a cache hit")
+    func durationlessAudioHits() throws {
+        let source = try runToEnd(audioDuration: 0)
+        defer { source.close() }
+        #expect(try seekHits(source, to: 2.0))
+    }
+
+    @Test("audio with durations keeps hitting as before")
+    func durationAudioHits() throws {
+        let source = try runToEnd(audioDuration: 1)
+        defer { source.close() }
+        #expect(try seekHits(source, to: 2.0))
+    }
+
+    @Test("a real hole in duration-less audio is not bridged")
+    func audioHoleMisses() throws {
+        let source = try runToEnd(audioDuration: 0, audioGapAt: 1.5)
+        defer { source.close() }
+        #expect(try seekHits(source, to: 2.0) == false)
+    }
+}

From 936f8b2ff97afe48e4d2620bdd982629b442c7df Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Tue, 13 Oct 2026 21:00:51 +0100
Subject: [PATCH 013/132] fix(tvos): keep the software VOD packet cache in
 purgeable memory

The software path's compressed packet cache was a session file on disk. On an Apple TV 4K (A12)
appends to it took 100 to 600 ms while a download ran; the producer holds the store across an
append, the demux thread's reads waited behind it (and its own reads stalled up to a second), and
video it had already parked reached the decoder late. The layer dropped it.

On tvOS the store now lives in memory (SoftwarePacketMemoryFIFO behind a SoftwarePacketStore
protocol the disk FIFO also conforms to). Records keep the disk layout in chunks of purgeable VM:
unread data stays resident, a chunk the reader has finished is made volatile, so the kernel may
reclaim it and it stops counting against the footprint; a seek into reclaimed history is a cache
miss and refetches. Bounds: 96 MB forward, 128 MB of played history. AVPlayer keeps its
progressive-download cache in memory on tvOS as well. macOS, iOS and visionOS keep the disk store.

Apple TV 4K (A12), 4K Dolby Vision title over HTTP, 150 s soaks with 5 seeks: disk store 42/39/22
drops, memory store 0 to 3 in 8 of 9 runs (one run 26, not reproduced), no slow reads left. Peak
footprint ~655 MB against ~580 MB with the disk store.
---
 CHANGELOG.md                                  |   7 +
 Scripts/test-software-packet-read-ahead.sh    |   1 +
 .../Native/SoftwarePacketDiskFIFO.swift       |   9 +-
 .../Native/SoftwarePacketMemoryFIFO.swift     | 357 ++++++++++++++++++
 .../Native/SoftwarePacketReadAhead.swift      |   4 +-
 .../Native/SoftwarePacketStore.swift          |  17 +
 .../Native/SoftwarePlaybackHost.swift         |  54 ++-
 .../SoftwarePacketMemoryFIFOTests.swift       | 155 ++++++++
 docs/architecture.md                          |   9 +
 9 files changed, 594 insertions(+), 19 deletions(-)
 create mode 100644 Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
 create mode 100644 Sources/AetherEngine/Native/SoftwarePacketStore.swift
 create mode 100644 Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c97a6da1d..5a7630bd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,13 @@ the public-API contract.
 
 ### Fixed
 
+- **The software path no longer drops frames on tvOS while it downloads.** Its compressed packet
+  cache was a temporary disk file; on an Apple TV 4K appends to it took 100 to 600 ms while a download
+  ran, the demux thread waited behind them, and video it had already parked reached the decoder late.
+  On tvOS the cache now lives in purgeable memory (96 MB forward, up to 128 MB of reclaimable played
+  history), as AVPlayer's own cache does there: a 4K title's 150 s soak went from 22 to 42 drops to
+  0 to 3. macOS, iOS and visionOS keep the disk cache.
+
 - **A live GOP longer than the sealed target duration no longer breaks the playlist.** RFC 8216 keeps
   `TARGETDURATION` fixed for a playlist's life, so a later segment above it made the playlist invalid
   for AVPlayer (-12642). The engine now retires that playlist URL with its original target and an
diff --git a/Scripts/test-software-packet-read-ahead.sh b/Scripts/test-software-packet-read-ahead.sh
index 7488e7578..68195fdd0 100644
--- a/Scripts/test-software-packet-read-ahead.sh
+++ b/Scripts/test-software-packet-read-ahead.sh
@@ -13,6 +13,7 @@ xcrun swiftc \
   "$TASK_ROOT/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift" \
   "$TASK_ROOT/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift" \
   "$TASK_ROOT/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift" \
+  "$TASK_ROOT/Sources/AetherEngine/Native/SoftwarePacketStore.swift" \
   "$TASK_ROOT/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift" \
   "$TASK_ROOT/Sources/AetherEngine/Diagnostics/EngineLog.swift" \
   "$TASK_ROOT/Sources/AetherEngine/Diagnostics/LogRedaction.swift" \
diff --git a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
index 2126cbf78..3d8f79835 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
@@ -12,10 +12,11 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
     /// Clients can index keyframes by token without retaining packet payloads or forging offsets.
     struct Cursor: Hashable, Sendable {
         let chunkID: UInt64
-        fileprivate let generation: UUID
-        fileprivate let offset: UInt64
-        fileprivate let recordIndex: Int
-        fileprivate let payloadPrefix: Int
+        // Internal, not fileprivate: `SoftwarePacketMemoryFIFO` mints the same tokens.
+        let generation: UUID
+        let offset: UInt64
+        let recordIndex: Int
+        let payloadPrefix: Int
     }
 
     struct StaleSweepResult: Sendable {
diff --git a/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
new file mode 100644
index 000000000..9ddb45edf
--- /dev/null
+++ b/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
@@ -0,0 +1,357 @@
+import Darwin
+import Foundation
+
+/// The software VOD packet store in purgeable memory instead of session files: tvOS's store, the
+/// way AVPlayer keeps its progressive-download cache in memory there.
+///
+/// On an Apple TV 4K (A12) the disk store's appends took 100 to 600 ms while a download ran, and the
+/// consumer's reads stalled for up to a second behind them, on the demux thread: video it already had
+/// parked reached the decoder late and the layer dropped it. Here every operation is a copy under a
+/// lock.
+///
+/// Records use the disk layout (8-byte length, then payload) in chunks of purgeable VM. A chunk the
+/// consumer has finished with is history: it is made volatile, so it no longer counts against the
+/// footprint and the kernel may take it back under memory pressure. Moving the reader back onto
+/// history (a cached seek, a still walk) makes those chunks non-volatile again; one the kernel
+/// emptied is evicted together with everything older, so the read-ahead sees a cache miss and
+/// refetches. Unread data is never volatile.
+///
+/// `snapshot.diskByteCount` reports only non-volatile bytes, which is what the read-ahead's byte
+/// budget bounds (the forward window). History is bounded separately by `historyCapBytes`.
+final class SoftwarePacketMemoryFIFO: @unchecked Sendable {
+    private final class Chunk {
+        let id: UInt64
+        let base: UnsafeMutableRawPointer
+        let capacity: Int
+        var used = 0
+        private(set) var isVolatile = false
+
+        init(id: UInt64, capacity: Int) throws {
+            var address: vm_address_t = 0
+            let size = vm_size_t(capacity)
+            let kr = vm_allocate(mach_task_self_, &address, size, VM_FLAGS_ANYWHERE | VM_FLAGS_PURGABLE)
+            guard kr == KERN_SUCCESS, let base = UnsafeMutableRawPointer(bitPattern: UInt(address)) else {
+                throw SoftwarePacketDiskFIFO.Failure.capacityExceeded
+            }
+            self.id = id
+            self.base = base
+            self.capacity = capacity
+        }
+
+        deinit {
+            vm_deallocate(mach_task_self_, vm_address_t(UInt(bitPattern: base)), vm_size_t(capacity))
+        }
+
+        /// `vm_purgable_control` operations; the header macros carry a cast and do not import.
+        private static let setState: vm_purgable_t = 0
+
+        /// Returns false when making the chunk non-volatile found it already emptied by the kernel.
+        /// A chunk that cannot be made volatile simply stays resident.
+        @discardableResult
+        func setVolatile(_ volatile: Bool) -> Bool {
+            guard volatile != isVolatile else { return true }
+            var state: Int32 = volatile ? VM_PURGABLE_VOLATILE : VM_PURGABLE_NONVOLATILE
+            let kr = vm_purgable_control(mach_task_self_, vm_address_t(UInt(bitPattern: base)),
+                                         Self.setState, &state)
+            if volatile {
+                if kr == KERN_SUCCESS { isVolatile = true }
+                return true
+            }
+            isVolatile = false
+            // SET_STATE hands back the previous state.
+            return kr == KERN_SUCCESS && state != VM_PURGABLE_EMPTY
+        }
+
+        /// Empties the chunk now, as the kernel may once it is volatile. Tests only.
+        func purgeForTesting() {
+            var state: Int32 = VM_PURGABLE_EMPTY
+            vm_purgable_control(mach_task_self_, vm_address_t(UInt(bitPattern: base)), Self.setState, &state)
+        }
+    }
+
+    private let chunkTargetBytes: Int
+    private let historyCapBytes: Int
+    private let lock = NSLock()
+    /// Contiguous ids, oldest first. `chunks[i].id == oldestChunkID + i`.
+    private var chunks: [Chunk] = []
+    private var generation = UUID()
+    private var oldestChunkID: UInt64 = 0
+    private var headID: UInt64 = 0
+    private var headOffset = 0
+    private var recordCount = 0
+    private var payloadBytes = 0
+    private var writtenRecordCount = 0
+    private var writtenPayloadBytes = 0
+    private var isClosed = false
+    private var failure: (any Error)?
+    /// History chunks found emptied by the kernel. Diagnostics and tests.
+    private(set) var purgedChunks = 0
+
+    init(chunkTargetBytes: Int = 4 << 20, historyCapBytes: Int) {
+        let page = Int(getpagesize())
+        self.chunkTargetBytes = max(page, (chunkTargetBytes + page - 1) / page * page)
+        self.historyCapBytes = max(0, historyCapBytes)
+    }
+
+    var snapshot: SoftwarePacketDiskFIFO.Snapshot {
+        lock.lock()
+        defer { lock.unlock() }
+        return SoftwarePacketDiskFIFO.Snapshot(
+            count: recordCount, byteCount: payloadBytes, diskByteCount: nonVolatileBytesLocked(),
+            chunkCount: chunks.count, oldestRetainedChunkID: chunks.isEmpty ? nil : oldestChunkID,
+            isClosed: isClosed, hasFailure: failure != nil)
+    }
+
+    @discardableResult
+    func append(_ data: Data) throws -> SoftwarePacketDiskFIFO.Cursor {
+        lock.lock()
+        defer { lock.unlock() }
+        try requireUsable()
+        let recordBytes = data.count + 8
+        do {
+            if chunks.isEmpty || chunks[chunks.count - 1].capacity - chunks[chunks.count - 1].used < recordBytes {
+                let page = Int(getpagesize())
+                let capacity = max(chunkTargetBytes, (recordBytes + page - 1) / page * page)
+                let id = chunks.isEmpty ? oldestChunkID : chunks[chunks.count - 1].id + 1
+                if chunks.isEmpty { headID = id; headOffset = 0 }
+                chunks.append(try Chunk(id: id, capacity: capacity))
+            }
+        } catch {
+            failure = error
+            throw error
+        }
+        let tail = chunks[chunks.count - 1]
+        let cursor = SoftwarePacketDiskFIFO.Cursor(
+            chunkID: tail.id, generation: generation, offset: UInt64(tail.used),
+            recordIndex: writtenRecordCount, payloadPrefix: writtenPayloadBytes)
+        var length = UInt64(data.count).littleEndian
+        withUnsafeBytes(of: &length) { tail.base.advanced(by: tail.used).copyMemory(from: $0.baseAddress!, byteCount: 8) }
+        data.withUnsafeBytes { raw in
+            if let src = raw.baseAddress { tail.base.advanced(by: tail.used + 8).copyMemory(from: src, byteCount: data.count) }
+        }
+        tail.used += recordBytes
+        recordCount += 1
+        payloadBytes += data.count
+        writtenRecordCount += 1
+        writtenPayloadBytes += data.count
+        return cursor
+    }
+
+    func pop() throws -> Data? {
+        lock.lock()
+        defer { lock.unlock() }
+        try requireUsable()
+        guard recordCount > 0 else { return nil }
+        var head = try chunkLocked(headID)
+        if headOffset == head.used, headID < tailIDLocked {
+            head.setVolatile(true)
+            headID += 1
+            headOffset = 0
+            head = try chunkLocked(headID)
+        }
+        guard head.used - headOffset >= 8 else { throw fail(.corruptRecord) }
+        var length: UInt64 = 0
+        withUnsafeMutableBytes(of: &length) { $0.copyMemory(from: UnsafeRawBufferPointer(start: head.base.advanced(by: headOffset), count: 8)) }
+        length = UInt64(littleEndian: length)
+        guard length <= UInt64(payloadBytes), Int(length) <= head.used - headOffset - 8 else {
+            throw fail(.corruptRecord)
+        }
+        let data = Data(bytes: head.base.advanced(by: headOffset + 8), count: Int(length))
+        headOffset += 8 + Int(length)
+        recordCount -= 1
+        payloadBytes -= Int(length)
+        if headOffset == head.used, headID < tailIDLocked {
+            head.setVolatile(true)
+            headID += 1
+            headOffset = 0
+        }
+        return data
+    }
+
+    /// Moves only the consumer cursor. History between the cursor and the old head becomes unread
+    /// again and is made non-volatile; if the kernel emptied any of it the cursor is refused
+    /// (`invalidCursor`) and the read-ahead takes its normal uncached path.
+    func restore(to cursor: SoftwarePacketDiskFIFO.Cursor) throws {
+        lock.lock()
+        defer { lock.unlock() }
+        try requireUsable()
+        try validateLocked(cursor)
+        if cursor.chunkID < headID {
+            try reclaimLocked(from: cursor.chunkID, through: headID - 1)
+        } else {
+            // Forward within stored data: what the reader skips becomes history.
+            var id = headID
+            while id < cursor.chunkID { try chunkLocked(id).setVolatile(true); id += 1 }
+        }
+        let chunk = try chunkLocked(cursor.chunkID)
+        guard Int(cursor.offset) + 8 <= chunk.used else { throw SoftwarePacketDiskFIFO.Failure.invalidCursor }
+        headID = cursor.chunkID
+        headOffset = Int(cursor.offset)
+        recordCount = writtenRecordCount - cursor.recordIndex
+        payloadBytes = writtenPayloadBytes - cursor.payloadPrefix
+    }
+
+    /// AE#605 still walk. Copies one chunk's records at a time under the lock and visits them
+    /// outside it; a walk that raced a reset or an eviction throws `invalidCursor` after visiting,
+    /// like the disk store.
+    func readHistory(from cursor: SoftwarePacketDiskFIFO.Cursor, visit: (Data) throws -> Bool) throws {
+        lock.lock()
+        do {
+            try requireUsable()
+            try validateLocked(cursor)
+        } catch { lock.unlock(); throw error }
+        let walkGeneration = generation
+        lock.unlock()
+
+        var id = cursor.chunkID
+        var offset = Int(cursor.offset)
+        walk: while true {
+            lock.lock()
+            guard generation == walkGeneration, !isClosed, id >= oldestChunkID, id <= tailIDLocked else {
+                lock.unlock()
+                throw SoftwarePacketDiskFIFO.Failure.invalidCursor
+            }
+            let isLast = id == tailIDLocked
+            var records: [Data] = []
+            do {
+                let chunk = try chunkLocked(id)
+                let wasVolatile = chunk.isVolatile
+                if wasVolatile, !chunk.setVolatile(false) {
+                    // The catch below releases the lock.
+                    evictPurgedLocked(through: id)
+                    throw SoftwarePacketDiskFIFO.Failure.invalidCursor
+                }
+                while chunk.used - offset >= 8 {
+                    var length: UInt64 = 0
+                    withUnsafeMutableBytes(of: &length) { $0.copyMemory(from: UnsafeRawBufferPointer(start: chunk.base.advanced(by: offset), count: 8)) }
+                    length = UInt64(littleEndian: length)
+                    guard Int(length) <= chunk.used - offset - 8 else { throw SoftwarePacketDiskFIFO.Failure.corruptRecord }
+                    records.append(Data(bytes: chunk.base.advanced(by: offset + 8), count: Int(length)))
+                    offset += 8 + Int(length)
+                }
+                if wasVolatile, id < headID { chunk.setVolatile(true) }
+            } catch { lock.unlock(); throw error }
+            lock.unlock()
+            for record in records where try !visit(record) { break walk }
+            if isLast { break }
+            id += 1
+            offset = 0
+        }
+        lock.lock()
+        let stillValid = generation == walkGeneration && !isClosed
+        lock.unlock()
+        guard stillValid else { throw SoftwarePacketDiskFIFO.Failure.invalidCursor }
+    }
+
+    /// History beyond `historyCapBytes` is dropped, oldest first. The argument (the disk store's
+    /// residency budget) does not apply: in memory the read-ahead's budget bounds the non-volatile
+    /// forward window through `snapshot`. History the kernel emptied is not looked for here, since
+    /// this runs on every read and it costs nothing while it waits: `restore` and `readHistory`
+    /// find it when they reclaim a chunk, and the cap retires it in turn.
+    func trimConsumed(toByteBudget budget: Int) throws {
+        lock.lock()
+        defer { lock.unlock() }
+        try requireUsable()
+        var history = chunks.reduce(0) { $0 + ($1.id < headID ? $1.used : 0) }
+        while history > historyCapBytes, let oldest = chunks.first, oldest.id < headID {
+            chunks.removeFirst()
+            oldestChunkID = oldest.id + 1
+            history -= oldest.used
+        }
+    }
+
+    /// Empties every volatile history chunk now, as the kernel may under memory pressure. Tests only.
+    func purgeHistoryForTesting() {
+        lock.lock()
+        defer { lock.unlock() }
+        for chunk in chunks where chunk.isVolatile { chunk.purgeForTesting() }
+    }
+
+    func reset() throws {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !isClosed else { throw SoftwarePacketDiskFIFO.Failure.closed }
+        clearLocked()
+        failure = nil
+    }
+
+    func close() throws {
+        lock.lock()
+        defer { lock.unlock() }
+        isClosed = true
+        chunks.removeAll()
+    }
+
+    // MARK: - Private
+
+    private var tailIDLocked: UInt64 { chunks.last?.id ?? oldestChunkID }
+
+    private func chunkLocked(_ id: UInt64) throws -> Chunk {
+        guard id >= oldestChunkID, Int(id - oldestChunkID) < chunks.count else {
+            throw fail(.corruptRecord)
+        }
+        return chunks[Int(id - oldestChunkID)]
+    }
+
+    private func validateLocked(_ cursor: SoftwarePacketDiskFIFO.Cursor) throws {
+        guard cursor.generation == generation, !chunks.isEmpty,
+              cursor.chunkID >= oldestChunkID, cursor.chunkID <= tailIDLocked,
+              cursor.recordIndex >= 0, cursor.recordIndex < writtenRecordCount,
+              cursor.payloadPrefix >= 0, cursor.payloadPrefix <= writtenPayloadBytes else {
+            throw SoftwarePacketDiskFIFO.Failure.invalidCursor
+        }
+    }
+
+    /// Makes history chunks `first...last` non-volatile for re-reading. If the kernel emptied any,
+    /// everything up to the newest emptied one is evicted and the cursor is refused.
+    private func reclaimLocked(from first: UInt64, through last: UInt64) throws {
+        var newestPurged: UInt64?
+        var id = first
+        while id <= last {
+            if !(try chunkLocked(id).setVolatile(false)) { newestPurged = id }
+            id += 1
+        }
+        guard let newestPurged else { return }
+        evictPurgedLocked(through: newestPurged)
+        // What survived stays history until a later restore succeeds.
+        for chunk in chunks where chunk.id < headID { chunk.setVolatile(true) }
+        throw SoftwarePacketDiskFIFO.Failure.invalidCursor
+    }
+
+    /// Never evicts the reader's chunk or anything after it.
+    private func evictPurgedLocked(through id: UInt64) {
+        while let oldest = chunks.first, oldest.id <= id, oldest.id < headID {
+            chunks.removeFirst()
+            oldestChunkID = oldest.id + 1
+            purgedChunks += 1
+        }
+    }
+
+    private func nonVolatileBytesLocked() -> Int {
+        chunks.reduce(0) { $0 + ($1.isVolatile ? 0 : $1.used) }
+    }
+
+    private func requireUsable() throws {
+        guard !isClosed else { throw SoftwarePacketDiskFIFO.Failure.closed }
+        if let failure { throw failure }
+    }
+
+    private func fail(_ error: SoftwarePacketDiskFIFO.Failure) -> SoftwarePacketDiskFIFO.Failure {
+        failure = error
+        return error
+    }
+
+    private func clearLocked() {
+        chunks.removeAll()
+        generation = UUID()
+        oldestChunkID = 0
+        headID = 0
+        headOffset = 0
+        recordCount = 0
+        payloadBytes = 0
+        writtenRecordCount = 0
+        writtenPayloadBytes = 0
+    }
+}
+
+extension SoftwarePacketMemoryFIFO: SoftwarePacketStore {}
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 3a7ee53d2..6181e403c 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -28,7 +28,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     /// Never acquired by a main-thread API. Serializes reset with append/pop, including the
     /// generation check, so an old consumer cannot pop and discard the first NEW-generation packet.
     private let operations = NSLock()
-    private let fifo: SoftwarePacketDiskFIFO
+    private let fifo: any SoftwarePacketStore
     private let readSource: @Sendable (@Sendable () -> Bool) throws -> SoftwareStoredPacket?
     private let beforeConsumerOperation: (@Sendable () -> Void)?
     private let video: Stream
@@ -85,7 +85,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
 
     /// Construct only off-main: creating the FIFO touches the temporary volume.
     init(video: Stream, audio: Stream?, byteBudget: Int, forwardSeconds: Double,
-         initialSourceClock: Double, fifo: SoftwarePacketDiskFIFO,
+         initialSourceClock: Double, fifo: any SoftwarePacketStore,
          videoReorderDepth: Int? = nil,
          coverageRangeCap: Int = 4096,
          beforeConsumerOperation: (@Sendable () -> Void)? = nil,
diff --git a/Sources/AetherEngine/Native/SoftwarePacketStore.swift b/Sources/AetherEngine/Native/SoftwarePacketStore.swift
new file mode 100644
index 000000000..ee1375a8c
--- /dev/null
+++ b/Sources/AetherEngine/Native/SoftwarePacketStore.swift
@@ -0,0 +1,17 @@
+import Foundation
+
+/// The operations `SoftwarePacketReadAhead` needs from its packet store. `SoftwarePacketDiskFIFO`
+/// keeps the records in session files; `SoftwarePacketMemoryFIFO` keeps the same records in
+/// purgeable memory, which is what tvOS uses (see there).
+protocol SoftwarePacketStore: AnyObject, Sendable {
+    var snapshot: SoftwarePacketDiskFIFO.Snapshot { get }
+    @discardableResult func append(_ data: Data) throws -> SoftwarePacketDiskFIFO.Cursor
+    func pop() throws -> Data?
+    func restore(to cursor: SoftwarePacketDiskFIFO.Cursor) throws
+    func readHistory(from cursor: SoftwarePacketDiskFIFO.Cursor, visit: (Data) throws -> Bool) throws
+    func trimConsumed(toByteBudget budget: Int) throws
+    func reset() throws
+    func close() throws
+}
+
+extension SoftwarePacketDiskFIFO: SoftwarePacketStore {}
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 9817a8f6e..d69c4488f 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -23,6 +23,23 @@ final class SoftwarePlaybackHost {
         }
     }
 
+    /// The software VOD packet store's bounds on tvOS, which keeps it in purgeable memory
+    /// (`SoftwarePacketMemoryFIFO`) instead of session files; nil elsewhere, where the disk store and
+    /// the session retention budget apply. On an Apple TV 4K (A12) the disk store's appends took
+    /// 100 to 600 ms while a download ran and the demux thread stalled behind them, so video it had
+    /// parked was decoded late and dropped: 22 to 42 drops in a 150 s soak of a 4K title, against
+    /// 0 to 3 in 8 of 9 runs with the store in memory (one run had 26, not seen again). The forward window is 96 MB (about 8 s of a 95 Mbit/s
+    /// title, on top of the forward-seconds limit); played history up to 128 MB stays volatile, so
+    /// the kernel may take it back and a seek into what it took refetches. Peak footprint of a 4K
+    /// FEL session on the A12: ~655 MB against ~580 MB with the disk store.
+    nonisolated static let memoryPacketStoreBudget: (forwardBytes: Int, historyBytes: Int)? = {
+        #if os(tvOS)
+        return (forwardBytes: 96 << 20, historyBytes: 128 << 20)
+        #else
+        return nil
+        #endif
+    }()
+
 
     // MARK: - Published state (mirrors NativeAVPlayerHost surface)
 
@@ -1110,19 +1127,30 @@ final class SoftwarePlaybackHost {
                 } : nil
             let initialSourceClock = initialClockTime.seconds
             let videoReorderDepth = Self.presentationReorderDepth(codecID: vCodecID)
-            let cacheResult = await BlockingWork.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 cacheResult = await BlockingWork.detached(priority: .utility) { () throws -> (SoftwarePacketReadAhead, RetentionClaims.Claim?)? in
                 let segments = HLSVideoEngine.clampedForwardWindow(forwardBufferSegments)
-                let capRelaxed = HLSVideoEngine.retentionCapRelaxed(forwardWindowSegments: segments)
-                let claim = RetentionClaims.shared.claim(volumeAvailableBytes: available) {
-                    HLSVideoEngine.sessionRetentionBudgetBytes(volumeAvailableBytes: $0, capRelaxed: capRelaxed)
+                let fifo: any SoftwarePacketStore
+                let bytes: Int
+                var claim: RetentionClaims.Claim?
+                if let memory = Self.memoryPacketStoreBudget {
+                    bytes = memory.forwardBytes
+                    fifo = SoftwarePacketMemoryFIFO(historyCapBytes: memory.historyBytes)
+                    EngineLog.emit("[SWHost] packet cache in memory: forward \(memory.forwardBytes >> 20) MB, "
+                                   + "history \(memory.historyBytes >> 20) MB", category: .swPlayback)
+                } else {
+                    let temp = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+                    let available = (try? temp.resourceValues(forKeys: [.volumeAvailableCapacityKey]))?
+                        .volumeAvailableCapacity.map(Int64.init)
+                    let capRelaxed = HLSVideoEngine.retentionCapRelaxed(forwardWindowSegments: segments)
+                    let diskClaim = RetentionClaims.shared.claim(volumeAvailableBytes: available) {
+                        HLSVideoEngine.sessionRetentionBudgetBytes(volumeAvailableBytes: $0, capRelaxed: capRelaxed)
+                    }
+                    bytes = diskClaim.bytes
+                    guard bytes > 0 else { return nil }
+                    fifo = try SoftwarePacketDiskFIFO(
+                        chunkTargetBytes: min(4 << 20, max(8, bytes)), retainConsumed: true)
+                    claim = diskClaim
                 }
-                let bytes = claim.bytes
-                guard bytes > 0 else { return nil }
-                let fifo = try SoftwarePacketDiskFIFO(
-                    chunkTargetBytes: min(4 << 20, max(8, bytes)), retainConsumed: true)
                 let readAhead = SoftwarePacketReadAhead(
                     video: video, audio: audio, byteBudget: bytes,
                     forwardSeconds: Double(segments) * 4,
@@ -1133,14 +1161,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 }
+                claim?.track { [weak readAhead] in readAhead?.snapshot.residentBytes ?? 0 }
                 return (readAhead, claim)
             }.result
             let readAhead: SoftwarePacketReadAhead?
             switch cacheResult {
             case .success(let cache):
                 readAhead = cache?.0
-                if !stopRequested, let claim = cache?.1 { retentionClaims.append(claim) }
+                if !stopRequested, let claim = cache?.1 ?? nil { 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.
diff --git a/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift b/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift
new file mode 100644
index 000000000..d2cf2b47e
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift
@@ -0,0 +1,155 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// The purgeable-memory packet store (tvOS's software VOD packet store) must behave like the
+/// disk store for everything the read-ahead relies on: FIFO order across chunks, cursors that
+/// restore backwards and forwards, the still walk, and history that is bounded and evictable.
+@Suite("Software packet memory FIFO")
+struct SoftwarePacketMemoryFIFOTests {
+
+    /// Records of 1000 bytes filled with their index, so a read can be checked by content.
+    private func record(_ i: Int) -> Data { Data(repeating: UInt8(i & 0xff), count: 1000) }
+
+    /// Page-sized chunks (16 KiB on arm64) hold 16 records each.
+    private func filled(_ count: Int, historyCap: Int = .max) throws
+        -> (SoftwarePacketMemoryFIFO, [SoftwarePacketDiskFIFO.Cursor]) {
+        let fifo = SoftwarePacketMemoryFIFO(chunkTargetBytes: 1, historyCapBytes: historyCap)
+        var cursors: [SoftwarePacketDiskFIFO.Cursor] = []
+        for i in 0..<count { cursors.append(try fifo.append(record(i))) }
+        return (fifo, cursors)
+    }
+
+    @Test("pops every record in order across chunk boundaries")
+    func fifoOrder() throws {
+        let (fifo, _) = try filled(100)
+        #expect(fifo.snapshot.chunkCount > 1)
+        for i in 0..<100 { #expect(try fifo.pop() == record(i)) }
+        #expect(try fifo.pop() == nil)
+        #expect(fifo.snapshot.count == 0)
+    }
+
+    @Test("consumed chunks leave the non-volatile byte count, unread ones stay in it")
+    func consumedHistoryIsNotResident() throws {
+        let (fifo, _) = try filled(100)
+        let before = fifo.snapshot.diskByteCount
+        for _ in 0..<80 { _ = try fifo.pop() }
+        let after = fifo.snapshot.diskByteCount
+        #expect(after < before)
+        #expect(after >= 20 * 1008)
+    }
+
+    @Test("a cursor behind the reader restores and re-reads the same records")
+    func restoreBackward() throws {
+        let (fifo, cursors) = try filled(100)
+        for _ in 0..<90 { _ = try fifo.pop() }
+        try fifo.restore(to: cursors[10])
+        #expect(fifo.snapshot.count == 90)
+        for i in 10..<100 { #expect(try fifo.pop() == record(i)) }
+    }
+
+    @Test("a cursor ahead of the reader skips forward")
+    func restoreForward() throws {
+        let (fifo, cursors) = try filled(100)
+        try fifo.restore(to: cursors[70])
+        #expect(fifo.snapshot.count == 30)
+        #expect(try fifo.pop() == record(70))
+    }
+
+    @Test("the still walk visits history without moving the reader")
+    func readHistory() throws {
+        let (fifo, cursors) = try filled(100)
+        for _ in 0..<60 { _ = try fifo.pop() }
+        var seen: [Data] = []
+        try fifo.readHistory(from: cursors[20]) { seen.append($0); return seen.count < 30 }
+        #expect(seen == (20..<50).map(record))
+        #expect(try fifo.pop() == record(60))
+    }
+
+    @Test("history over the cap is dropped and its cursors become cache misses")
+    func historyCap() throws {
+        let (fifo, cursors) = try filled(200, historyCap: 40_000)
+        for _ in 0..<190 { _ = try fifo.pop() }
+        try fifo.trimConsumed(toByteBudget: 0)
+        let oldest = try #require(fifo.snapshot.oldestRetainedChunkID)
+        #expect(oldest > cursors[0].chunkID)
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) { try fifo.restore(to: cursors[0]) }
+        // Recent history is still there.
+        try fifo.restore(to: cursors[185])
+        #expect(try fifo.pop() == record(185))
+    }
+
+    @Test("history the kernel emptied is a cache miss, and the store stays usable")
+    func purgedHistoryRestore() throws {
+        let (fifo, cursors) = try filled(100)
+        for _ in 0..<90 { _ = try fifo.pop() }
+        fifo.purgeHistoryForTesting()
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) { try fifo.restore(to: cursors[10]) }
+        #expect(fifo.purgedChunks > 0)
+        // The reader did not move and unread data was never volatile.
+        for i in 90..<100 { #expect(try fifo.pop() == record(i)) }
+        try fifo.append(record(100))
+        #expect(try fifo.pop() == record(100))
+    }
+
+    @Test("a still walk into emptied history is refused and releases the store")
+    func purgedHistoryWalk() async throws {
+        let (fifo, cursors) = try filled(100)
+        for _ in 0..<90 { _ = try fifo.pop() }
+        fifo.purgeHistoryForTesting()
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) {
+            try fifo.readHistory(from: cursors[10]) { _ in true }
+        }
+        // A lock left held (or released twice) by the refusal would hang or trap here, so the next
+        // operation runs on its own thread.
+        let popped = await withCheckedContinuation { (done: CheckedContinuation<Data?, Never>) in
+            Thread.detachNewThread { done.resume(returning: try? fifo.pop()) }
+        }
+        #expect(popped == record(90))
+    }
+
+    @Test("reset invalidates old cursors and starts empty")
+    func reset() throws {
+        let (fifo, cursors) = try filled(50)
+        try fifo.reset()
+        #expect(fifo.snapshot.count == 0)
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) { try fifo.restore(to: cursors[0]) }
+        try fifo.append(record(7))
+        #expect(try fifo.pop() == record(7))
+    }
+
+    @Test("the read-ahead plays from the memory store and a backward seek into history hits")
+    func readAheadSeekBackHits() throws {
+        // 25 fps video, every picture a keyframe, 4 s, then EOF. No audio.
+        let packets = (0..<100).map { i in
+            SoftwareStoredPacket(
+                pts: Int64(i * 40), dts: Int64(i * 40), duration: 40, position: 0, streamIndex: 0,
+                flags: 0x1, timeBaseNumerator: 1, timeBaseDenominator: 1000,
+                bytes: Data(repeating: UInt8(i), count: 2000), sideData: [])
+        }
+        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 }
+        }
+        let counter = Counter()
+        let source = SoftwarePacketReadAhead(
+            video: .init(index: 0, numerator: 1, denominator: 1000), audio: nil,
+            byteBudget: 64 << 20, forwardSeconds: 100, initialSourceClock: 0,
+            fifo: SoftwarePacketMemoryFIFO(chunkTargetBytes: 16 * 1024, historyCapBytes: 64 << 20)
+        ) { _ in
+            let index = counter.next() - 1
+            return index < packets.count ? packets[index] : nil
+        }
+        defer { source.close() }
+        source.start()
+        // Play 3 s: those chunks become volatile history.
+        for i in 0..<75 { #expect(try source.read()?.pts == Int64(i * 40)) }
+        let token = source.beginSeek(to: 1.0)
+        #expect(try source.prepareSeek(token, to: 1.0))
+        source.endSeek(token, sourceClock: 1.0)
+        let first = try #require(try source.read())
+        #expect(first.pts <= 1000)
+        #expect(first.bytes == packets[Int(first.pts / 40)].bytes)
+    }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index 51cadd49a..069e541fc 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -238,6 +238,15 @@ cleanup uses session leases without following symlinks or deleting live stores.
 If creating the store fails, the original direct playback loop remains available.
 Runtime cache corruption is a reported playback failure, not silently skipped data.
 
+On tvOS the same records live in purgeable memory instead
+(`SoftwarePacketMemoryFIFO`, bounds in `SoftwarePlaybackHost.memoryPacketStoreBudget`):
+a 96 MB forward window, and up to 128 MB of played history kept volatile, so the
+kernel may reclaim it under pressure and a seek into reclaimed history is a normal
+cache miss. On an Apple TV 4K the disk store's appends took 100 to 600 ms while a
+download ran, the demux thread stalled behind them, and video it had already
+parked reached the decoder late; AVPlayer keeps its progressive-download cache in
+memory on tvOS too. No session files and no disk retention claim are made there.
+
 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 and HEVC use a bounded presentation

From e1d328505aecf5ebe3587465da40ec5b3eedc472 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:34:29 +0100
Subject: [PATCH 014/132] feat(dovi): dual-layer Profile 7 FEL decoder (not
 routed)

DualLayerVideoDecoder: the decoder half of the dual-layer route. It splits
each packet into base layer, enhancement layer and RPU
(DoviRpuConverter.separateDualLayers), decodes both layers on VideoToolbox
through two HardwareVideoDecoder sessions, pairs them by HEVC picture
order, composes with DoviFelComposer and delivers the frames in decode
order with the Profile 8.1 RPU attached per frame.

- Pairing: DualLayerPictureAlignment restamps each enhancement-layer
  packet with the time of the base picture in the same display slot, so an
  enhancement layer coded with B-frames over a base layer without them is
  no longer paired with a neighbouring frame's residual. A layer keeps
  access-unit pairing until its next sequence-opening IRAP after a seek.
- Bounded memory: base-layer skew K = 3 frames, at most 10 waiting
  enhancement frames, output pool 15 plus a reserve of 3. A late or broken
  EL falls back to the base layer for that frame.
- Seeks: a seek flushes every stage. A stale EL is never paired with a
  post-seek base layer and a stale BL is never delivered. The composer's
  output pool is kept across the flush instead of being dropped (it made
  the frames after a seek allocate a second pool beside the buffers the
  renderer still held): peak footprint on a 12-seek run of one test clip
  went from 674 MB to 500 MB. The pool is dropped on close.
- HardwareVideoDecoder gains an opt-in no-copy block source and a
  parameter-set open for the enhancement layer; both are off for every
  existing caller. FelResidualMeasure (the AETHER_FEL_MEASURE diagnostic,
  off by default) is here because the decoder calls it.

Nothing constructs the decoder yet: no host code selects it until the route
PR, so no source plays differently after this one. Public API: none. Not in
this PR: the capability gate, the preferDualLayerDolbyVision flag, host
wiring, dolby-vision-fel.md.

Tests: decoder, GPU slot wait, seek realignment (flush of both sessions and
the composer, stale EL not composed, waiting BL dropped at the seek, seek
during an in-flight composition), stream classification and packet balance,
CPU model, output-pool-across-flush, real-clip tests (gated on
DV_FEL_TESTS_DIR, skipped without), and a subtitle compositor test that the
Dolby Vision attachments survive compositing.
---
 CHANGELOG.md                                  |    5 +
 .../Decoder/DualLayerVideoDecoder.swift       | 1706 +++++++++++
 .../Decoder/HardwareVideoDecoder.swift        |  283 +-
 .../Decoder/VideoDecoderTypes.swift           |   11 +
 .../Diagnostics/FelResidualMeasure.swift      |  105 +
 .../AetherEngineTests/DoviCpuModelTests.swift |  440 +++
 .../DoviFelRealFileTests.swift                |  395 +++
 .../DoviRealFileExportTests.swift             |   96 +
 .../DualLayerGpuSlotWaitTests.swift           |  312 ++
 .../DualLayerSeekRealignmentTests.swift       |  307 ++
 .../DualLayerStreamClassificationTests.swift  |  240 ++
 .../DualLayerVideoDecoderTests.swift          | 2535 +++++++++++++++++
 .../SubtitleFrameCompositorTests.swift        |   33 +
 docs/architecture.md                          |    1 +
 14 files changed, 6442 insertions(+), 27 deletions(-)
 create mode 100644 Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
 create mode 100644 Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
 create mode 100644 Tests/AetherEngineTests/DoviCpuModelTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviRealFileExportTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 189c9f9fc..37b879c40 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,11 @@ the public-API contract.
 
 ## [Unreleased]
 
+### Added
+
+- **`AETHER_FEL_MEASURE` reports the signed FEL-minus-MEL mean per plane and luma band.** The diagnostic composes every Nth frame a second time with the residual off and compares the two; the signed mean says whether the residual brightens or darkens, which the absolute difference could not. It runs one sample at a time and skips a frame that arrives while one is in flight. Off by default; it is an environment-variable diagnostic, not API.
+- **The dual-layer decoder pairs the two layers by picture order.** `DualLayerPictureAlignment` derives each layer's display slot from its POC (`HEVCPictureOrderCount`, no decoding) and stamps each enhancement-layer packet with the time of the base-layer picture in the same slot, so a stream whose enhancement layer is coded with B-frames over a base layer without them pairs the right pictures. A stream whose layers share one GOP keeps every packet's own time. After a seek a layer pairs by access unit until its next sequence-opening IRAP.
+
 ### Fixed
 
 - **A live GOP longer than the sealed target duration no longer breaks the playlist.** RFC 8216 keeps
diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
new file mode 100644
index 000000000..1d9f7e94d
--- /dev/null
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -0,0 +1,1706 @@
+import Foundation
+import CoreMedia
+import CoreVideo
+import VideoToolbox
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+
+/// Side data that travels with a waiting base-layer frame (dolby-vision-fel.md
+/// §5.3). The base-layer queue stores only buffer + PTS by itself, so a
+/// frame whose enhancement layer arrives last would otherwise reach `onFrame`
+/// with `hdr10Data` dropped; carrying it here makes delivery independent of
+/// arrival order. `dmNAL` is the Profile 8.1 display-metadata NAL cached for
+/// this frame's PTS, resolved once at base-layer arrival for the same reason:
+/// `OrderedDelivery.emit` runs on the delivery queue and does not reach
+/// into the decoder's frame state (`dmRpuCache`, the queues) itself. `HardwareVideoDecoder` passes
+/// `hdr10Data: nil` today (latent), so that field is unused in practice, with
+/// room for params if they migrate here too.
+private struct FrameSideData: Sendable {
+    let hdr10Data: Data?
+    let dmNAL: [UInt8]?
+}
+
+/// What `DualLayerVideoDecoder` needs from its composer.
+///
+/// Splitting the GPU-slot wait (`acquireSlot`) from encode-and-commit
+/// (`composeAsyncWithAcquiredSlot`) is what lets the decoder decide under its
+/// lock and block outside it (dolby-vision-fel.md §5.5, §5.6). `DoviFelComposer` is the
+/// production implementation; tests inject a gated fake through
+/// `DualLayerVideoDecoder(composer:)`.
+protocol FelComposing: Sendable {
+    func composeAsync(
+        baseBuffer: CVPixelBuffer,
+        enhancementBuffer: CVPixelBuffer,
+        params: DoviMetalParams,
+        frameIndex: UInt32,
+        completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+    )
+    func composeAsyncWithAcquiredSlot(
+        baseBuffer: CVPixelBuffer,
+        enhancementBuffer: CVPixelBuffer,
+        params: DoviMetalParams,
+        frameIndex: UInt32,
+        completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+    )
+    func acquireSlot()
+    func releaseSlot()
+    func flush()
+    func releaseOutputPool()
+    func flushTextureCache()
+    func takePeakSlotsInUse() -> Int
+    var allocatedPoolBuffers: Int { get }
+    var meanGPUTimeMs: Double? { get }
+}
+
+extension FelComposing {
+    func releaseOutputPool() {}
+    func flushTextureCache() {}
+    func takePeakSlotsInUse() -> Int { 0 }
+    var allocatedPoolBuffers: Int { 0 }
+    var meanGPUTimeMs: Double? { nil }
+}
+
+extension DoviFelComposer: FelComposing {}
+
+/// What `DualLayerVideoDecoder` needs from each single-layer VideoToolbox
+/// decoder (dolby-vision-fel.md §5.8).
+///
+/// A small protocol over `HardwareVideoDecoder` so tests can inject a fake
+/// that emits a frame from inside `flush()`, proving pre-seek frames drained
+/// there never reach delivery.
+protocol SingleLayerVideoDecoder: VideoDecodingPipeline {
+    /// Opens a decoder session from raw HEVC parameter sets (VPS, SPS, PPS),
+    /// used for both layers when they arrive in-band.
+    func open(
+        parameterSets: [[UInt8]],
+        timeBase: AVRational,
+        onFrame: @escaping DecodedFrameHandler
+    ) throws
+
+    /// Moves the decoder's feed epoch to its owner's. Called from inside the owner's `flush()`
+    /// critical section, so it must not take any lock a VideoToolbox callback can be waiting behind.
+    func adoptFeedEpoch(_ epoch: UInt64)
+    /// The flush the owner makes after `adoptFeedEpoch`: drains and discontinues the session without
+    /// moving the epoch again.
+    func flushKeepingEpoch()
+}
+
+extension SingleLayerVideoDecoder {
+    func adoptFeedEpoch(_ epoch: UInt64) {}
+    func flushKeepingEpoch() { flush() }
+}
+
+extension HardwareVideoDecoder: SingleLayerVideoDecoder {}
+
+/// Video decoding pipeline that transparently coordinates dual VideoToolbox HEVC decoders
+/// (base layer, typically 4K, plus an enhancement layer, typically 1080p) and reconstructs the 12-bit master on Apple GPU
+/// using `DoviFelComposer`. Falls back smoothly to single-layer BL if no EL is present (MEL / P8.1).
+final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
+
+    // The callback itself is owned by `orderedDelivery`, not this
+    // decoder, so a call already queued for delivery when the host reassigns
+    // it (or `close()` clears it) is ordered against that write rather than
+    // racing it under a lock the delivery path no longer takes.
+    var onFrame: DecodedFrameHandler? {
+        get { orderedDelivery.currentOnFrame }
+        set { orderedDelivery.setOnFrame(newValue) }
+    }
+
+    // Set once by the host before `open()`; guarded by `lock` so a late
+    // reassignment cannot race a VideoToolbox callback reading it.
+    var onFirstHDR10PlusDetected: (@Sendable () -> Void)? {
+        get { lock.lock(); defer { lock.unlock() }; return _onFirstHDR10PlusDetected }
+        set { lock.lock(); _onFirstHDR10PlusDetected = newValue; lock.unlock() }
+    }
+    private var _onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+    var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)? {
+        get { lock.lock(); defer { lock.unlock() }; return _onA53Captions }
+        set { lock.lock(); _onA53Captions = newValue; lock.unlock() }
+    }
+    private var _onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+    /// AE#658: the composed display buffer's format, reported on the first frame and when it changes.
+    var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)? {
+        get { lock.lock(); defer { lock.unlock() }; return _onDecodedFormat }
+        set { lock.lock(); _onDecodedFormat = newValue; lock.unlock() }
+    }
+    private var _onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+    private var declaredFormat: (color: ColorDescription, codecID: AVCodecID, profile: Int32)?  // guarded by `lock`
+    private var reportedPixelBufferType: OSType = 0  // guarded by `lock`
+
+    /// What `onFrame` is handed is the composed buffer, so that buffer's type is the decoded format and
+    /// its colour is what the stream declares. Called on the delivery queue; it takes `lock` for a moment, which is
+    /// safe because nothing holds `lock` while waiting on that queue (`flush()` waits only after unlocking).
+    private func reportDecodedFormat(_ buffer: CVPixelBuffer) {
+        let type = CVPixelBufferGetPixelFormatType(buffer)
+        lock.lock()
+        let handler = _onDecodedFormat
+        let declared = declaredFormat
+        let isNew = type != reportedPixelBufferType
+        if handler != nil, isNew { reportedPixelBufferType = type }
+        lock.unlock()
+        guard let handler, isNew, let declared else { return }
+        handler(DecodedVideoFormat(
+            frame: VideoStreamFormat(
+                pixelFormat: DecodedVideoFormat.libavPixelFormat(forPixelBufferType: type),
+                declaredBitDepth: 0,
+                color: declared.color,
+                codecID: declared.codecID,
+                profile: declared.profile),
+            pixelBufferFormat: DecodedVideoFormat.fourCC(type)))
+    }
+
+    var skipUntilPTS: CMTime? {
+        get { lock.lock(); defer { lock.unlock() }; return _skipUntilPTS }
+        set {
+            // Lock ordering: `HardwareVideoDecoder.skipUntilPTS` takes that
+            // decoder's own `skipLock`, while its output callback takes `skipLock`
+            // and then re-enters this decoder's `lock` via the frame handlers.
+            // Setting the sub-decoders while holding `lock` would nest the locks
+            // in the opposite order, so capture the pointers and fan out outside.
+            lock.lock()
+            _skipUntilPTS = newValue
+            let primary = primaryDecoder
+            let enhancement = enhancementDecoder
+            lock.unlock()
+            primary.skipUntilPTS = newValue
+            enhancement?.skipUntilPTS = newValue
+        }
+    }
+    private var _skipUntilPTS: CMTime?
+
+    /// The primary decoder's own methods are internally synchronized
+    /// (`HardwareVideoDecoder.lock` / `skipLock`); it is safe to call without holding
+    /// this decoder's `lock`, and callers must do so to preserve the lock ordering
+    /// above. `composer` is immutable and `Sendable`.
+    private let primaryDecoder: any SingleLayerVideoDecoder
+    /// Guarded by `lock`. Captured into a local before any `decode`/`flush`/`close`
+    /// call, which runs after the lock is released; swapped out under the lock and
+    /// closed after releasing it in `flush()`/`close()`.
+    private var enhancementDecoder: (any SingleLayerVideoDecoder)?
+    private let composer: (any FelComposing)?
+
+    /// Every outgoing frame — composed or bypassed — reaches the host through
+    /// here (dolby-vision-fel.md §5.7). Owned by the decoder, not the composer.
+    /// `DoviFelComposer` still keeps a small relay queue of its own
+    /// (`deliveryQueue`) that a composed frame's completion hops through
+    /// before calling `fulfil`. It is a §4.3 firewall against Metal's completion handler ever blocking on
+    /// something downstream (`DoviComposeAsyncTests.
+    /// doesNotDeadlockAgainstTheCallersLock` reproduces the deadlock shape
+    /// removing it would reopen), not a second ordering mechanism — `fulfil`
+    /// reorders every frame by ticket regardless of which queue called it,
+    /// so a bypass arriving directly from a VideoToolbox thread and a
+    /// composition arriving via that relay hop are indistinguishable once
+    /// they reach `orderedDelivery`. See `OrderedDelivery`'s own type doc
+    /// and dolby-vision-fel.md §5.7, §5.9 for the full justification. Sized off this
+    /// decoder's own bounds (`DoviFelComposer.maxFramesInFlight`,
+    /// `Self.maxLayerSkewFrames`) so the stall guard's threshold tracks them
+    /// if either changes.
+    private let orderedDelivery = OrderedDelivery(
+        maxFramesInFlight: DoviFelComposer.maxFramesInFlight,
+        maxLayerSkew: DualLayerVideoDecoder.maxLayerSkewFrames
+    )
+
+    /// Production use: builds the Metal composer (nil when there is no Metal
+    /// device, in which case every frame bypasses). Tests inject a fake to
+    /// control the GPU-slot wait without a GPU.
+    init(composer: (any FelComposing)? = DoviFelComposer()) {
+        self.composer = composer
+        let primary = HardwareVideoDecoder()
+        primary.useCustomBlockSource = true
+        self.primaryDecoder = primary
+    }
+
+    /// Test seam: inject fake single-layer decoders, e.g. ones that
+    /// emit a pre-seek frame from inside `flush()`.
+    init(
+        composer: (any FelComposing)?,
+        primaryDecoder: any SingleLayerVideoDecoder,
+        enhancementDecoder: (any SingleLayerVideoDecoder)?
+    ) {
+        self.composer = composer
+        self.primaryDecoder = primaryDecoder
+        (self.primaryDecoder as? HardwareVideoDecoder)?.useCustomBlockSource = true
+        self.enhancementDecoder = enhancementDecoder
+        (self.enhancementDecoder as? HardwareVideoDecoder)?.useCustomBlockSource = true
+    }
+
+    // Lock discipline: every `private var` below up to `lock` is guarded
+    // by `lock` unless stated otherwise. `decode(packet:)` runs on the demux
+    // thread while `handleBaseLayerFrame` / `handleEnhancementLayerFrame` run on
+    // VideoToolbox output threads, so any state they all touch must be read or
+    // written under the lock, with at most a pointer captured for use outside it.
+    // `nextDeliveryTicket` and `resolveDisplayMetadata` require the lock (callers
+    // hold it). `noteSettledBaseLayer` requires the lock. `orderedDelivery`
+    // is its own, separately-confined owner, reached only through `fulfil`/`reset`/
+    // `setOnFrame`, never through this lock. Sub-decoder calls (`decode`/`flush`/`close`,
+    // `skipUntilPTS` fan-out, `open`) always run without the lock held — see the
+    // ordering note on `skipUntilPTS`.
+    private var timeBase: AVRational = AVRational(num: 1, den: 90000)
+    // Stream classification (dolby-vision-fel.md §5.2, invariant I9 in §5.12): decided once, from the
+    // first RPU's `el_type`, before the enhancement decoder opens. A per-frame
+    // `disable_residual_flag` is a kernel flag (`DoviComposerFlags.disableResidual`,
+    // honoured by the composer) and never changes these. Guarded by `lock`.
+    private var isFEL: Bool = false
+    private var isMEL: Bool = false
+    private var streamClassified: Bool = false
+    private var frameIndex: UInt32 = 0
+
+    private var primaryDecoderInitialized = false
+    /// Set by the first failed in-band open of the primary decoder. Retrying on every later packet
+    /// with parameter sets would only repeat the failure and leave the player on a black screen with
+    /// one log line per keyframe; the failure is reported once, and `decode` refuses packets after it.
+    /// Guarded by `lock`.
+    private var primaryOpenFailure: Error?
+    /// Fired once, on the thread that called `decode`, when the primary decoder cannot be opened from
+    /// in-band parameter sets: nothing can be shown, so the host should fall back or surface an error
+    /// (the hvcC path throws the equivalent from `open(stream:)`).
+    var onFatalDecodeError: (@Sendable (Error) -> Void)? {
+        get { lock.lock(); defer { lock.unlock() }; return _onFatalDecodeError }
+        set { lock.lock(); _onFatalDecodeError = newValue; lock.unlock() }
+    }
+    private var _onFatalDecodeError: (@Sendable (Error) -> Void)?
+    /// The error `onFatalDecodeError` reported, if any.
+    var fatalDecodeError: Error? { lock.lock(); defer { lock.unlock() }; return primaryOpenFailure }
+    /// Set by the first failed open of the enhancement decoder. Retrying on every later packet would
+    /// start a new VideoToolbox session attempt and write a log line per frame for the rest of the
+    /// session; the failure is logged once and the stream stays on the base layer (every frame takes
+    /// the single-layer bypass). Not fatal, unlike `primaryOpenFailure`: there is still a picture to
+    /// show. Cleared by `close()`. Guarded by `lock`.
+    private var enhancementOpenFailure: Error?
+    /// The error that stopped the enhancement decoder from opening, if any.
+    var enhancementDecoderOpenError: Error? { lock.lock(); defer { lock.unlock() }; return enhancementOpenFailure }
+    /// Builds the enhancement-layer session. Replaced by tests only, before the first packet.
+    var makeEnhancementDecoder: () -> any SingleLayerVideoDecoder = {
+        let decoder = HardwareVideoDecoder()
+        decoder.useCustomBlockSource = true
+        return decoder
+    }
+    private var blVPS: [UInt8]?
+    private var blSPS: [UInt8]?
+    private var blPPS: [UInt8]?
+
+    private var elVPS: [UInt8]?
+    private var elSPS: [UInt8]?
+    private var elPPS: [UInt8]?
+    /// Fixed-capacity side data ring for Dolby Vision metadata (dolby-vision-fel.md §5.3).
+    /// Stores `{ params, dmNAL }` keyed by canonical PTS, capacity 32, no sorting.
+    private var sideDataRing = FrameSideDataRing()
+    /// Restamps each enhancement-layer packet with the time of the base-layer picture of the same POC,
+    /// so pairing by time pairs by picture order even when the layers' GOPs differ. Guarded by `lock`.
+    private var pictureAlignment = DualLayerVideoDecoder.makeAlignment()
+    private var blFrameQueue: [Int64: (buffer: CVPixelBuffer, pts: CMTime, ticket: UInt64, seq: UInt64, side: FrameSideData)] = [:]
+    private var elFrameQueue: [Int64: CVPixelBuffer] = [:]
+
+    /// Maximum layer skew in frames (dolby-vision-fel.md §5.5): a waiting base-layer
+    /// frame is bypassed under its own arrival ticket once this many newer
+    /// base-layer frames have arrived. Starts at 3; the 1 Hz summary's maximum skew
+    /// counter (§5.11) is what measures whether it can tighten.
+    static let maxLayerSkewFrames = 3
+
+    /// A waiting base frame is bypassed once K newer ones have arrived, so an enhancement picture
+    /// restamped K or more frames back would find its partner gone: the alignment declines to place those.
+    static func makeAlignment() -> DualLayerPictureAlignment {
+        var a = DualLayerPictureAlignment()
+        a.maxBackwardRestamp = maxLayerSkewFrames - 1
+        return a
+    }
+    /// The enhancement layer can run ahead of the 4K base layer after a seek or at startup.
+    /// Retain up to 10 waiting EL frames (~6 MB each) before pruning the oldest.
+    static let maxEnhancementLayerQueueFrames = 10
+    /// Counts base-layer arrivals. A queued entry is due for bypass once
+    /// `blArrivalSeq - entry.seq >= maxLayerSkewFrames`. Guarded by `lock`.
+    private var blArrivalSeq: UInt64 = 0
+    /// Recently settled (composed or bypassed) base-layer keys. An enhancement
+    /// frame matching one (±300 ticks) can never pair again and is dropped on
+    /// arrival (dolby-vision-fel.md §5.5). Not "older than the newest": output is in decode
+    /// order, so older-PTS base frames settle after newer ones. Guarded by `lock`.
+    private var settledBlKeys: [Int64] = []
+    /// How many settled base-layer keys are remembered (dolby-vision-fel.md §5.5).
+    static let settledKeyMemory = 64
+    /// Last parameters that came from a real RPU, and how many frames in a row have borrowed them. Both
+    /// move in decode order, in `recordSideData`.
+    private var lastGoodParams: DoviMetalParams?
+    private var lastGoodDMNAL: [UInt8]?
+    private var borrowedParamsRun = 0
+    /// A frame whose RPU is missing or failed its CRC may borrow the previous frame's parameters
+    /// for up to this many frames in a row. Reshaping and NLQ parameters are constant across a scene,
+    /// so this beats dropping to the base layer; a longer run is not trusted.
+    static let maxBorrowedParamsRun = 3
+    private(set) var summaryBorrowedParams = 0
+
+    // 1 Hz summary counters (dolby-vision-fel.md §5.11). Guarded by `lock`.
+    /// Compose outcomes are counted from the GPU completion thread, so they get their own lock rather
+    /// than `lock` (taking that one inside the delivery path perturbs the pairing races).
+    private let composeResultLock = NSLock()
+    private var summaryComposedFrames: Int = 0
+    /// Frames the GPU composed since this decoder was created. Unlike `summaryComposedFrames` it is
+    /// never reset by the 1 Hz summary or by `flush()`, so a probe can ask "did anything compose".
+    /// Guarded by `composeResultLock`.
+    private var totalComposedFrames: Int = 0
+    private var summaryComposeFailures: Int = 0
+    /// Compositions started, and compositions whose frame (composed or fallback) has been handed to
+    /// `orderedDelivery`. Equal when nothing is on the GPU or in a completion handler. Guarded by
+    /// `composeResultLock`; read only by `quiesceForTesting`.
+    private var composeRequestsStarted = 0
+    private var composeRequestsHandedOff = 0
+    private var summaryBypassNoEL: Int = 0
+    private var summaryBypassNoRPU: Int = 0
+    private var summaryDropStaleEL: Int = 0
+    private var summaryPrunedEL: Int = 0
+    private var summaryMaxObservedSkew: Int = 0
+    private var lastSummaryTimestamp: TimeInterval = 0
+
+    /// Held for the whole of `flush()` and `close()`, so two of them (the EOF flush on the demux
+    /// thread against a seek flush on the main actor, or either against `close()`) run one after
+    /// the other instead of interleaving their critical sections: without it one call could lower
+    /// `draining` and clear the queues while the other was still draining the hardware decoders.
+    /// Lock order: `lifecycleLock` before `lock`, never the other way round. Nothing on the pairing,
+    /// delivery or VideoToolbox callback paths takes it (`handle*Frame`, `orderedDelivery`, the
+    /// sub-decoders' output callbacks), so the drains inside `flush()` can wait on those paths with
+    /// it held; `decode(packet:)` does not take it either.
+    private let lifecycleLock = NSLock()
+    private let lock = NSRecursiveLock()
+    private var _feedEpoch: UInt64 = 0
+    /// True while `flush()` is draining the hardware decoders (dolby-vision-fel.md
+    /// §5.8). `HardwareVideoDecoder.flush()` waits for the frames VideoToolbox
+    /// still owes, which arrive through the normal callbacks while the host
+    /// thread is blocked inside it; those are pre-seek frames and are dropped
+    /// on arrival rather than paired, ticketed or delivered. Guarded by `lock`.
+    private var draining = false
+    /// Single use (dolby-vision-fel.md §5.8): set by `close()`, after which `open`
+    /// refuses with `VideoDecoderError.decoderClosed`. The host builds a new
+    /// decoder per session, so nothing reopens one; the flag turns a latent
+    /// stale-state reuse into a loud error. Guarded by `lock`.
+    private var isClosed = false
+
+    // MARK: - Ordered delivery
+    //
+    // Composition is asynchronous, so a frame's pixels are ready on a Metal
+    // completion thread rather than at the point the decoder handed them over.
+    // Every outgoing frame — composed, bypassed or pruned — takes a ticket
+    // here, under `lock`, in decode order, at base-layer arrival.
+    // Ordering behind that ticket, and `emit` itself, live entirely in
+    // `orderedDelivery` from here on (dolby-vision-fel.md §5.7): once a ticket is
+    // issued, this decoder's only remaining job is to hand `orderedDelivery`
+    // the ticket, the epoch it was issued in, and the finished frame.
+    private var deliveryNextTicket: UInt64 = 0
+
+    var feedEpoch: UInt64 {
+        lock.lock(); defer { lock.unlock() }; return _feedEpoch
+    }
+
+    static func canonicalKey(pts: CMTime) -> Int64 {
+        guard pts.isNumeric else { return Int64.min }
+        return pts.convertScale(90000, method: .roundHalfAwayFromZero).value
+    }
+
+    static func canonicalKey(rawPTS: Int64, timeBase: AVRational) -> Int64 {
+        guard rawPTS != Int64.min else { return Int64.min }
+        // Stream timestamps are untrusted: a product that overflows has no usable key.
+        let (value, overflow) = rawPTS.multipliedReportingOverflow(by: Int64(timeBase.num))
+        guard !overflow else { return Int64.min }
+        let pts = CMTimeMake(value: value, timescale: max(timeBase.den, 1))
+        return canonicalKey(pts: pts)
+    }
+
+    // MARK: - Lifecycle
+
+    func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {
+        // Single use: refuse before touching `stream` or mutating anything.
+        lock.lock()
+        let closed = isClosed
+        let hasComposer = composer != nil
+        lock.unlock()
+        guard !closed else { throw VideoDecoderError.decoderClosed }
+        // Fail fast if no composer (no Metal device or shader compilation failed).
+        // The host can then fall back to the native 8.1 route instead of decoding the EL for nothing.
+        guard hasComposer else {
+            EngineLog.emit("[DualLayerVideoDecoder] No composer available; FEL composition disabled", category: .swPlayback)
+            throw VideoDecoderError.composerUnavailable
+        }
+        (primaryDecoder as? HardwareVideoDecoder)?.useCustomBlockSource = true
+        if let codecpar = stream.pointee.codecpar {
+            lock.lock()
+            declaredFormat = (ColorDescription(codecpar: codecpar), codecpar.pointee.codec_id, codecpar.pointee.profile)
+            lock.unlock()
+        }
+        self.onFrame = { [weak self] buffer, pts, extra in
+            self?.reportDecodedFormat(buffer)
+            onFrame(buffer, pts, extra)
+        }
+        lock.lock()
+        self.timeBase = stream.pointee.time_base
+        // Only an hvcC record can build the session up front. Extradata of that size that is something
+        // else (an Annex B parameter-set blob, say) takes the in-band path, where the parameter
+        // sets are read from the packets, instead of throwing out of `open`.
+        var hasHVCC = false
+        if (stream.pointee.codecpar?.pointee.extradata_size ?? 0) > 23,
+           let par = stream.pointee.codecpar?.pointee, let ed = par.extradata, ed[0] == 1 {
+            hasHVCC = true
+            // hvcC: the base layer's SPS/PPS may never repeat in band.
+            pictureAlignment.seedBaseParameterSets(parseHVCCParameterSets(ed, Int(par.extradata_size)))
+        }
+        lock.unlock()
+
+        if hasHVCC {
+            // `HardwareVideoDecoder.open` builds the VT session; it synchronizes
+            // internally, so this runs without `lock` held (see the lock ordering note above).
+            try primaryDecoder.open(stream: stream) { [weak self] baseBuffer, pts, hdr10Data in
+                self?.handleBaseLayerFrame(baseBuffer: baseBuffer, pts: pts, hdr10Data: hdr10Data)
+            }
+            lock.lock()
+            primaryDecoderInitialized = true
+            lock.unlock()
+        } else {
+            // Parameter sets are carried in-band in the video packets (e.g. hev1 MP4)
+            lock.lock()
+            primaryDecoderInitialized = false
+            lock.unlock()
+        }
+    }
+
+    // MARK: - Decode Loop
+
+    func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64? = nil) {
+        // Single snapshot under the lock: the epoch gate, the primary
+        // readiness flag and the time base are all shared with the VT threads.
+        // A closed decoder refuses packets outright: without this,
+        // `ensurePrimaryDecoder` could reopen the primary session after `close()`.
+        lock.lock()
+        if isClosed {
+            lock.unlock()
+            return
+        }
+        if let epoch, epoch != _feedEpoch {
+            lock.unlock()
+            return
+        }
+        // The epoch this packet entered under, whether or not the caller passed one: a `flush()` that
+        // lands while the packet is being parsed below must stop it from touching post-flush state.
+        let entryEpoch = _feedEpoch
+        let primed = primaryDecoderInitialized
+        let tb = timeBase
+        lock.unlock()
+
+        if !primed {
+            ensurePrimaryDecoder(from: packet)
+        }
+        lock.lock()
+        guard primaryDecoderInitialized else { lock.unlock(); return }
+        lock.unlock()
+
+        let ptsRaw = packet.pointee.pts
+        let ptsKey = Self.canonicalKey(rawPTS: ptsRaw, timeBase: tb)
+
+        // Extract EL NALs, RPU, and rewrite Base Layer packet to Profile 8.1.
+        // Whether to extract is read from the (immutable once classified) stream state.
+        // If not composing, skip parameter extraction entirely.
+        // Per dolby-vision-fel.md §5.3, §5.4: VideoToolbox format description carries no dvcC,
+        // so VT skips unspec62/63 for both FEL and MEL without rebuilding the base-layer packet.
+        let (skipEL, canCompose): (Bool, Bool) = {
+            lock.lock()
+            defer { lock.unlock() }
+            let composing = !isClosed && !isMEL && composer != nil
+            return (isMEL, composing)
+        }()
+        // One-shot stream classification: the first definitive RPU decides, later
+        // RPUs — including per-frame `disable_residual_flag`, which rides to the kernels
+        // as `DoviComposerFlags.disableResidual` — never change it. In particular this
+        // never closes the enhancement decoder; decoders are only torn down in
+        // `flush()`/`close()`, never from `decode(packet:)`.
+        let layers = DoviRpuConverter.separateDualLayers(
+            packet,
+            extractEL: !skipEL,
+            useCustomBlockSource: true,
+            extractParams: canCompose
+        )
+        applyStreamClassification(DoviRpuConverter.classifyStream(layers))
+
+        // One critical section for everything this packet writes into shared state: the side-data
+        // record (which also moves `lastGoodParams`) and the picture-order restamp. A `flush()` or
+        // `close()` that landed while `separateDualLayers` ran (outside the lock) means this packet
+        // belongs to the old feed: recording it would poison the post-flush state, or undo a close.
+        lock.lock()
+        guard !isClosed, _feedEpoch == entryEpoch else {
+            lock.unlock()
+            var stale = layers.elPacket
+            trackedPacketFree(&stale)
+            return
+        }
+        if ptsKey != Int64.min {
+            // In decode order, here, so every frame carries concrete parameters by the time it pairs:
+            // compose time runs in completion order, which is not stream order.
+            recordSideData(key: ptsKey, params: layers.rpuParams, dmNAL: layers.convertedRpu,
+                           usesPrevious: layers.usesPreviousMapping, disableResidual: layers.disableResidual)
+        }
+
+        // The enhancement decoder opens for a classified FEL stream only
+        // (dolby-vision-fel.md §5.2): MEL never opens it, and the EL keeps decoding across RPUs
+        // with `disable_residual_flag` set.
+        // Also require a composer; without one, never engage the EL decoder.
+        let engageEL = isFEL && !isMEL && composer != nil
+        if engageEL, let data = packet.pointee.data {
+            // `separateDualLayers` left the packet intact (custom block source), so both layers are
+            // still in it. Every unit is read, with or without an EL, to keep the POC state current.
+            let wasReordered = pictureAlignment.reorderedUnits > 0
+            let elPTS = pictureAlignment.enhancementPTS(data, Int(packet.pointee.size), framing: .lengthPrefixed(size: 4), pts: ptsRaw)
+            let nowReordered = pictureAlignment.reorderedUnits > 0
+            lock.unlock()
+            layers.elPacket?.pointee.pts = elPTS
+            if nowReordered && !wasReordered {
+                EngineLog.emit("[DualLayerVideoDecoder] enhancement layer is reordered against the base layer; pairing by picture order", category: .swPlayback)
+            }
+        } else {
+            lock.unlock()
+        }
+        if engageEL, let elPacket = layers.elPacket {
+            ensureEnhancementDecoder(from: elPacket)
+            // Capture under the lock, decode outside it: `close()`/`flush()` may
+            // swap the decoder out concurrently, and the sub-decoder call must not
+            // nest inside this lock. Re-check `isClosed` from
+            // the same snapshot: a `close()` that landed after the entry gate
+            // must not feed the (possibly freshly installed) enhancement decoder.
+            lock.lock()
+            let el = enhancementDecoder
+            let closedAfterEnsure = isClosed
+            lock.unlock()
+            if !closedAfterEnsure {
+                el?.decode(packet: elPacket, epoch: epoch)
+            }
+            var elOpt: UnsafeMutablePointer<AVPacket>? = elPacket
+            trackedPacketFree(&elOpt)
+        } else if let elPacket = layers.elPacket {
+            var elOpt: UnsafeMutablePointer<AVPacket>? = elPacket
+            trackedPacketFree(&elOpt)
+        }
+
+        // Decode Base Layer packet.
+        //
+        // With `useCustomBlockSource` the packet is untouched: `separateDualLayers` only reads it, so
+        // the base layer's own RPU NAL (unspec62) is still inside it, which
+        // looks alarming next to a composer that is about to apply the same
+        // reshaping curve itself. It is inert: the primary decoder's format
+        // description is built from the base layer's VPS/SPS/PPS alone (see
+        // `ensurePrimaryDecoder`) with no `dvcC`/`dvvC` record, so VideoToolbox
+        // decodes plain HEVC and skips the unspec62 NAL as an unknown type. The
+        // curve is applied exactly once, on the GPU. (`separateDualLayers` also backs
+        // `convertPacketToProfile81`, the remux route, where it does rewrite the packet to
+        // Profile 8.1 and the container declares a `dvcC`; that is not this path.)
+        //
+        // Re-check `isClosed` before feeding the primary — a `close()`
+        // that landed after the entry gate must not reopen/feed a torn-down session.
+        lock.lock()
+        let closedBeforePrimary = isClosed
+        lock.unlock()
+        guard !closedBeforePrimary else { return }
+        primaryDecoder.decode(packet: packet, epoch: epoch)
+    }
+
+    /// Applies one RPU's stream classification. The first definitive report wins and every
+    /// later one is ignored, so one frame can never shut off the enhancement layer for the
+    /// rest of the session (invariant I9, dolby-vision-fel.md §5.12). Called from `decode(packet:)` — which
+    /// never closes a decoder — and from the test seam below.
+    private func applyStreamClassification(_ kind: DoviRpuConverter.StreamKind) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !streamClassified else { return }
+        switch kind {
+        case .undetermined:
+            return
+        case .fel:
+            isFEL = true
+            isMEL = false
+            streamClassified = true
+            EngineLog.emit("[DualLayerVideoDecoder] FEL stream detected; engaging enhancement decoder", category: .swPlayback)
+        case .mel:
+            isFEL = false
+            isMEL = true
+            streamClassified = true
+            EngineLog.emit("[DualLayerVideoDecoder] MEL stream detected; secondary decoder bypassed, routing Base Layer directly", category: .swPlayback)
+        }
+    }
+
+    // Lazily opens the primary decoder from in-band parameter sets. Only the demux
+    // thread reaches here (from `decode`), but `primaryDecoderInitialized`, the
+    // accumulated `blVPS/SPS/PPS` and `timeBase` are shared with the VT threads, so
+    // every touch is under `lock`; the blocking `open` runs outside it.
+    // Resurrection guard: `decode()` passes the entry gate before
+    // `close()` runs, so re-check `isClosed` before opening and again before
+    // installing — a post-close open is torn down immediately instead of
+    // leaving a live VT session in a closed decoder.
+    private func ensurePrimaryDecoder(from packet: UnsafeMutablePointer<AVPacket>) {
+        lock.lock()
+        guard !primaryDecoderInitialized, !isClosed, primaryOpenFailure == nil else { lock.unlock(); return }
+        var v = blVPS
+        var s = blSPS
+        var p = blPPS
+        let tb = timeBase
+        lock.unlock()
+        guard let data = packet.pointee.data, packet.pointee.size > 4 else { return }
+        let size = Int(packet.pointee.size)
+
+        A53SEIParser.forEachNAL(data, size, .lengthPrefixed(size: 4)) { nal, len in
+            let nalType = (nal[0] >> 1) & 0x3F
+            let bytes = [UInt8](UnsafeBufferPointer(start: nal, count: len))
+            switch nalType {
+            case 32: v = bytes
+            case 33: s = bytes
+            case 34: p = bytes
+            default: break
+            }
+        }
+
+        guard let vv = v, let ss = s, let pp = p else {
+            // Incomplete set: accumulate what this packet carried for the next one.
+            lock.lock()
+            if blVPS == nil { blVPS = v }
+            if blSPS == nil { blSPS = s }
+            if blPPS == nil { blPPS = p }
+            lock.unlock()
+            return
+        }
+        do {
+            try primaryDecoder.open(parameterSets: [vv, ss, pp], timeBase: tb) { [weak self] baseBuffer, pts, hdr10Data in
+                self?.handleBaseLayerFrame(baseBuffer: baseBuffer, pts: pts, hdr10Data: hdr10Data)
+            }
+            lock.lock()
+            blVPS = vv
+            blSPS = ss
+            blPPS = pp
+            if isClosed || primaryDecoderInitialized {
+                // Lost the race with `close()` (or another opener): the session
+                // just built belongs to a closed decoder — tear it down outside
+                // the lock instead of marking it initialized.
+                lock.unlock()
+                primaryDecoder.close()
+                return
+            }
+            primaryDecoderInitialized = true
+            lock.unlock()
+            EngineLog.emit("[DualLayerVideoDecoder] primary decoder initialized from in-band parameter sets", category: .swPlayback)
+        } catch {
+            // Fail once, visibly: the same sets would fail the same way on every later packet.
+            lock.lock()
+            let firstFailure = primaryOpenFailure == nil
+            if firstFailure { primaryOpenFailure = error }
+            let handler = _onFatalDecodeError
+            lock.unlock()
+            guard firstFailure else { return }
+            EngineLog.emit("[DualLayerVideoDecoder] failed to open the primary decoder from in-band parameter sets, no video will be produced: \(error)", category: .swPlayback)
+            handler?(error)
+        }
+    }
+
+    // Lazily opens the enhancement decoder. Same discipline as
+    // `ensurePrimaryDecoder`: shared state under `lock`, VT session build outside
+    // it, install under the lock only if still absent **and** the decoder is not
+    // closed (resurrection guard: a thread past the `decode()` entry gate
+    // that reaches the install after `close()` cleared `enhancementDecoder` to
+    // nil must close its spare instead of planting a live VT session into the
+    // closed decoder).
+    func ensureEnhancementDecoder(from packet: UnsafeMutablePointer<AVPacket>) {
+        lock.lock()
+        // Never open the EL decoder without a composer. In production this is
+        // redundant (`engageEL` in `decode()` already gates on `composer != nil`), but
+        // it makes the invariant explicit and safe against future refactors.
+        guard enhancementDecoder == nil, !isClosed, composer != nil, enhancementOpenFailure == nil else { lock.unlock(); return }
+        var v = elVPS
+        var s = elSPS
+        var p = elPPS
+        let skip = _skipUntilPTS
+        let tb = timeBase
+        lock.unlock()
+        guard let data = packet.pointee.data, packet.pointee.size > 4 else { return }
+        let size = Int(packet.pointee.size)
+
+        A53SEIParser.forEachNAL(data, size, .lengthPrefixed(size: 4)) { nal, len in
+            let nalType = (nal[0] >> 1) & 0x3F
+            let bytes = [UInt8](UnsafeBufferPointer(start: nal, count: len))
+            switch nalType {
+            case 32: v = bytes
+            case 33: s = bytes
+            case 34: p = bytes
+            default: break
+            }
+        }
+
+        guard let vv = v, let ss = s, let pp = p else {
+            lock.lock()
+            if elVPS == nil { elVPS = v }
+            if elSPS == nil { elSPS = s }
+            if elPPS == nil { elPPS = p }
+            lock.unlock()
+            return
+        }
+        let decoder = makeEnhancementDecoder()
+        decoder.skipUntilPTS = skip
+        do {
+            try decoder.open(parameterSets: [vv, ss, pp], timeBase: tb) { [weak self] elBuffer, pts, _ in
+                self?.handleEnhancementLayerFrame(elBuffer: elBuffer, pts: pts)
+            }
+            lock.lock()
+            elVPS = vv
+            elSPS = ss
+            elPPS = pp
+            if enhancementDecoder == nil, !isClosed {
+                // Same epoch as this decoder: a `flush()` before the first EL packet has already moved
+                // `_feedEpoch`, and a decoder left at epoch 0 would drop every packet it is fed.
+                // Safe under `lock`: the new decoder is not shared yet, so nothing else holds its lock.
+                decoder.adoptFeedEpoch(_feedEpoch)
+                enhancementDecoder = decoder
+                lock.unlock()
+                EngineLog.emit("[DualLayerVideoDecoder] secondary decoder initialized for the enhancement layer", category: .swPlayback)
+            } else {
+                // Lost the race with another opener, or `close()` cleared the
+                // slot (and set `isClosed`) while the session was building: do
+                // not plant a live VT session into the closed decoder; tear the
+                // spare down outside the lock.
+                lock.unlock()
+                decoder.close()
+            }
+        } catch {
+            // Fail once: the same sets would fail the same way on every later packet.
+            lock.lock()
+            elVPS = vv
+            elSPS = ss
+            elPPS = pp
+            let firstFailure = enhancementOpenFailure == nil
+            if firstFailure { enhancementOpenFailure = error }
+            lock.unlock()
+            guard firstFailure else { return }
+            EngineLog.emit("[DualLayerVideoDecoder] failed to initialize EL decoder, continuing with the base layer only: \(error)", category: .swPlayback)
+        }
+    }
+
+    // MARK: - Frame Emission
+
+    /// Reserves this frame's place in the output order. The caller holds `lock`.
+    ///
+    /// Every ticket must reach ``OrderedDelivery/fulfil(ticket:epoch:_:)`` or the
+    /// queue behind it stalls — `orderedDelivery`'s own stall guard is the backstop
+    /// if one never does; a flush or close retires outstanding tickets wholesale.
+    private func nextDeliveryTicket() -> UInt64 {
+        let t = deliveryNextTicket
+        deliveryNextTicket &+= 1
+        return t
+    }
+
+    /// Looks up and removes this frame's Profile 8.1 display-metadata NAL,
+    /// within the same jitter tolerance as the RPU cache. The caller holds
+    /// `lock`.
+    ///
+    /// Resolved once, at base-layer arrival — the same point `hdr10Data`
+    /// already enters the system as a parameter — so it can travel with the
+    /// frame instead of living in a cache `OrderedDelivery.emit` would
+    /// otherwise have to reach back into without the decoder's lock
+    /// (dolby-vision-fel.md §5.7).
+    private func resolveDisplayMetadata(key: Int64) -> [UInt8]? {
+        sideDataRing.removeDisplayMetadata(key: key)
+    }
+
+    // MARK: - Frame Pairing & Metal Composition
+    //
+    // dolby-vision-fel.md §5.5, §5.6: decide under the lock, act outside it. Each
+    // handler holds `lock` only while it matches queues, consumes caches and
+    // issues the delivery ticket. The GPU slot wait, encode and commit happen
+    // after the lock is released (see `runCompose`), so backpressure on the
+    // calling VideoToolbox thread never stalls `orderedDelivery`, the other
+    // layer's callback, `flush()` or `close()`.
+
+    /// What one frame handler decided while holding `lock`. Payloads are a
+    /// baton pass: the handler stops touching them once they are in here, and
+    /// `runCompose` / `orderedDelivery` is the only reader after that.
+    /// `dmNAL` and `epoch` are resolved under the same lock hold that issued
+    /// `ticket` (dolby-vision-fel.md §5.7): `dmNAL` so `OrderedDelivery.emit` never
+    /// touches `dmRpuCache`, `epoch` so a late completion can tell a stale
+    /// delivery from a current one without the decoder lock.
+    private struct ComposeRequest {
+        let ticket: UInt64
+        let epoch: UInt64
+        let base: CVPixelBuffer
+        let enhancement: CVPixelBuffer
+        let params: DoviMetalParams
+        let frameIndex: UInt32
+        let pts: CMTime
+        let hdr10Data: Data?
+        let dmNAL: [UInt8]?
+        /// Which arrival path produced this, for the compose-failure log.
+        let arrived: String
+    }
+
+    private struct BypassRequest {
+        let ticket: UInt64
+        let epoch: UInt64
+        let buffer: CVPixelBuffer
+        let pts: CMTime
+        let hdr10Data: Data?
+        let dmNAL: [UInt8]?
+        let reason: String
+    }
+
+    private enum PairingOutcome {
+        case queued
+        case bypass(BypassRequest)
+        case compose(ComposeRequest)
+    }
+
+    /// Hands one bypass request straight to `orderedDelivery`. No lock held.
+    private func fulfilBypass(_ req: BypassRequest) {
+        orderedDelivery.fulfil(
+            ticket: req.ticket, epoch: req.epoch,
+            DeliveredFrame(buffer: SendableBuffer(value: req.buffer), pts: req.pts, hdr10Data: req.hdr10Data, dmNAL: req.dmNAL)
+        )
+    }
+
+    /// Acquires the GPU slot with no lock held, then encodes and commits. The
+    /// completed frame (or the base layer when composition fails) reaches
+    /// `orderedDelivery`, which reorders by ticket. The completion closure
+    /// captures `orderedDelivery` strongly and the decoder weakly for counters
+    /// (dolby-vision-fel.md §5.7): a completion that outlives the decoder
+    /// still calls `fulfil`, which drops it once `orderedDelivery`'s epoch has
+    /// moved on, instead of silently no-oping on a `weak self`.
+    private func runCompose(_ req: ComposeRequest) {
+        guard let composer else {
+            orderedDelivery.fulfil(
+                ticket: req.ticket, epoch: req.epoch,
+                DeliveredFrame(buffer: SendableBuffer(value: req.base), pts: req.pts, hdr10Data: req.hdr10Data, dmNAL: req.dmNAL)
+            )
+            return
+        }
+        if let concrete = composer as? DoviFelComposer {
+            FelResidualMeasure.sampleIfDue(composer: concrete, base: req.base, enhancement: req.enhancement,
+                                           params: req.params, frameIndex: req.frameIndex, pts: req.pts)
+        }
+        composeResultLock.lock(); composeRequestsStarted += 1; composeResultLock.unlock()
+        composer.acquireSlot()
+        let fallback = SendableBuffer(value: req.base)
+        // Scalars (plus the strongly-captured `delivery`) copied out so the
+        // `@Sendable` completion captures no CoreVideo types (Swift 6 mode
+        // rejects the struct itself).
+        let ticket = req.ticket
+        let epoch = req.epoch
+        let pts = req.pts
+        let hdr10Data = req.hdr10Data
+        let dmNAL = req.dmNAL
+        let arrived = req.arrived
+        let delivery = orderedDelivery
+        composer.composeAsyncWithAcquiredSlot(
+            baseBuffer: req.base,
+            enhancementBuffer: req.enhancement,
+            params: req.params,
+            frameIndex: req.frameIndex
+        ) { [weak self] composed in
+            self?.recordComposeResult(success: composed != nil)
+            if composed == nil {
+                EngineLog.emit("[DualLayer] COMPOSE FAILED (\(arrived)): pts=\(String(format: "%.3f", pts.seconds))", category: .swPlayback, level: .verbose)
+            }
+            let buffer = SendableBuffer(value: composed ?? fallback.value)
+            delivery.fulfil(ticket: ticket, epoch: epoch, DeliveredFrame(buffer: buffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL))
+            self?.composeResultLock.lock(); self?.composeRequestsHandedOff += 1; self?.composeResultLock.unlock()
+        }
+    }
+
+    private func recordComposeResult(success: Bool) {
+        composeResultLock.lock()
+        if success { summaryComposedFrames += 1; totalComposedFrames += 1 } else { summaryComposeFailures += 1 }
+        composeResultLock.unlock()
+    }
+
+    /// Frames composed on the GPU so far (bypassed and failed frames are not counted).
+    var composedFrameCount: Int {
+        composeResultLock.lock(); defer { composeResultLock.unlock() }
+        return totalComposedFrames
+    }
+
+    /// Internal rather than private so `DualLayerVideoDecoderTests` can drive it directly.
+    func handleBaseLayerFrame(baseBuffer: CVPixelBuffer, pts: CMTime, hdr10Data: Data?) {
+        // The ticket is issued when the frame arrives, so a frame that
+        // waits for a late enhancement layer keeps its place in decode order.
+        // The arrival may also push older waiting frames past K newer frames,
+        // which go out here under their own tickets (`due`).
+        let outcome: PairingOutcome
+        let due: [BypassRequest]
+        (outcome, due) = {
+            lock.lock()
+            defer { lock.unlock() }
+
+            // Defense in depth: VT callbacks still in flight when
+            // `close()` runs must not pair, ticket or queue into cleared state.
+            guard !isClosed else { return (.queued, []) }
+            // Pre-seek frame drained by `flush()`: drop before it can
+            // take a ticket or occupy a queue slot meant for post-seek frames.
+            guard !draining else { return (.queued, []) }
+            guard isFEL, !isMEL, enhancementDecoder != nil, composer != nil else {
+                // Not a FEL stream or secondary decoder not engaged (e.g. MEL or P8.1 fallback): emit Base Layer directly
+                EngineLog.emit("[DualLayer] Bypass: isFEL=\(isFEL), isMEL=\(isMEL), enhDecoder=\(enhancementDecoder != nil)", category: .swPlayback, level: .verbose)
+                if isFEL && !isMEL && enhancementDecoder == nil {
+                    summaryBypassNoEL += 1
+                }
+                let singleLayerKey = Self.canonicalKey(pts: pts)
+                let dmNAL = resolveDisplayMetadata(key: singleLayerKey)
+                return (.bypass(BypassRequest(ticket: nextDeliveryTicket(), epoch: _feedEpoch, buffer: baseBuffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, reason: "single-layer")), [])
+            }
+
+            let key = Self.canonicalKey(pts: pts)
+            let ticket = nextDeliveryTicket()
+            let epoch = _feedEpoch
+            let dmNAL = resolveDisplayMetadata(key: key)
+            blArrivalSeq &+= 1
+            let seq = blArrivalSeq
+
+            var primary: PairingOutcome
+            // A frame without a timestamp has nothing to pair on: it goes out as its base layer now, under
+            // the ticket it already holds, rather than waiting for a partner that cannot match it.
+            guard key != Int64.min else {
+                EngineLog.emit("[DualLayer] Bypass: base-layer frame without a timestamp", category: .swPlayback, level: .verbose)
+                return (.bypass(BypassRequest(ticket: ticket, epoch: epoch, buffer: baseBuffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, reason: "no-pts")), collectDueBypasses())
+            }
+            let mKey: Int64?
+            if elFrameQueue[key] != nil {
+                mKey = key
+            } else {
+                // Search within +/- 300 ticks (~3.3ms) for clock jitter tolerance
+                mKey = elFrameQueue.keys.first(where: { FrameSideDataRing.isWithinJitter($0, key) })
+            }
+
+            if let mKey, let elBuffer = elFrameQueue.removeValue(forKey: mKey) {
+                // Matching EL frame is already ready: compose on the Metal GPU outside the lock
+                guard let params = takeParams(key: key) else {
+                    // S1: Missing RPU metadata: do NOT synthesize identity NLQ. Emit base layer directly.
+                    EngineLog.emit("[DualLayer] Bypass: missing RPU for key=\(key)", category: .swPlayback, level: .verbose)
+                    summaryBypassNoRPU += 1
+                    noteSettledBaseLayer(key: key)
+                    primary = .bypass(BypassRequest(ticket: ticket, epoch: epoch, buffer: baseBuffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, reason: "missing-rpu"))
+                    return (primary, collectDueBypasses())
+                }
+                frameIndex &+= 1
+                noteSettledBaseLayer(key: key)
+                primary = .compose(ComposeRequest(ticket: ticket, epoch: epoch, base: baseBuffer, enhancement: elBuffer, params: params, frameIndex: frameIndex, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, arrived: "BL arrived"))
+            } else {
+                // EL frame has not arrived yet: queue Base Layer frame under its ticket
+                EngineLog.emit("[DualLayer] QUEUE BL: pts=\(String(format: "%.3f", pts.seconds)) key=\(key), elCount=\(elFrameQueue.count)", category: .swPlayback, level: .verbose)
+                var displaced: BypassRequest?
+                if let old = blFrameQueue[key] {
+                    // Same canonical key twice: the old entry's ticket would stall
+                    // delivery forever if dropped, so bypass it under its ticket,
+                    // carrying its stored side data.
+                    displaced = BypassRequest(ticket: old.ticket, epoch: epoch, buffer: old.buffer, pts: old.pts, hdr10Data: old.side.hdr10Data, dmNAL: old.side.dmNAL, reason: "duplicate-key")
+                    noteSettledBaseLayer(key: key)
+                }
+                blFrameQueue[key] = (buffer: baseBuffer, pts: pts, ticket: ticket, seq: seq, side: FrameSideData(hdr10Data: hdr10Data, dmNAL: dmNAL))
+                let currentSkew = max(blFrameQueue.count, elFrameQueue.count)
+                if currentSkew > summaryMaxObservedSkew {
+                    summaryMaxObservedSkew = currentSkew
+                }
+                primary = .queued
+                var due = collectDueBypasses()
+                if let displaced { due.insert(displaced, at: 0) }
+                return (primary, due)
+            }
+            return (primary, collectDueBypasses())
+        }()
+
+        // Older tickets first; `orderedDelivery` reorders by ticket anyway.
+        for req in due {
+            fulfilBypass(req)
+        }
+        switch outcome {
+        case .queued:
+            break
+        case .bypass(let req):
+            fulfilBypass(req)
+        case .compose(let req):
+            runCompose(req)
+        }
+        maybeEmitSummary()
+    }
+
+    /// Internal rather than private so `DualLayerVideoDecoderTests` can drive it directly.
+    func handleEnhancementLayerFrame(elBuffer: CVPixelBuffer, pts: CMTime) {
+        let outcome: PairingOutcome = {
+            lock.lock()
+            defer { lock.unlock() }
+
+            // Defense in depth: see `handleBaseLayerFrame`.
+            guard !isClosed else { return .queued }
+            // Pre-seek frame drained by `flush()`: drop before it can
+            // pair or occupy a queue slot meant for post-seek frames.
+            guard !draining else { return .queued }
+            guard composer != nil else { return .queued }
+            let key = Self.canonicalKey(pts: pts)
+            // No timestamp, no partner: it cannot pair with anything.
+            guard key != Int64.min else { return .queued }
+            // This enhancement layer's base layer already went out
+            // (composed or bypassed), so it can never pair; drop it.
+            if settledBlKeys.contains(where: { FrameSideDataRing.isWithinJitter($0, key) }) {
+                EngineLog.emit("[DualLayer] DROP stale EL: key=\(key), already settled", category: .swPlayback, level: .verbose)
+                summaryDropStaleEL += 1
+                return .queued
+            }
+            var matchingBlKey: Int64?
+            if blFrameQueue[key] != nil {
+                matchingBlKey = key
+            } else {
+                matchingBlKey = blFrameQueue.keys.first(where: { FrameSideDataRing.isWithinJitter($0, key) })
+            }
+
+            if let mKey = matchingBlKey, let waiting = blFrameQueue.removeValue(forKey: mKey) {
+                // Base Layer frame was waiting: compose on the Metal GPU outside the lock,
+                // under the ticket its arrival took.
+                let epoch = _feedEpoch
+                let dmNAL = waiting.side.dmNAL
+                guard let params = takeParams(key: mKey) else {
+                    // S1: Missing RPU metadata: do NOT synthesize identity NLQ. Emit base layer directly.
+                    EngineLog.emit("[DualLayer] Bypass: missing RPU for key=\(mKey)", category: .swPlayback, level: .verbose)
+                    summaryBypassNoRPU += 1
+                    noteSettledBaseLayer(key: mKey)
+                    return .bypass(BypassRequest(ticket: waiting.ticket, epoch: epoch, buffer: waiting.buffer, pts: waiting.pts, hdr10Data: waiting.side.hdr10Data, dmNAL: waiting.side.dmNAL, reason: "missing-rpu"))
+                }
+                frameIndex &+= 1
+                noteSettledBaseLayer(key: mKey)
+                return .compose(ComposeRequest(ticket: waiting.ticket, epoch: epoch, base: waiting.buffer, enhancement: elBuffer, params: params, frameIndex: frameIndex, pts: waiting.pts, hdr10Data: waiting.side.hdr10Data, dmNAL: dmNAL, arrived: "EL arrived"))
+            } else {
+                // Base Layer frame has not arrived yet: queue EL frame under its own larger cap
+                EngineLog.emit("[DualLayer] QUEUE EL: pts=\(String(format: "%.3f", pts.seconds)) key=\(key), blCount=\(blFrameQueue.count)", category: .swPlayback, level: .verbose)
+                elFrameQueue[key] = elBuffer
+                let currentSkew = max(blFrameQueue.count, elFrameQueue.count)
+                if currentSkew > summaryMaxObservedSkew {
+                    summaryMaxObservedSkew = currentSkew
+                }
+                if elFrameQueue.count > Self.maxEnhancementLayerQueueFrames {
+                    let sortedKeys = elFrameQueue.keys.sorted()
+                    for k in sortedKeys.prefix(elFrameQueue.count - Self.maxEnhancementLayerQueueFrames) {
+                        EngineLog.emit("[DualLayer] PRUNED EL: key=\(k)", category: .swPlayback, level: .verbose)
+                        elFrameQueue.removeValue(forKey: k)
+                        summaryPrunedEL += 1
+                    }
+                }
+                return .queued
+            }
+        }()
+
+        switch outcome {
+        case .queued:
+            break
+        case .bypass(let req):
+            fulfilBypass(req)
+        case .compose(let req):
+            runCompose(req)
+        }
+        maybeEmitSummary()
+    }
+
+    /// Resolves what one packet's RPU means for its frame and records it for pairing. Runs in decode order,
+    /// from `decode(packet:)`, so "the previous mapping" is the previous frame in the stream and not whichever
+    /// frame happened to finish composing last. The caller holds `lock`.
+    ///
+    /// - A real RPU is the frame's parameters, and the new "previous mapping".
+    /// - `use_prev_vdr_rpu_flag` keeps the previous mapping by definition, for as long as the stream keeps
+    ///   asking.
+    /// - A missing or corrupt RPU may borrow the previous mapping for up to `maxBorrowedParamsRun` frames in
+    ///   a row; reshaping and NLQ parameters are constant across a scene. Past that the frame carries none
+    ///   and goes out as its base layer.
+    private func recordSideData(key: Int64, params: DoviMetalParams?, dmNAL: [UInt8]?, usesPrevious: Bool, disableResidual: Bool = false) {
+        var resolvedParams = params
+        var resolvedNAL = dmNAL
+        if let params {
+            lastGoodParams = params
+            lastGoodDMNAL = dmNAL
+            borrowedParamsRun = 0
+        } else if let last = lastGoodParams {
+            if usesPrevious {
+                // Only `prev_vdr_rpu_id` 0 is followed (the previous RPU in decode order), as on every
+                // surveyed stream. The curves and NLQ come from that RPU; the residual switch is this
+                // frame's own header flag, not the previous frame's.
+                var borrowed = last
+                if disableResidual { borrowed.flags.insert(.disableResidual) } else { borrowed.flags.remove(.disableResidual) }
+                resolvedParams = borrowed
+                resolvedNAL = dmNAL ?? lastGoodDMNAL
+            } else if borrowedParamsRun < Self.maxBorrowedParamsRun {
+                borrowedParamsRun += 1
+                summaryBorrowedParams += 1
+                resolvedParams = last
+                resolvedNAL = dmNAL ?? lastGoodDMNAL
+                EngineLog.emit("[DualLayer] RPU missing for key=\(key); reusing the previous frame's parameters (\(borrowedParamsRun)/\(Self.maxBorrowedParamsRun))", category: .swPlayback, level: .verbose)
+            }
+        }
+        guard resolvedParams != nil || resolvedNAL != nil else { return }
+        sideDataRing.insert(key: key, params: resolvedParams, dmNAL: resolvedNAL)
+    }
+
+    /// The parameters `recordSideData` resolved for `key`, nil when the frame has none. The caller holds `lock`.
+    private func takeParams(key: Int64) -> DoviMetalParams? {
+        sideDataRing.removeParams(key: key)
+    }
+
+    /// Records a settled base-layer key and drops queued enhancement frames that
+    /// can never pair with a future base layer (dolby-vision-fel.md §5.5). The caller
+    /// holds `lock`.
+    private func noteSettledBaseLayer(key: Int64) {
+        // Keyed match, not "older than the newest": both layers come out of VideoToolbox in
+        // decode order, so an older-PTS base frame legitimately settles after a newer one.
+        settledBlKeys.append(key)
+        if settledBlKeys.count > Self.settledKeyMemory { settledBlKeys.removeFirst(settledBlKeys.count - Self.settledKeyMemory) }
+        for k in elFrameQueue.keys where FrameSideDataRing.isWithinJitter(k, key) {
+            EngineLog.emit("[DualLayer] DROP stale EL: key=\(k), base \(key) settled", category: .swPlayback, level: .verbose)
+            elFrameQueue.removeValue(forKey: k)
+            summaryDropStaleEL += 1
+        }
+    }
+
+    /// Bypasses every queued base-layer frame that has seen K newer base-layer
+    /// arrivals, oldest first, each under the ticket its arrival took.
+    /// The caller holds `lock`.
+    private func collectDueBypasses() -> [BypassRequest] {
+        var due: [BypassRequest] = []
+        for k in blFrameQueue.keys.sorted() {
+            guard let entry = blFrameQueue[k],
+                  blArrivalSeq &- entry.seq >= UInt64(Self.maxLayerSkewFrames) else { continue }
+            blFrameQueue.removeValue(forKey: k)
+            summaryBypassNoEL += 1
+            EngineLog.emit("[DualLayer] BYPASS no-EL: pts=\(String(format: "%.3f", entry.pts.seconds)) key=\(k)", category: .swPlayback, level: .verbose)
+            noteSettledBaseLayer(key: k)
+            due.append(BypassRequest(ticket: entry.ticket, epoch: _feedEpoch, buffer: entry.buffer, pts: entry.pts, hdr10Data: entry.side.hdr10Data, dmNAL: entry.side.dmNAL, reason: "no-el"))
+        }
+        // Every arrival takes a new `seq`, so what survives the loop arrived within the last
+        // `maxLayerSkewFrames` base frames: the queue is bounded by the skew rule alone.
+        assert(blFrameQueue.count <= Self.maxLayerSkewFrames)
+        return due
+    }
+
+    #if DEBUG
+    var summaryTimestampProviderForTesting: (() -> TimeInterval)?
+    #endif
+
+    // MARK: - Observability (dolby-vision-fel.md §5.11)
+
+    /// Seconds between `[DualLayer] summary` lines (dolby-vision-fel.md §5.11).
+    static let summaryIntervalSeconds: TimeInterval = 1.0
+
+    func maybeEmitSummary() {
+        #if DEBUG
+        let now = summaryTimestampProviderForTesting?() ?? ProcessInfo.processInfo.systemUptime
+        #else
+        let now = ProcessInfo.processInfo.systemUptime
+        #endif
+        lock.lock()
+        guard isFEL, !isMEL else {
+            lock.unlock()
+            return
+        }
+        if lastSummaryTimestamp == 0 {
+            lastSummaryTimestamp = now
+            lock.unlock()
+            return
+        }
+        guard now - lastSummaryTimestamp >= Self.summaryIntervalSeconds else {
+            lock.unlock()
+            return
+        }
+        composeResultLock.lock()
+        let composed = summaryComposedFrames
+        let composeFailures = summaryComposeFailures
+        summaryComposedFrames = 0
+        summaryComposeFailures = 0
+        composeResultLock.unlock()
+        let noEL = summaryBypassNoEL
+        let noRPU = summaryBypassNoRPU
+        let staleEL = summaryDropStaleEL
+        let prunedEL = summaryPrunedEL
+        let borrowedParams = summaryBorrowedParams
+        let skew = summaryMaxObservedSkew
+        summaryBypassNoEL = 0
+        summaryBypassNoRPU = 0
+        summaryDropStaleEL = 0
+        summaryPrunedEL = 0
+        summaryBorrowedParams = 0
+        summaryMaxObservedSkew = max(blFrameQueue.count, elFrameQueue.count)
+        lastSummaryTimestamp = now
+        let activeComposer = composer
+        lock.unlock()
+
+        let slots = activeComposer?.takePeakSlotsInUse() ?? 0
+        let poolBuffers = activeComposer?.allocatedPoolBuffers ?? 0
+        let gpuMs = activeComposer?.meanGPUTimeMs
+        let pendingPeak = orderedDelivery.takePeakPendingCount()
+        let gpuStr = gpuMs.map { String(format: "%.1f", $0) } ?? "n/a"
+        let line = "[DualLayer] summary: composed=\(composed), composeFailures=\(composeFailures), bypassNoEL=\(noEL), bypassNoRPU=\(noRPU), staleELDropped=\(staleEL), prunedEL=\(prunedEL), borrowedParams=\(borrowedParams), maxSkew=\(skew), peakGpuSlots=\(slots), poolBuffers=\(poolBuffers), deliveryPendingPeak=\(pendingPeak), meanGpuMs=\(gpuStr)"
+        EngineLog.emit(line, category: .swPlayback)
+        activeComposer?.flushTextureCache()
+    }
+
+    // MARK: - Flush & Teardown
+
+    func flush() {
+        #if DEBUG
+        flushWillTakeLifecycleLockHookForTesting?()
+        #endif
+        lifecycleLock.lock()
+        defer { lifecycleLock.unlock() }
+        // `orderedDelivery`'s epoch is retired from THIS critical section, the same one that bumps
+        // `_feedEpoch` and raises `draining`, with `resetAsync` (a plain `queue.async`, safe under
+        // `lock`) and a `barrier()` once `lock` is released. Retiring it later, after the hardware
+        // drain, left a gap: a VideoToolbox callback landing between the unlock and the reset (with
+        // `draining` already false) took a new-epoch ticket that `orderedDelivery` still dropped as
+        // stale, and the reset then skipped past it, stalling every following frame until the stall
+        // guard gave up on it. Two things follow from the order used here:
+        //
+        // 1. **No ticket can be lost.** `draining` stays raised for the whole window in which
+        //    `orderedDelivery` might still be on the old epoch: it is lowered only in the second
+        //    critical section below, after `barrier()` has confirmed the `resetAsync` ran. No
+        //    thread can issue a new-epoch ticket until `orderedDelivery` is on that epoch.
+        // 2. **Nothing from before the flush is delivered during the drain.** A composition that
+        //    was in flight before this `flush()` and retires while `primary.flush()` / `el.flush()`
+        //    are still draining finds the epoch already moved and is dropped, so the draining gate
+        //    covers delivery as well as pairing.
+        //
+        // Concurrent `flush()`/`flush()` or `flush()`/`close()`: the whole of each call runs under
+        // `lifecycleLock`, so they never interleave (one cannot lower `draining` or clear the
+        // queues while the other still drains). Inside a call, `_feedEpoch`/`deliveryNextTicket`
+        // only ever move forward under `lock`, so `orderedDelivery`'s FIFO queue applies the
+        // resets in call order and neither can ever move backwards.
+        //
+        // `nextTicket` is stable across this whole call: no new ticket can
+        // be issued between this section and the one below, because
+        // `handleBaseLayerFrame`/`handleEnhancementLayerFrame` both gate on
+        // `!draining` under `lock`, and `draining` does not go false until
+        // after the drain completes.
+        lock.lock()
+        guard !isClosed else { lock.unlock(); return }
+        _feedEpoch &+= 1
+        draining = true
+        // Here, not with the queues below: the demux thread may feed post-seek packets while this
+        // thread waits on the drain, and those must start from the next IRAP.
+        pictureAlignment.reset()
+        // Same reason, and the same section: RPUs the demux thread records for post-seek packets
+        // during the drain must survive it, so the side data resets here, before any of them can
+        // exist, and not after the drain.
+        lastGoodParams = nil
+        lastGoodDMNAL = nil
+        borrowedParamsRun = 0
+        sideDataRing.removeAll()
+        let epoch = _feedEpoch
+        let nextTicket = deliveryNextTicket
+        let primary = primaryDecoder
+        let el = enhancementDecoder
+        // The sub-decoders move to the new epoch in this same critical section. The host feeds the
+        // demux thread's packets concurrently with a seek's flush: it reads the new epoch the moment
+        // it is published, and hands it down with the packet. Were the sub-decoders to move only when
+        // their own `flush()` runs below, a post-seek packet fed in that window would pass the gate
+        // here and be refused by a sub-decoder still on the old epoch, losing the post-seek IRAP
+        // (garbage until the next keyframe). `adoptFeedEpoch` takes only the sub-decoder's leaf
+        // `epochLock`, never its `lock`, so it cannot nest against the VideoToolbox callbacks that
+        // wait on this lock. DEC-4 still holds: a pre-seek packet is refused from here on, and a
+        // sub-decoder's `flush()` below serialises against any packet already inside its
+        // check-and-send.
+        primary.adoptFeedEpoch(epoch)
+        el?.adoptFeedEpoch(epoch)
+        orderedDelivery.resetAsync(epoch: epoch, nextTicket: nextTicket)
+        lock.unlock()
+
+        #if DEBUG
+        // Test seam only: lets a test drive a ticket through the window a
+        // post-flush ticket could be lost in if the reset moved back out of
+        // the critical section above — right after this
+        // section's `unlock()`, before the `barrier()` below has confirmed
+        // the `resetAsync` above has run — without a real GPU or
+        // VideoToolbox callback. See `raceTicketForTesting`.
+        flushRaceHookForTesting?()
+        #endif
+
+        // Waits for the `resetAsync` enqueued above to actually run (and for
+        // anything already ahead of it in `orderedDelivery`'s queue to
+        // finish first), with no decoder lock held — this cannot nest
+        // inside, or be nested by, any lock a concurrent `fulfil`/`emit`
+        // might touch (I8).
+        orderedDelivery.barrier()
+
+        // Drain both hardware decoders now that `orderedDelivery` is
+        // provably on the new epoch: `HardwareVideoDecoder.flush()` waits
+        // for the frames VideoToolbox still owes, which arrive through the
+        // normal callbacks while this thread is blocked inside it, but
+        // `draining` (still up) drops them at the pairing gate before they
+        // can take a ticket, and any composition that was already
+        // in flight before this `flush()` is dropped by the epoch check the
+        // instant it reaches `fulfil` instead.
+        //
+        // Post-seek frames that VideoToolbox outputs while this drain is still running (a post-seek
+        // packet is now accepted from the moment the epoch moved) meet `draining` and are dropped.
+        // That is deliberate and costs nothing visible: the drain cannot tell them from the pre-seek
+        // frames it is waiting for, they are decoded from the IRAP onwards, which the host's
+        // `skipUntilPTS` pre-roll discards anyway until the seek target; and a dropped output frame
+        // does not affect decoding, VideoToolbox's reference state is intact. What it can cost is
+        // pairing: a frame dropped on one layer and not on the other leaves its partner waiting, and
+        // a waiting base frame goes out base-layer only once `maxLayerSkewFrames` newer ones have
+        // arrived. So the first few frames after a seek can be base-layer only (how many depends on
+        // how many frames the two sessions output during the drain), and the base frames dropped
+        // during the drain are never shown.
+        primary.flushKeepingEpoch()
+        el?.flushKeepingEpoch()
+
+        // Now that nothing more can arrive, reset pairing and let new tickets flow again. (The
+        // side-data ring is not touched here: see the first critical section.)
+        lock.lock()
+        draining = false
+        blFrameQueue.removeAll()
+        elFrameQueue.removeAll()
+        blArrivalSeq = 0
+        settledBlKeys.removeAll()
+        composeResultLock.lock(); summaryComposedFrames = 0; summaryComposeFailures = 0; composeResultLock.unlock()
+        summaryBypassNoEL = 0
+        summaryBypassNoRPU = 0
+        summaryDropStaleEL = 0
+        summaryPrunedEL = 0
+        summaryBorrowedParams = 0
+        summaryMaxObservedSkew = 0
+        lastSummaryTimestamp = 0
+        lock.unlock()
+
+        composer?.flush()
+    }
+
+    func close() {
+        lifecycleLock.lock()
+        defer { lifecycleLock.unlock() }
+        // dolby-vision-fel.md §5.8: `close()` resets every field of stream state, so a
+        // reopened instance could not inherit the MEL latch, a stale
+        // `primaryDecoderInitialized`, BL parameter sets, `frameIndex` or
+        // `timeBase` — and then makes reopening impossible anyway: the decoder
+        // is single use and `open` after this refuses with `decoderClosed`.
+        // Epoch limitation: the bump below only retires `decode(packet:epoch:)`
+        // callers that pass an epoch. The DVR-reseed path calls `decode` with
+        // `epoch: nil`, which never matches and is never retired by the epoch —
+        // those packets (and any thread already past the entry gate) are stopped
+        // by the `isClosed` checks in `decode`, `ensure*Decoder` and the frame
+        // handlers, not by the epoch. Delivery itself IS stopped by the epoch,
+        // via `orderedDelivery` below.
+        //
+        // As in `flush()`, `orderedDelivery.resetAsync` is enqueued from
+        // inside THIS critical section — the same one that bumps `_feedEpoch`,
+        // zeroes `deliveryNextTicket` and sets `isClosed`. Nothing can issue a ticket after
+        // this section unlocks (`isClosed` gates every entry point), so
+        // there is no gap for one to race `resetAsync` in, but keeping the
+        // same enqueue-under-lock shape as `flush()` means a `flush()`/
+        // `close()` race is decided the same way in both directions: `lock`
+        // fixes the order the two calls' `resetAsync`s land in
+        // `orderedDelivery`'s queue, and `_feedEpoch` only ever increases
+        // under that same lock, so whichever lands later always carries the
+        // larger epoch.
+        lock.lock()
+        _feedEpoch &+= 1
+        draining = false
+        deliveryNextTicket = 0
+        pictureAlignment = Self.makeAlignment()
+        blFrameQueue.removeAll()
+        elFrameQueue.removeAll()
+        blArrivalSeq = 0
+        settledBlKeys.removeAll()
+        lastGoodParams = nil
+        lastGoodDMNAL = nil
+        borrowedParamsRun = 0
+        sideDataRing.removeAll()
+        composeResultLock.lock(); summaryComposedFrames = 0; summaryComposeFailures = 0; composeResultLock.unlock()
+        summaryBypassNoEL = 0
+        summaryBypassNoRPU = 0
+        summaryDropStaleEL = 0
+        summaryPrunedEL = 0
+        summaryBorrowedParams = 0
+        summaryMaxObservedSkew = 0
+        lastSummaryTimestamp = 0
+        isFEL = false
+        isMEL = false
+        streamClassified = false
+        frameIndex = 0
+        primaryDecoderInitialized = false
+        blVPS = nil
+        blSPS = nil
+        blPPS = nil
+        elVPS = nil
+        elSPS = nil
+        elPPS = nil
+        enhancementOpenFailure = nil
+        timeBase = AVRational(num: 1, den: 90000)
+        _skipUntilPTS = nil
+        isClosed = true
+        let epoch = _feedEpoch
+        let nextTicket = deliveryNextTicket
+        // Swap the enhancement decoder out under the lock and close it after releasing
+        // it: `close()` runs on the host thread while VideoToolbox callbacks may still
+        // be delivering into `handleEnhancementLayerFrame`.
+        let el = enhancementDecoder
+        enhancementDecoder = nil
+        orderedDelivery.resetAsync(epoch: epoch, nextTicket: nextTicket)
+        lock.unlock()
+
+        // Same guarantee as `flush()`: nothing tagged with the
+        // pre-close epoch reaches `onFrame` after this returns. Clearing the
+        // callback only after that is what makes "nothing is delivered after
+        // `close()` returns" hold even for the frame that was legitimately
+        // mid-delivery when this call started.
+        orderedDelivery.barrier()
+        orderedDelivery.setOnFrame(nil)
+
+        // Sessions first: closing them drains the frames VideoToolbox still owes, and those can still be
+        // holding or about to take pool buffers. Only then flush the composer and release its pool.
+        primaryDecoder.close()
+        el?.close()
+        composer?.flush()
+        composer?.releaseOutputPool()
+    }
+
+    // MARK: - Test seams
+    //
+    // Both frame handlers are driven by VideoToolbox callbacks, which a unit test cannot produce
+    // on demand. These put the decoder in the state `decode(packet:)` reaches on a real stream,
+    // so `DualLayerVideoDecoderTests` can exercise pairing, ordering, metadata and flush with
+    // synthetic buffers.
+
+    #if DEBUG
+    /// Regression seam for the post-flush ticket race: if set, `flush()`
+    /// calls this exactly once, synchronously, in the gap right after the
+    /// critical section that bumps `_feedEpoch`, captures `nextTicket` and
+    /// enqueues `orderedDelivery.resetAsync` releases `lock`, but before the
+    /// `orderedDelivery.barrier()` call that waits for it to actually run.
+    /// This is the window a post-flush ticket could be lost in — see the
+    /// comment at the top of `flush()`. Paired with `raceTicketForTesting`, this drives a ticket
+    /// through that window deterministically, without a real GPU or
+    /// VideoToolbox callback, so a regression that reopens the window (e.g.
+    /// moving the `resetAsync` call back outside the lock) fails a test
+    /// instead of waiting on a sub-microsecond production race.
+    var flushRaceHookForTesting: (() -> Void)?
+
+    /// Called at the top of every `flush()`, before it queues for `lifecycleLock`. Lets a test know a
+    /// second flush has reached the lock without sleeping to find out.
+    var flushWillTakeLifecycleLockHookForTesting: (() -> Void)?
+
+    /// Waits until every composition started so far has finished and handed its frame to
+    /// `orderedDelivery`, then until that queue has run everything enqueued ahead of this call. After
+    /// it returns, a frame that was going to be delivered (or dropped as stale) by work already in
+    /// flight has been, which is what a "nothing more arrives" assertion needs; it is a condition
+    /// wait, not a delay. Compositions that never finish (a gated fake) would make it wait forever, so a
+    /// test that holds one releases it first.
+    func quiesceForTesting() {
+        while true {
+            composeResultLock.lock()
+            let idle = composeRequestsStarted == composeRequestsHandedOff
+            composeResultLock.unlock()
+            if idle { break }
+            usleep(500)
+        }
+        orderedDelivery.barrier()
+    }
+
+    /// Issues a ticket the same way `handleBaseLayerFrame` would — under
+    /// `lock`, in decode order, tagged with the current epoch — and hands it
+    /// straight to `orderedDelivery`, bypassing the `draining` gate that
+    /// would otherwise stop a real VideoToolbox callback from reaching here
+    /// at this point. Standing in for "a VideoToolbox callback landing in
+    /// the gap": the gate no
+    /// longer needs to stop it, now that the epoch is retired before
+    /// `draining` can go false, but this seam drives the ordering itself,
+    /// not the gate, so that guarantee is what is actually under test.
+    func raceTicketForTesting(buffer: CVPixelBuffer, pts: CMTime) {
+        lock.lock()
+        let ticket = nextDeliveryTicket()
+        let epoch = _feedEpoch
+        lock.unlock()
+        orderedDelivery.fulfil(
+            ticket: ticket, epoch: epoch,
+            DeliveredFrame(buffer: SendableBuffer(value: buffer), pts: pts, hdr10Data: nil, dmNAL: nil))
+    }
+    #endif
+
+    /// Marks the stream as FEL with the enhancement-layer decoder engaged, or as single layer.
+    /// The engaged decoder is never opened: pairing only checks that one exists.
+    func primeForTesting(enhancementLayer: Bool) {
+        lock.lock()
+        defer { lock.unlock() }
+        isFEL = enhancementLayer
+        isMEL = false
+        streamClassified = true
+        if enhancementLayer {
+            // Only engage the EL decoder when a composer exists. Without
+            // one, the production path (`decode(packet:)`) never reaches
+            // `ensureEnhancementDecoder`, so neither does the test seam.
+            if enhancementDecoder == nil, composer != nil {
+                let decoder = HardwareVideoDecoder()
+                decoder.useCustomBlockSource = true
+                enhancementDecoder = decoder
+            }
+        } else {
+            enhancementDecoder = nil
+        }
+    }
+
+    /// Puts the decoder in the classified state `decode(packet:)` reaches for `kind`
+    ///: FEL engages the enhancement-layer stub, MEL never does. Fresh-decoder
+    /// assumption, like `primeForTesting`: the stub is never opened, pairing only checks
+    /// that one exists.
+    func primeStreamForTesting(_ kind: DoviRpuConverter.StreamKind) {
+        lock.lock()
+        defer { lock.unlock() }
+        streamClassified = true
+        switch kind {
+        case .fel:
+            isFEL = true
+            isMEL = false
+            // Only engage the EL decoder when a composer exists.
+            if enhancementDecoder == nil, composer != nil {
+                let decoder = HardwareVideoDecoder()
+                decoder.useCustomBlockSource = true
+                enhancementDecoder = decoder
+            }
+        case .mel:
+            isFEL = false
+            isMEL = true
+            enhancementDecoder = nil
+        case .undetermined:
+            isFEL = false
+            isMEL = false
+            enhancementDecoder = nil
+        }
+    }
+
+    /// Applies one `separateDualLayers` result's classification exactly as
+    /// `decode(packet:)` does, so tests can drive classification sequences without real packets.
+    func classifyPacketResultForTesting(_ result: DoviRpuConverter.DualLayerPacketResult) {
+        applyStreamClassification(DoviRpuConverter.classifyStream(result))
+    }
+
+    /// The feed epoch of the lazily opened enhancement decoder, nil until it exists.
+    var enhancementFeedEpochForTesting: UInt64? {
+        lock.lock()
+        let el = enhancementDecoder
+        lock.unlock()
+        return (el as? HardwareVideoDecoder)?.feedEpoch
+    }
+
+    /// The stream classification `decode(packet:)` has latched so far.
+    var streamClassification: DoviRpuConverter.StreamKind {
+        lock.lock()
+        defer { lock.unlock() }
+        if isMEL { return .mel }
+        if isFEL { return .fel }
+        return .undetermined
+    }
+
+    var streamClassificationForTesting: DoviRpuConverter.StreamKind { streamClassification }
+
+    /// The decode-path gate for opening and feeding the enhancement decoder: only a classified FEL stream with a composer engages it; MEL or
+    /// no composer never does.
+    func engagesEnhancementLayerForTesting() -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return isFEL && !isMEL && composer != nil
+    }
+
+    /// Stream state `close()` must reset: classification latch,
+    /// primary-decoder readiness, composition counter and EL engagement, plus
+    /// the single-use flag that makes `open` refuse after `close()`. Queue,
+    /// cache, ticket and epoch counts are included so tests can assert the reset
+    /// explicitly rather than relying on delivery silence alone.
+    struct DecoderStateSnapshot: Sendable {
+        var isClosed: Bool
+        var isFEL: Bool
+        var isMEL: Bool
+        var streamClassified: Bool
+        var primaryDecoderInitialized: Bool
+        var frameIndex: UInt32
+        var enhancementEngaged: Bool
+        var blQueueCount: Int
+        var elQueueCount: Int
+        var rpuCacheCount: Int
+        var dmRpuCacheCount: Int
+        var deliveryPendingCount: Int
+        var deliveryNextTicket: UInt64
+        var deliveryNextToEmit: UInt64
+        var feedEpoch: UInt64
+        var draining: Bool
+        var timeBaseNum: Int32
+        var timeBaseDen: Int32
+        var hasBLVPS: Bool
+        var hasBLSPS: Bool
+        var hasBLPPS: Bool
+        var hasELVPS: Bool
+        var hasELSPS: Bool
+        var hasELPPS: Bool
+        var hasSkipUntilPTS: Bool
+        var hasOnFrame: Bool
+        var hasComposer: Bool
+    }
+
+    var stateSnapshotForTesting: DecoderStateSnapshot {
+        // Decoder-lock fields first, then release before touching
+        // `orderedDelivery`: its `queue.sync` reads never need the
+        // decoder lock, and not holding both at once keeps this snapshot from
+        // becoming the one place that reintroduces a lock/queue dependency.
+        lock.lock()
+        let isClosed = self.isClosed
+        let isFEL = self.isFEL
+        let isMEL = self.isMEL
+        let streamClassified = self.streamClassified
+        let primaryDecoderInitialized = self.primaryDecoderInitialized
+        let frameIndex = self.frameIndex
+        let enhancementEngaged = isFEL && !isMEL && enhancementDecoder != nil && composer != nil
+        let blQueueCount = blFrameQueue.count
+        let elQueueCount = elFrameQueue.count
+        let rpuCacheCount = sideDataRing.paramsCount
+        let dmRpuCacheCount = sideDataRing.dmNALCount
+        let deliveryNextTicket = self.deliveryNextTicket
+        let feedEpoch = _feedEpoch
+        let draining = self.draining
+        let timeBaseNum = timeBase.num
+        let timeBaseDen = timeBase.den
+        let hasBLVPS = blVPS != nil
+        let hasBLSPS = blSPS != nil
+        let hasBLPPS = blPPS != nil
+        let hasELVPS = elVPS != nil
+        let hasELSPS = elSPS != nil
+        let hasELPPS = elPPS != nil
+        let hasSkipUntilPTS = _skipUntilPTS != nil
+        let hasComposer = composer != nil
+        lock.unlock()
+
+        return DecoderStateSnapshot(
+            isClosed: isClosed,
+            isFEL: isFEL,
+            isMEL: isMEL,
+            streamClassified: streamClassified,
+            primaryDecoderInitialized: primaryDecoderInitialized,
+            frameIndex: frameIndex,
+            enhancementEngaged: enhancementEngaged,
+            blQueueCount: blQueueCount,
+            elQueueCount: elQueueCount,
+            rpuCacheCount: rpuCacheCount,
+            dmRpuCacheCount: dmRpuCacheCount,
+            deliveryPendingCount: orderedDelivery.pendingCountForTesting,
+            deliveryNextTicket: deliveryNextTicket,
+            deliveryNextToEmit: orderedDelivery.nextToEmitForTesting,
+            feedEpoch: feedEpoch,
+            draining: draining,
+            timeBaseNum: timeBaseNum,
+            timeBaseDen: timeBaseDen,
+            hasBLVPS: hasBLVPS,
+            hasBLSPS: hasBLSPS,
+            hasBLPPS: hasBLPPS,
+            hasELVPS: hasELVPS,
+            hasELSPS: hasELSPS,
+            hasELPPS: hasELPPS,
+            hasSkipUntilPTS: hasSkipUntilPTS,
+            hasOnFrame: orderedDelivery.hasOnFrameForTesting,
+            hasComposer: hasComposer
+        )
+    }
+
+    /// Caches what `decode(packet:)` would have cached for the packet at `pts`: the composer's
+    /// reshaping parameters and the Profile 8.1 RPU NAL attached as display metadata.
+    /// One call is one packet, in decode order: a nil `params` is a packet with a missing RPU (or, with
+    /// `usesPrevious`, one that says to keep the previous mapping), resolved exactly as in production.
+    func seedRPUForTesting(pts: CMTime, params: DoviMetalParams?, displayMetadataNAL: [UInt8]?, usesPrevious: Bool = false, disableResidual: Bool = false) {
+        lock.lock()
+        defer { lock.unlock() }
+        let key = Self.canonicalKey(pts: pts)
+        recordSideData(key: key, params: params, dmNAL: displayMetadataNAL, usesPrevious: usesPrevious, disableResidual: disableResidual)
+    }
+}
diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 125480982..7823a08b8 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -79,10 +79,38 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     /// Protects `session` across the demux thread (decode), main thread (close/flush), and VT callback (delivery).
     private let lock = NSLock()
 
-    /// AE#492: guarded by `lock`, the same one `flush()` and `decode(packet:epoch:)` take.
+    /// When true, wrap the packet's AVBuffer with a CMBlockBuffer that holds
+    /// an `av_buffer_ref` and unrefs it on disposal (dolby-vision-fel.md §5.4).
+    var useCustomBlockSource: Bool = false
+
+    #if DEBUG
+    /// Called after a packet has been handed to VideoToolbox (whatever the status it returned), and
+    /// not for one the epoch gate or a missing session refused.
+    var onSubmittedToVideoToolboxForTesting: (() -> Void)?
+    var onBlockBufferAllocatedForTesting: ((CMBlockBuffer) -> Void)?
+    #endif
+
+    /// AE#492: the epoch a fed packet must carry. Guarded by `epochLock`, a leaf lock held only for a
+    /// read or a write of this integer (nothing is taken, awaited or called while it is held), so
+    /// `DualLayerVideoDecoder` can move this decoder's epoch from inside its own critical section
+    /// without nesting into `lock`, which `decode` may hold across a blocking VideoToolbox call whose
+    /// output callbacks need the owner's lock. `decode` and `flush()` still read and bump it while
+    /// holding `lock`, so a flush and a feed cannot interleave; `adoptFeedEpoch` alone moves it
+    /// without `lock`, and only ever to the owner's current epoch.
     private var _feedEpoch: UInt64 = 0
-    var feedEpoch: UInt64 {
-        lock.lock(); defer { lock.unlock() }; return _feedEpoch
+    private let epochLock = NSLock()
+    private var currentEpoch: UInt64 {
+        epochLock.lock(); defer { epochLock.unlock() }; return _feedEpoch
+    }
+    var feedEpoch: UInt64 { currentEpoch }
+
+    /// Moves this decoder onto the feed epoch its owner is already in. `DualLayerVideoDecoder` calls it
+    /// (a) when it opens the enhancement decoder lazily, after a `flush()` may have moved its own
+    /// epoch, and (b) from inside its `flush()` critical section, so that a post-seek packet fed with
+    /// the new epoch while the owner is still draining this decoder is accepted, instead of being
+    /// dropped as stale by a decoder that has not yet been flushed. Takes only `epochLock`.
+    func adoptFeedEpoch(_ epoch: UInt64) {
+        epochLock.lock(); _feedEpoch = epoch; epochLock.unlock()
     }
 
     /// AE#739: the system invalidates the session behind our back (iOS screen lock, media services
@@ -102,6 +130,9 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     private var awaitingKeyframe = false
     private var droppedAwaitingKeyframe = 0
     private var decoderSpecification: NSDictionary?
+    /// Guarded by `lock`. False for a session opened from parameter sets, which `makeSession` and a
+    /// rebuild then create without `PropagatePerFrameHDRDisplayMetadata`.
+    private var propagatesHDRDisplayMetadata = true
     private var pixelBufferAttributes: NSDictionary?
 
     /// Heap-allocated box carrying a weak self reference for the C decompression callback's refCon.
@@ -114,6 +145,71 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         init(_ decoder: HardwareVideoDecoder) { self.decoder = decoder }
     }
 
+    /// Keeps `packet.buf` alive for the lifetime of a CMBlockBuffer that wraps
+    /// the packet's data without copying it (dolby-vision-fel.md §5.4).
+    final class CustomBlockSource {
+        var avBuf: UnsafeMutablePointer<AVBufferRef>?
+        let dataPtr: UnsafeMutableRawPointer
+
+        /// `data` is the packet's own payload pointer. It is not always `buf->data`: the Matroska
+        /// demuxer hands out packets whose `data` sits inside a larger buffer (observed at +4 on P7
+        /// MKV remuxes), so block memory taken from `buf->data` starts early and VideoToolbox sees
+        /// a corrupt sample (-12909). Defaults to `buf->data` for callers that own the whole buffer.
+        init?(buf: UnsafeMutablePointer<AVBufferRef>, data: UnsafeMutablePointer<UInt8>? = nil) {
+            guard let data = data ?? buf.pointee.data, let ref = av_buffer_ref(buf) else { return nil }
+            self.avBuf = ref
+            self.dataPtr = UnsafeMutableRawPointer(data)
+        }
+
+        func releaseBuffer() {
+            if avBuf != nil {
+                av_buffer_unref(&avBuf)
+            }
+        }
+
+        deinit {
+            releaseBuffer()
+        }
+    }
+
+    /// Wraps a packet's payload in a CMBlockBuffer without copying it. The block buffer owns
+    /// `blockSource` (and with it the `av_buffer_ref` of `packet.buf`) until CoreMedia frees the
+    /// block; if the buffer cannot be created the reference is released here, so the caller has
+    /// nothing to clean up. `dataLength` is the size of the payload when it differs from the block
+    /// (only a test needs that, to make the creation fail).
+    static func makeBlockBuffer(wrapping blockSource: CustomBlockSource, size: Int, dataLength: Int? = nil) -> (buffer: CMBlockBuffer?, status: OSStatus) {
+        var source = CMBlockBufferCustomBlockSource(
+            version: kCMBlockBufferCustomBlockSourceVersion,
+            AllocateBlock: { refCon, _ in
+                guard let refCon else { return nil }
+                let holder = Unmanaged<CustomBlockSource>.fromOpaque(refCon).takeUnretainedValue()
+                return holder.dataPtr
+            },
+            FreeBlock: { refCon, _memoryBlock, _size in
+                guard let refCon else { return }
+                let holder = Unmanaged<CustomBlockSource>.fromOpaque(refCon).takeRetainedValue()
+                holder.releaseBuffer()
+            },
+            refCon: Unmanaged.passRetained(blockSource).toOpaque()
+        )
+        var blockBuffer: CMBlockBuffer?
+        let status = CMBlockBufferCreateWithMemoryBlock(
+            allocator: kCFAllocatorDefault,
+            memoryBlock: nil,
+            blockLength: size,
+            blockAllocator: kCFAllocatorNull,
+            customBlockSource: &source,
+            offsetToData: 0,
+            dataLength: dataLength ?? size,
+            flags: kCMBlockBufferAssureMemoryNowFlag,
+            blockBufferOut: &blockBuffer
+        )
+        if status != kCMBlockBufferNoErr, let refCon = source.refCon {
+            Unmanaged<CustomBlockSource>.fromOpaque(refCon).takeRetainedValue().releaseBuffer()
+        }
+        return (blockBuffer, status)
+    }
+
     // MARK: - Lifecycle
 
     func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {
@@ -245,11 +341,14 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         )
         guard status == noErr, let created = sessionOut else { return (nil, status) }
         // Pass through per-frame HDR metadata for correct tone mapping; unknown-key set returns -12911 on older OSes (swallowed).
-        VTSessionSetProperty(
-            created,
-            key: kVTDecompressionPropertyKey_PropagatePerFrameHDRDisplayMetadata,
-            value: kCFBooleanTrue
-        )
+        // Not on a session opened from parameter sets: see `open(parameterSets:timeBase:onFrame:)`.
+        if propagatesHDRDisplayMetadata {
+            VTSessionSetProperty(
+                created,
+                key: kVTDecompressionPropertyKey_PropagatePerFrameHDRDisplayMetadata,
+                value: kCFBooleanTrue
+            )
+        }
         return (created, noErr)
     }
 
@@ -267,7 +366,7 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             VTDecompressionSessionInvalidate(old)
             session = nil
         }
-        _feedEpoch &+= 1
+        epochLock.lock(); _feedEpoch &+= 1; epochLock.unlock()
         let created = makeSession(formatDescription: formatDescription, refCon: refConBox)
         guard let fresh = created.session else {
             sessionLost = true
@@ -295,12 +394,111 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     }
     #endif
 
+    /// Opens a decoder session from raw HEVC parameter sets (VPS, SPS, PPS), used for the Enhancement Layer (EL)
+    /// in Dolby Vision Profile 7 dual-layer decoding.
+    func open(
+        parameterSets: [[UInt8]],
+        timeBase: AVRational,
+        onFrame: @escaping DecodedFrameHandler
+    ) throws {
+        self.onFrame = onFrame
+        self.timeBase = timeBase
+
+        guard parameterSets.count >= 3 else {
+            throw VideoDecoderError.noExtradata
+        }
+
+        var ptrs: [UnsafePointer<UInt8>] = []
+        var sizes: [Int] = []
+        var allocations: [UnsafeMutablePointer<UInt8>] = []
+        defer {
+            for a in allocations { a.deallocate() }
+        }
+        for ps in parameterSets {
+            let p = UnsafeMutablePointer<UInt8>.allocate(capacity: ps.count)
+            ps.withUnsafeBufferPointer { src in
+                if let base = src.baseAddress {
+                    p.initialize(from: base, count: ps.count)
+                }
+            }
+            allocations.append(p)
+            ptrs.append(UnsafePointer(p))
+            sizes.append(ps.count)
+        }
+
+        var fd: CMVideoFormatDescription?
+        let fdStatus = CMVideoFormatDescriptionCreateFromHEVCParameterSets(
+            allocator: kCFAllocatorDefault,
+            parameterSetCount: parameterSets.count,
+            parameterSetPointers: ptrs,
+            parameterSetSizes: sizes,
+            nalUnitHeaderLength: 4,
+            extensions: nil,
+            formatDescriptionOut: &fd
+        )
+        guard fdStatus == noErr, let formatDesc = fd else {
+            throw VideoDecoderError.formatDescriptionFailed(status: fdStatus)
+        }
+
+        let dims = CMVideoFormatDescriptionGetDimensions(formatDesc)
+        self.width = dims.width
+        self.height = dims.height
+
+        var decoderSpec: NSDictionary?
+        if #available(tvOS 17.0, iOS 17.0, *) {
+            decoderSpec = [
+                kVTVideoDecoderSpecification_RequireHardwareAcceleratedVideoDecoder: true,
+            ]
+        }
+
+        self.colorPrimaries = kCVImageBufferColorPrimaries_ITU_R_2020
+        self.colorTransfer = kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ
+        self.colorMatrix = kCVImageBufferYCbCrMatrix_ITU_R_2020
+
+        let pixelBufferAttrs: NSDictionary = [
+            kCVPixelBufferPixelFormatTypeKey: kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+            kCVPixelBufferIOSurfacePropertiesKey: NSDictionary(),
+            kCVPixelBufferMetalCompatibilityKey: true,
+        ]
+
+        let box = RefConBox(self)
+        let unmanaged = Unmanaged.passRetained(box)
+
+        // `session` is read by `decode`/`flush`/`close` on other threads: install it under `lock`.
+        lock.lock()
+        propagatesHDRDisplayMetadata = false
+        decoderSpecification = decoderSpec
+        pixelBufferAttributes = pixelBufferAttrs
+        let created = makeSession(formatDescription: formatDesc, refCon: unmanaged)
+        guard let createdSession = created.session else {
+            lock.unlock()
+            unmanaged.release()
+            throw VideoDecoderError.sessionCreationFailed(status: created.status)
+        }
+        formatDescription = formatDesc
+        session = createdSession
+        refConBox = unmanaged
+        lock.unlock()
+
+        // Deliberately no `kVTDecompressionPropertyKey_PropagatePerFrameHDRDisplayMetadata` here,
+        // unlike `open(stream:)`. This path builds the base layer's session when its parameter sets
+        // arrive in band, and the enhancement layer's session always. The dual-layer decoder
+        // attaches its own Dolby Vision RPU to every frame it delivers (composed or bypassed) from
+        // the RPU it extracted; letting VideoToolbox propagate HDR display metadata as well would put a
+        // second, possibly different, attachment on the base-layer buffer a bypassed frame goes out as.
+
+        EngineLog.emit(
+            "[HardwareVideoDecoder] opened secondary HEVC \(width)x\(height) 10-bit from parameter sets",
+            category: .swPlayback
+        )
+    }
+
     // MARK: - Decode
 
     func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64? = nil) {
         lock.lock()
         // AE#492: see `SoftwareVideoDecoder.decode`. Same rule, same lock as `flush()`.
-        if let epoch, epoch != _feedEpoch { lock.unlock(); return }
+        if let epoch, epoch != currentEpoch { lock.unlock(); return }
         guard session != nil, !sessionLost, let formatDesc = formatDescription else {
             lock.unlock()
             return
@@ -312,24 +510,43 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         // and AVPacket storage is reused for the next packet.
         guard let data = packet.pointee.data, packet.pointee.size > 0 else { return }
         let size = Int(packet.pointee.size)
-        let copied = UnsafeMutableRawPointer.allocate(byteCount: size, alignment: 1)
-        copied.copyMemory(from: data, byteCount: size)
 
         var blockBuffer: CMBlockBuffer?
-        let blockStatus = CMBlockBufferCreateWithMemoryBlock(
-            allocator: kCFAllocatorDefault,
-            memoryBlock: copied,
-            blockLength: size,
-            blockAllocator: kCFAllocatorDefault,  // ← matching dealloc allocator
-            customBlockSource: nil,
-            offsetToData: 0,
-            dataLength: size,
-            flags: 0,
-            blockBufferOut: &blockBuffer
-        )
+        var blockStatus: OSStatus = noErr
+        var copied: UnsafeMutableRawPointer?
+
+        if useCustomBlockSource,
+           let buf = packet.pointee.buf,
+           let blockSource = CustomBlockSource(buf: buf, data: data) {
+            // Design §5.4: no copy. The CMBlockBuffer holds an `av_buffer_ref` of
+            // `packet.buf` and unrefs it in FreeBlock, so VT can retain the data past
+            // the call without a copy.
+            (blockBuffer, blockStatus) = Self.makeBlockBuffer(wrapping: blockSource, size: size)
+            #if DEBUG
+            if let bb = blockBuffer {
+                onBlockBufferAllocatedForTesting?(bb)
+            }
+            #endif
+        } else {
+            // Fallback: copy into newly allocated memory when custom block source is disabled,
+            // packet has no AVBufferRef (e.g. synthetic test packet), or av_buffer_ref failed.
+            copied = UnsafeMutableRawPointer.allocate(byteCount: size, alignment: 1)
+            copied?.copyMemory(from: data, byteCount: size)
+            blockStatus = CMBlockBufferCreateWithMemoryBlock(
+                allocator: kCFAllocatorDefault,
+                memoryBlock: copied,
+                blockLength: size,
+                blockAllocator: kCFAllocatorDefault,
+                customBlockSource: nil,
+                offsetToData: 0,
+                dataLength: size,
+                flags: 0,
+                blockBufferOut: &blockBuffer
+            )
+        }
         guard blockStatus == kCMBlockBufferNoErr, let bb = blockBuffer else {
             // CMBlockBuffer takes ownership only on success; we own the allocation on failure.
-            copied.deallocate()
+            copied?.deallocate()
             return
         }
         let pts = SourceTimestampBounds.cmTime(ticks: packet.pointee.pts, timeBase: timeBase)
@@ -378,7 +595,7 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         // 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 }
+        if let epoch, epoch != currentEpoch { lock.unlock(); return }
         guard let session = self.session, !sessionLost else { lock.unlock(); return }
         var recoveredAfterDropping: Int?
         if awaitingKeyframe {
@@ -404,6 +621,9 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         let lostNow = decodeStatus == kVTInvalidSessionErr && !sessionLost
         if lostNow { sessionLost = true }
         lock.unlock()
+        #if DEBUG
+        onSubmittedToVideoToolboxForTesting?()
+        #endif
         if let recoveredAfterDropping {
             EngineLog.emit(
                 "[HardwareVideoDecoder] AE#739 recovered at keyframe pts=\(packet.pointee.pts) "
@@ -426,9 +646,18 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         }
     }
 
-    func flush() {
+    func flush() { flush(bumpingEpoch: true) }
+
+    /// The flush a `DualLayerVideoDecoder` makes: its owner has already moved this decoder's epoch with
+    /// `adoptFeedEpoch` (inside its own critical section), so bumping it again here would retire the
+    /// post-seek packets the owner has been feeding since.
+    func flushKeepingEpoch() { flush(bumpingEpoch: false) }
+
+    private func flush(bumpingEpoch: Bool) {
         lock.lock()
-        _feedEpoch &+= 1   // AE#492
+        if bumpingEpoch {   // AE#492
+            epochLock.lock(); _feedEpoch &+= 1; epochLock.unlock()
+        }
         let session = self.session
         lock.unlock()
         guard let session else { return }
diff --git a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
index a1a87601d..800ba93ce 100644
--- a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
+++ b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
@@ -46,6 +46,15 @@ enum VideoDecoderError: Error, LocalizedError {
     case noExtradata
     case formatDescriptionFailed(status: OSStatus)
     case sessionCreationFailed(status: OSStatus)
+    /// `DualLayerVideoDecoder` is single use (dolby-vision-fel.md §5.8): `open` after `close` refuses
+    /// with this instead of inheriting the previous stream's state. Thrown rather than a
+    /// trapping precondition so host misuse surfaces as an error and tests can assert it.
+    case decoderClosed
+    /// No Metal device or shader compilation failed; FEL composition cannot run.
+    /// Thrown from `open()` for a decoder built without a composer. The software host does not get
+    /// there in production: it builds the composer first and decodes the base layer alone when that
+    /// fails.
+    case composerUnavailable
 
     var errorDescription: String? {
         switch self {
@@ -54,6 +63,8 @@ enum VideoDecoderError: Error, LocalizedError {
         case .noExtradata: "Missing codec extradata"
         case .formatDescriptionFailed(let s): "Format description failed (\(s))"
         case .sessionCreationFailed(let s): "Decoder session failed (\(s))"
+        case .decoderClosed: "Decoder is closed (single use)"
+        case .composerUnavailable: "Dolby Vision FEL composer unavailable (no Metal device or shader compilation failed)"
         }
     }
 }
diff --git a/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift b/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
new file mode 100644
index 000000000..8fc7b442d
--- /dev/null
+++ b/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
@@ -0,0 +1,105 @@
+import Foundation
+import CoreVideo
+import CoreMedia
+import os
+
+/// Diagnostic: how much the enhancement-layer residual changes the picture. With `AETHER_FEL_MEASURE=N`
+/// in the environment, every Nth composed frame is composed a second time with the residual off (what a
+/// minimal enhancement layer would give) and the two are compared in 10-bit codes per plane: absolute
+/// differences for size, and the signed mean (FEL minus MEL) for direction, so a residual that brightens
+/// shows as a positive `signed`. Dithering
+/// is disabled in both so only the residual differs. Off by default; costs two extra compositions per
+/// sampled frame, which can briefly take pool buffers, so it is for measurement runs, not playback.
+enum FelResidualMeasure {
+    static let stride: Int = {
+        guard let v = ProcessInfo.processInfo.environment["AETHER_FEL_MEASURE"], let n = Int(v), n > 0 else { return 0 }
+        return n
+    }()
+
+    private static let queue = DispatchQueue(label: "aether.fel.measure", qos: .utility)
+
+    /// True while a sample is queued or running. A sample retains its two source buffers and takes two
+    /// pool buffers, so a sample that arrives while one is in flight is skipped rather than queued
+    /// behind it: a stride smaller than the sampling time would otherwise pile up held buffers.
+    private static let inFlight = OSAllocatedUnfairLock(initialState: false)
+
+    static func sampleIfDue(composer: DoviFelComposer, base: CVPixelBuffer, enhancement: CVPixelBuffer,
+                            params: DoviMetalParams, frameIndex: UInt32, pts: CMTime) {
+        guard stride > 0, Int(frameIndex) % stride == 0 else { return }
+        guard inFlight.withLock({ busy in
+            if busy { return false }
+            busy = true
+            return true
+        }) else { return }
+        let b = SendableBuffer(value: base), e = SendableBuffer(value: enhancement)
+        queue.async {
+            defer { inFlight.withLock { $0 = false } }
+            var full = params; full.ditherMode = .none; full.flags.remove(.disableResidual)
+            var mel = params; mel.ditherMode = .none; mel.flags.insert(.disableResidual)
+            guard let a = composer.compose(baseBuffer: b.value, enhancementBuffer: e.value, params: full, frameIndex: frameIndex),
+                  let m = composer.compose(baseBuffer: b.value, enhancementBuffer: e.value, params: mel, frameIndex: frameIndex)
+            else { return }
+            let planes = ["Y", "Cb", "Cr"]
+            var parts: [String] = []
+            for (k, name) in planes.enumerated() {
+                let s = stats(a, m, plane: k)
+                parts.append(String(format: "%@ diff=%.2f%% mean=%.3f signed=%+.3f p99=%d max=%d ge2=%.3f%% ge4=%.3f%%",
+                                    name, s.diffPct, s.mean, s.signedMean, s.p99, s.max, s.ge2Pct, s.ge4Pct))
+                if k == 0 {
+                    parts.append("Yband[0-255|256-511|512-767|768+] mean=" + s.bandMean.map { String(format: "%.2f", $0) }.joined(separator: "/")
+                                 + " signed=" + s.bandSignedMean.map { String(format: "%+.2f", $0) }.joined(separator: "/")
+                                 + " share%=" + s.bandFrac.map { String(format: "%.1f", $0) }.joined(separator: "/"))
+                }
+            }
+            EngineLog.emit("[FELMeasure] pts=\(String(format: "%.3f", pts.seconds)) " + parts.joined(separator: " | "), category: .swPlayback)
+        }
+    }
+
+    private struct Stats { var diffPct = 0.0, mean = 0.0, signedMean = 0.0, p99 = 0, max = 0, ge2Pct = 0.0, ge4Pct = 0.0, bandMean = [Double](repeating: 0, count: 4), bandSignedMean = [Double](repeating: 0, count: 4), bandFrac = [Double](repeating: 0, count: 4) }
+
+    private static func stats(_ x: CVPixelBuffer, _ y: CVPixelBuffer, plane k: Int) -> Stats {
+        CVPixelBufferLockBaseAddress(x, .readOnly); CVPixelBufferLockBaseAddress(y, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(x, .readOnly); CVPixelBufferUnlockBaseAddress(y, .readOnly) }
+        let p = k == 0 ? 0 : 1
+        let w = CVPixelBufferGetWidthOfPlane(x, p), h = CVPixelBufferGetHeightOfPlane(x, p)
+        let stx = CVPixelBufferGetBytesPerRowOfPlane(x, p) / 2, sty = CVPixelBufferGetBytesPerRowOfPlane(y, p) / 2
+        let px = CVPixelBufferGetBaseAddressOfPlane(x, p)!.assumingMemoryBound(to: UInt16.self)
+        let py = CVPixelBufferGetBaseAddressOfPlane(y, p)!.assumingMemoryBound(to: UInt16.self)
+        var hist = [Int](repeating: 0, count: 1024)
+        var bandSum = [Int](repeating: 0, count: 4), bandSigned = [Int](repeating: 0, count: 4), bandN = [Int](repeating: 0, count: 4)
+        var signedSum = 0
+        let comps = k == 0 ? 1 : 2, off = k == 2 ? 1 : 0
+        for row in 0..<h {
+            for col in 0..<w {
+                let i = col * comps + (comps == 2 ? off : 0)
+                let a = Int(px[row * stx + i] >> 6), b = Int(py[row * sty + i] >> 6)
+                let d = abs(a - b)
+                hist[min(d, 1023)] += 1
+                signedSum += a - b
+                if k == 0 { let band = min(b >> 8, 3); bandSum[band] += d; bandSigned[band] += a - b; bandN[band] += 1 }
+            }
+        }
+        let n = w * h
+        var s = Stats()
+        var sum = 0, cum = 0, p99Set = false
+        for d in 0..<1024 {
+            sum += d * hist[d]
+            cum += hist[d]
+            if hist[d] > 0 { s.max = d }
+            if !p99Set, cum * 100 >= n * 99 { s.p99 = d; p99Set = true }
+        }
+        s.diffPct = Double(n - hist[0]) * 100 / Double(n)
+        s.mean = Double(sum) / Double(n)
+        s.signedMean = Double(signedSum) / Double(n)
+        s.ge2Pct = Double(hist[2...].reduce(0, +)) * 100 / Double(n)
+        s.ge4Pct = Double(hist[4...].reduce(0, +)) * 100 / Double(n)
+        for i in 0..<4 {
+            if bandN[i] > 0 {
+                s.bandMean[i] = Double(bandSum[i]) / Double(bandN[i])
+                s.bandSignedMean[i] = Double(bandSigned[i]) / Double(bandN[i])
+            }
+            s.bandFrac[i] = Double(bandN[i]) * 100 / Double(n)
+        }
+        return s
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviCpuModelTests.swift b/Tests/AetherEngineTests/DoviCpuModelTests.swift
new file mode 100644
index 000000000..9d2786ed5
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviCpuModelTests.swift
@@ -0,0 +1,440 @@
+import Testing
+import Foundation
+import CoreVideo
+@testable import AetherEngine
+
+/// M8: an independent model of the composition, written from the RPU syntax and the reshaping
+/// equations rather than from the shader, and compared with the GPU on frames captured from real
+/// titles. The real titles carry what synthetic test content cannot produce (multi-piece luma curves,
+/// MMR chroma, large NLQ scales), so this is the check on those paths.
+///
+/// The model works in `Double` and `Int64`, evaluates the curves with explicit `pow`, and samples the
+/// enhancement layer with its own bilinear filter. It compares the un-quantised 12-bit VDR code
+/// (`DoviDither.debugRawVDR`), so the final rounding cannot hide a disagreement.
+///
+/// What it settles: arithmetic, piece selection, MMR term layout, NLQ, clamps. What it cannot: the
+/// spec readings the shader and the model share by construction (the chroma-site luma filter, the
+/// half-step NLQ reconstruction); those were settled against DoViBaker, an independent implementation.
+struct DoviCpuModelTests {
+
+    // MARK: - Planes
+
+    /// One P010 plane as 10-bit codes, `components` interleaved samples per pixel.
+    struct Plane {
+        let width: Int, height: Int, components: Int
+        let raw: [UInt16]
+        func code(_ x: Int, _ y: Int, _ c: Int = 0) -> Int {
+            Int(raw[(y * width + x) * components + c] >> 6)
+        }
+        /// Raw 16-bit word, for the enhancement-layer filter (the GPU filters the UNORM word).
+        func word(_ x: Int, _ y: Int, _ c: Int = 0) -> Double {
+            Double(raw[(y * width + x) * components + c])
+        }
+    }
+
+    static func plane(_ b: CVPixelBuffer, _ index: Int, components: Int) -> Plane {
+        CVPixelBufferLockBaseAddress(b, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(b, .readOnly) }
+        let w = CVPixelBufferGetWidthOfPlane(b, index), h = CVPixelBufferGetHeightOfPlane(b, index)
+        let stride = CVPixelBufferGetBytesPerRowOfPlane(b, index) / 2
+        let base = CVPixelBufferGetBaseAddressOfPlane(b, index)!.assumingMemoryBound(to: UInt16.self)
+        var out = [UInt16](); out.reserveCapacity(w * h * components)
+        for y in 0..<h { for x in 0..<(w * components) { out.append(base[y * stride + x]) } }
+        return Plane(width: w, height: h, components: components, raw: out)
+    }
+
+    // MARK: - The model
+
+    struct Model {
+        let p: DoviMetalParams
+        let blMax: Double
+        let scale: Double
+
+        init(_ p: DoviMetalParams) {
+            self.p = p
+            blMax = Double(p.blMax) + 1   // 2^bits, as the kernels normalise
+            scale = Double(p.vdrScale)
+        }
+
+        /// The piece that owns `v`: the last pivot `v` has reached.
+        func piece(_ c: DoviPolynomialParams, _ v: Int) -> Int {
+            let last = Int(c.numPivots) - 2
+            var k = 0
+            for i in 0...max(last, 0) where v >= Int(c.pivots[i]) { k = i }
+            return min(max(k, 0), max(last, 0))
+        }
+
+        /// Normalised prediction of one component.
+        func predict(_ c: DoviPolynomialParams, _ mmr: DoviMmrParams, blValue: Int,
+                     y: Double, u: Double, v: Double) -> Double {
+            if c.numPivots < 2 { return Double(blValue) / blMax }
+            let k = piece(c, blValue)
+            if c.method[k] == DoviMapping.mmr.rawValue {
+                let inv = pow(2.0, -Double(mmr.coefShift))
+                var s = Double(mmr.constant[k]) * inv
+                let terms = [y, u, v, y * u, y * v, u * v, y * u * v]
+                let order = min(Int(c.order[k]), 3)
+                for o in 0..<order {
+                    for t in 0..<7 {
+                        s += Double(mmr.coef[k][o * 7 + t]) * inv * pow(terms[t], Double(o + 1))
+                    }
+                }
+                return s
+            }
+            let lo = Int(c.pivots[0]), hi = Int(c.pivots[Int(c.numPivots) - 1])
+            let x = Double(min(max(blValue, lo), hi)) / blMax
+            let inv = pow(2.0, -Double(c.coefShift[k]))
+            var s = Double(c.coef[k][0]) * inv
+            if c.order[k] >= 1 { s += Double(c.coef[k][1]) * inv * x }
+            if c.order[k] >= 2 { s += Double(c.coef[k][2]) * inv * x * x }
+            return s
+        }
+
+        func denormalize(_ n: Double) -> Int { Int((n * blMax * scale).rounded(.toNearestOrEven)) }
+
+        /// Inverse NLQ in `Int64`, reconstructing at the middle of the quantisation step.
+        func inverseNlq(_ n: DoviNlqParams, _ el: Int) -> Int {
+            guard n.nlqMethod == .linear, n.nlqScale != 0 else { return 0 }
+            let r = Int64(el) - Int64(n.nlqOffset)
+            if r == 0 { return 0 }
+            let magFp = (2 * abs(r) - 1) * Int64(n.nlqScale)
+            let thr2 = 2 * Int64(n.nlqThreshold)
+            var mag = (magFp + thr2) >> Int64(n.nlqShift + 1)
+            if n.vdrInMax > 0 && mag > Int64(n.vdrInMax) { mag = Int64(n.vdrInMax) }
+            return Int(r < 0 ? -mag : mag)
+        }
+
+        func nlqActive(_ n: DoviNlqParams) -> Bool {
+            !p.flags.contains(.disableResidual) && n.nlqMethod == .linear && n.nlqScale != 0
+        }
+
+        /// Bilinear sample of an enhancement-layer plane at the centre of base-layer pixel (x, y) of a
+        /// plane `baseW` x `baseH`, as a 10-bit code (the word is UNORM x 65535 / 64).
+        func elCode(_ el: Plane, comp: Int, x: Int, y: Int, baseW: Int, baseH: Int) -> Int {
+            let u = (Double(x) + 0.5) / Double(baseW) * Double(el.width) - 0.5
+            let v = (Double(y) + 0.5) / Double(baseH) * Double(el.height) - 0.5
+            let x0 = Int(floor(u)), y0 = Int(floor(v))
+            let fx = u - Double(x0), fy = v - Double(y0)
+            func w(_ xx: Int, _ yy: Int) -> Double {
+                el.word(min(max(xx, 0), el.width - 1), min(max(yy, 0), el.height - 1), comp)
+            }
+            let top = w(x0, y0) * (1 - fx) + w(x0 + 1, y0) * fx
+            let bot = w(x0, y0 + 1) * (1 - fx) + w(x0 + 1, y0 + 1) * fx
+            let word = top * (1 - fy) + bot * fy
+            return Int((word / 64.0).rounded(.toNearestOrEven))
+        }
+
+        /// One component's pieces before any clamp: the normalised prediction, the VDR code it
+        /// denormalises to, the enhancement-layer code and the residual it decodes to.
+        struct Parts { var predNorm = 0.0; var pred = 0; var elCode = 0; var residual = 0; var active = false
+            var total: Int { pred + residual } }
+
+        func lumaParts(bl: Plane, blUV: Plane, el: Plane, x: Int, y: Int) -> Parts {
+            let by = bl.code(x, y)
+            let cx = min(x >> 1, blUV.width - 1), cy = min(y >> 1, blUV.height - 1)
+            let yn = Double(by) / blMax
+            let un = Double(blUV.code(cx, cy, 0)) / blMax
+            let vn = Double(blUV.code(cx, cy, 1)) / blMax
+            var r = Parts()
+            r.predNorm = predict(p.polyY, p.mmrY, blValue: by, y: yn, u: un, v: vn)
+            r.pred = denormalize(r.predNorm)
+            if nlqActive(p.nlqY) {
+                r.active = true
+                r.elCode = elCode(el, comp: 0, x: x, y: y, baseW: bl.width, baseH: bl.height)
+                r.residual = inverseNlq(p.nlqY, r.elCode)
+            }
+            return r
+        }
+
+        /// Luma at the chroma site: [1 2 1] around the even column in both rows of the cell, rounded per
+        /// row, then the two rows averaged; edges clamped (DoViBaker's reading, which Dolby's EL confirms).
+        static func chromaSiteLuma(_ bl: Plane, x: Int, y: Int) -> Int {
+            func at(_ c: Int, _ r: Int) -> Int { bl.code(min(max(c, 0), bl.width - 1), min(r, bl.height - 1)) }
+            let rows = [y * 2, y * 2 + 1].map { r in (at(x * 2 - 1, r) + 2 * at(x * 2, r) + at(x * 2 + 1, r) + 2) >> 2 }
+            return (rows[0] + rows[1] + 1) >> 1
+        }
+
+        func chromaParts(bl: Plane, blUV: Plane, elUV: Plane, x: Int, y: Int) -> (cb: Parts, cr: Parts) {
+            let by = Self.chromaSiteLuma(bl, x: x, y: y)
+            let cb = blUV.code(x, y, 0), cr = blUV.code(x, y, 1)
+            let yn = Double(by) / blMax, un = Double(cb) / blMax, vn = Double(cr) / blMax
+            var a = Parts(), b = Parts()
+            a.predNorm = predict(p.polyCb, p.mmrCb, blValue: cb, y: yn, u: un, v: vn)
+            b.predNorm = predict(p.polyCr, p.mmrCr, blValue: cr, y: yn, u: un, v: vn)
+            a.pred = denormalize(a.predNorm); b.pred = denormalize(b.predNorm)
+            if !p.flags.contains(.disableResidual) {
+                if nlqActive(p.nlqCb) {
+                    a.active = true
+                    a.elCode = elCode(elUV, comp: 0, x: x, y: y, baseW: blUV.width, baseH: blUV.height)
+                    a.residual = inverseNlq(p.nlqCb, a.elCode)
+                }
+                if nlqActive(p.nlqCr) {
+                    b.active = true
+                    b.elCode = elCode(elUV, comp: 1, x: x, y: y, baseW: blUV.width, baseH: blUV.height)
+                    b.residual = inverseNlq(p.nlqCr, b.elCode)
+                }
+            }
+            return (a, b)
+        }
+
+        func luma(bl: Plane, blUV: Plane, el: Plane, x: Int, y: Int) -> Int {
+            let by = bl.code(x, y)
+            let cx = min(x >> 1, blUV.width - 1), cy = min(y >> 1, blUV.height - 1)
+            let yn = Double(by) / blMax
+            let un = Double(blUV.code(cx, cy, 0)) / blMax
+            let vn = Double(blUV.code(cx, cy, 1)) / blMax
+            var v = denormalize(predict(p.polyY, p.mmrY, blValue: by, y: yn, u: un, v: vn))
+            if nlqActive(p.nlqY) {
+                v += inverseNlq(p.nlqY, elCode(el, comp: 0, x: x, y: y, baseW: bl.width, baseH: bl.height))
+            }
+            return min(max(v, 0), Int(p.vdrMax))
+        }
+
+        func chroma(bl: Plane, blUV: Plane, elUV: Plane, x: Int, y: Int) -> (Int, Int) {
+            let by = Self.chromaSiteLuma(bl, x: x, y: y)
+            let cb = blUV.code(x, y, 0), cr = blUV.code(x, y, 1)
+            let yn = Double(by) / blMax, un = Double(cb) / blMax, vn = Double(cr) / blMax
+            var vcb = denormalize(predict(p.polyCb, p.mmrCb, blValue: cb, y: yn, u: un, v: vn))
+            var vcr = denormalize(predict(p.polyCr, p.mmrCr, blValue: cr, y: yn, u: un, v: vn))
+            if !p.flags.contains(.disableResidual) {
+                if nlqActive(p.nlqCb) {
+                    vcb += inverseNlq(p.nlqCb, elCode(elUV, comp: 0, x: x, y: y, baseW: blUV.width, baseH: blUV.height))
+                }
+                if nlqActive(p.nlqCr) {
+                    vcr += inverseNlq(p.nlqCr, elCode(elUV, comp: 1, x: x, y: y, baseW: blUV.width, baseH: blUV.height))
+                }
+            }
+            let m = Int(p.vdrMax)
+            return (min(max(vcb, 0), m), min(max(vcr, 0), m))
+        }
+    }
+
+    // MARK: - Comparison
+
+    struct Stat {
+        var n = 0, exact = 0, over1 = 0, maxAbs = 0, sum = 0
+        mutating func add(_ d: Int) {
+            n += 1; let a = abs(d)
+            if a == 0 { exact += 1 }
+            if a > 1 { over1 += 1 }
+            maxAbs = max(maxAbs, a); sum += d
+        }
+        var exactPct: Double { n == 0 ? 0 : 100 * Double(exact) / Double(n) }
+        var over1Pct: Double { n == 0 ? 0 : 100 * Double(over1) / Double(n) }
+        var description: String {
+            String(format: "n=%d exact %.2f%% |d|>1 %.3f%% max %d mean %+.3f", n, exactPct, over1Pct, maxAbs,
+                   n == 0 ? 0 : Double(sum) / Double(n))
+        }
+    }
+
+    static func describe(_ c: DoviPolynomialParams, _ mmr: DoviMmrParams) -> String {
+        guard c.numPivots >= 2 else { return "identity" }
+        let pieces = Int(c.numPivots) - 1
+        let kinds = (0..<pieces).map { c.method[$0] == DoviMapping.mmr.rawValue ? "mmr\(c.order[$0])" : "poly\(c.order[$0])" }
+        return "\(pieces) pieces [\(kinds.joined(separator: ","))] shift \(c.coefShift[0])/\(mmr.coefShift)"
+    }
+
+    @Test("the independent CPU model reproduces the GPU's 12-bit VDR on real titles, MMR chroma and multi-piece curves included",
+          .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func modelMatchesGpu(name: String) throws {
+        let rec = try #require(DoviFelRealFileTests.RecordingComposer(limit: 6, stride: 40))
+        let s = try DoviFelRealFileTests.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        DoviFelRealFileTests.feed(s, count: 300)
+        s.decoder.flush()
+        let caps = rec.captures
+        try #require(!caps.isEmpty, "no frames reached the composer")
+
+        var yStat = Stat(), cbStat = Stat(), crStat = Stat()
+        for (i, cap) in caps.enumerated() {
+            var params = cap.params
+            params.ditherMode = .debugRawVDR
+            let out = try #require(rec.inner.compose(baseBuffer: cap.bl, enhancementBuffer: cap.el, params: params, frameIndex: 0))
+            let gy = Self.plane(out, 0, components: 1), guv = Self.plane(out, 1, components: 2)
+            let bl = Self.plane(cap.bl, 0, components: 1), blUV = Self.plane(cap.bl, 1, components: 2)
+            let el = Self.plane(cap.el, 0, components: 1), elUV = Self.plane(cap.el, 1, components: 2)
+            let model = Model(params)
+            if i == 0 {
+                print("[m8] \(name): Y \(Self.describe(params.polyY, params.mmrY)); Cb \(Self.describe(params.polyCb, params.mmrCb)); Cr \(Self.describe(params.polyCr, params.mmrCr)); flags \(params.flags.rawValue); nlqY scale \(params.nlqY.nlqScale) thr \(params.nlqY.nlqThreshold) max \(params.nlqY.vdrInMax) shift \(params.nlqY.nlqShift); nlqCb scale \(params.nlqCb.nlqScale)")
+            }
+            // The raw-VDR planes hold the 12-bit code shifted left 4 in a 16-bit word.
+            func gpu(_ p: Plane, _ x: Int, _ y: Int, _ c: Int) -> Int { Int(p.raw[(y * p.width + x) * p.components + c] >> 4) }
+            for y in stride(from: 3, to: bl.height, by: 7) {
+                for x in stride(from: 5, to: bl.width, by: 11) {
+                    yStat.add(model.luma(bl: bl, blUV: blUV, el: el, x: x, y: y) - gpu(gy, x, y, 0))
+                }
+            }
+            for y in stride(from: 1, to: blUV.height, by: 5) {
+                for x in stride(from: 2, to: blUV.width, by: 7) {
+                    let (cb, cr) = model.chroma(bl: bl, blUV: blUV, elUV: elUV, x: x, y: y)
+                    cbStat.add(cb - gpu(guv, x, y, 0))
+                    crStat.add(cr - gpu(guv, x, y, 1))
+                }
+            }
+        }
+        print("[m8] \(name): Y \(yStat.description)")
+        print("[m8] \(name): Cb \(cbStat.description)")
+        print("[m8] \(name): Cr \(crStat.description)")
+        // The enhancement-layer filter is the one place the two are not the same arithmetic (the
+        // hardware bilinear weights are fixed point), so a residual code can land one off; anything
+        // beyond that is a disagreement about the maths.
+        for (label, st) in [("Y", yStat), ("Cb", cbStat), ("Cr", crStat)] {
+            #expect(st.over1Pct < 0.5, "\(label): \(st.description)")
+            #expect(st.exactPct > 90, "\(label): \(st.description)")
+        }
+    }
+
+    // MARK: - Loss census (M1) and error attribution (M3, M4, M6)
+
+    /// Counts, per plane, every pixel at a point where information can be lost. Fractions of the
+    /// sampled pixels. The output range clamps are video range: 64...940 luma, 64...960 chroma.
+    struct Census {
+        var n = 0
+        var predBelow0 = 0, predAbove1 = 0
+        var nlqAtMax = 0, residualPixels = 0
+        var vdrBelow0 = 0, vdrAboveMax = 0
+        var outBelowLo = 0, outAboveHi = 0
+        var elAt0 = 0, elAt1023 = 0
+        var worstOvershoot = 0
+        mutating func add(_ q: Model.Parts, _ nlq: DoviNlqParams, vdrMax: Int, scale: Double, lo: Int, hi: Int) {
+            n += 1
+            if q.predNorm < 0 { predBelow0 += 1 }
+            if q.predNorm > 1 { predAbove1 += 1 }
+            if q.active {
+                residualPixels += 1
+                if abs(q.residual) >= Int(nlq.vdrInMax) && nlq.vdrInMax > 0 { nlqAtMax += 1 }
+                if q.elCode <= 0 { elAt0 += 1 }
+                if q.elCode >= 1023 { elAt1023 += 1 }
+            }
+            let t = q.total
+            if t < 0 { vdrBelow0 += 1 }
+            if t > vdrMax { vdrAboveMax += 1 }
+            let c = min(max(t, 0), vdrMax)
+            let out = Int(floor(Double(c) / scale + 0.5))
+            if out < lo { outBelowLo += 1; worstOvershoot = max(worstOvershoot, lo - out) }
+            if out > hi { outAboveHi += 1; worstOvershoot = max(worstOvershoot, out - hi) }
+        }
+        var line: String {
+            func f(_ v: Int) -> String { String(format: "%.4f%%", n == 0 ? 0 : 100 * Double(v) / Double(n)) }
+            return "n=\(n) pred<0 \(f(predBelow0)) pred>1 \(f(predAbove1)) | residual px \(f(residualPixels)) at vdr_in_max \(f(nlqAtMax)) EL=0 \(f(elAt0)) EL=1023 \(f(elAt1023)) | vdr<0 \(f(vdrBelow0)) vdr>max \(f(vdrAboveMax)) | out<lo \(f(outBelowLo)) out>hi \(f(outAboveHi)) worst overshoot \(worstOvershoot) codes"
+        }
+    }
+
+    @Test("M1: loss census on real titles, every clamp counted", .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func lossCensus(name: String) throws {
+        let rec = try #require(DoviFelRealFileTests.RecordingComposer(limit: 6, stride: 40))
+        let s = try DoviFelRealFileTests.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        DoviFelRealFileTests.feed(s, count: 300)
+        s.decoder.flush()
+        var y = Census(), cb = Census(), cr = Census()
+        for cap in rec.captures {
+            let p = cap.params
+            let m = Model(p)
+            let bl = Self.plane(cap.bl, 0, components: 1), blUV = Self.plane(cap.bl, 1, components: 2)
+            let el = Self.plane(cap.el, 0, components: 1), elUV = Self.plane(cap.el, 1, components: 2)
+            for yy in stride(from: 3, to: bl.height, by: 5) {
+                for xx in stride(from: 5, to: bl.width, by: 7) {
+                    y.add(m.lumaParts(bl: bl, blUV: blUV, el: el, x: xx, y: yy), p.nlqY, vdrMax: Int(p.vdrMax), scale: m.scale, lo: 64, hi: 940)
+                }
+            }
+            for yy in stride(from: 1, to: blUV.height, by: 3) {
+                for xx in stride(from: 2, to: blUV.width, by: 5) {
+                    let (a, b) = m.chromaParts(bl: bl, blUV: blUV, elUV: elUV, x: xx, y: yy)
+                    cb.add(a, p.nlqCb, vdrMax: Int(p.vdrMax), scale: m.scale, lo: 64, hi: 960)
+                    cr.add(b, p.nlqCr, vdrMax: Int(p.vdrMax), scale: m.scale, lo: 64, hi: 960)
+                }
+            }
+        }
+        print("[m1] \(name): Y  \(y.line)")
+        print("[m1] \(name): Cb \(cb.line)")
+        print("[m1] \(name): Cr \(cr.line)")
+    }
+
+    @Test("M3/M4/M6: where the GPU and the exact model still differ, split by cause", .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func errorAttribution(name: String) throws {
+        let rec = try #require(DoviFelRealFileTests.RecordingComposer(limit: 6, stride: 40))
+        let s = try DoviFelRealFileTests.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        DoviFelRealFileTests.feed(s, count: 300)
+        s.decoder.flush()
+        var lumaNoRes = Stat(), chromaNoRes = Stat(), lumaRes = Stat(), chromaRes = Stat()
+        for cap in rec.captures {
+            let bl = Self.plane(cap.bl, 0, components: 1), blUV = Self.plane(cap.bl, 1, components: 2)
+            let el = Self.plane(cap.el, 0, components: 1), elUV = Self.plane(cap.el, 1, components: 2)
+            for residual in [false, true] {
+                var params = cap.params
+                params.ditherMode = .debugRawVDR
+                if !residual { params.flags.insert(.disableResidual) }
+                let out = try #require(rec.inner.compose(baseBuffer: cap.bl, enhancementBuffer: cap.el, params: params, frameIndex: 0))
+                let gy = Self.plane(out, 0, components: 1), guv = Self.plane(out, 1, components: 2)
+                let m = Model(params)
+                func g(_ p: Plane, _ x: Int, _ y: Int, _ c: Int) -> Int { Int(p.raw[(y * p.width + x) * p.components + c] >> 4) }
+                for yy in stride(from: 3, to: bl.height, by: 5) {
+                    for xx in stride(from: 5, to: bl.width, by: 7) {
+                        let d = m.luma(bl: bl, blUV: blUV, el: el, x: xx, y: yy) - g(gy, xx, yy, 0)
+                        if residual { lumaRes.add(d) } else { lumaNoRes.add(d) }
+                    }
+                }
+                for yy in stride(from: 1, to: blUV.height, by: 3) {
+                    for xx in stride(from: 2, to: blUV.width, by: 5) {
+                        let (a, b) = m.chroma(bl: bl, blUV: blUV, elUV: elUV, x: xx, y: yy)
+                        let d1 = a - g(guv, xx, yy, 0), d2 = b - g(guv, xx, yy, 1)
+                        if residual { chromaRes.add(d1); chromaRes.add(d2) } else { chromaNoRes.add(d1); chromaNoRes.add(d2) }
+                    }
+                }
+            }
+        }
+        print("[m3] \(name): luma, no residual (table + float): \(lumaNoRes.description)")
+        print("[m4] \(name): chroma, no residual (MMR float):   \(chromaNoRes.description)")
+        print("[m6] \(name): luma, with residual (+ EL sampling): \(lumaRes.description)")
+        print("[m6] \(name): chroma, with residual:               \(chromaRes.description)")
+    }
+
+    /// M7: how much the chroma MMR output depends on how the luma is brought down to the chroma site.
+    /// Each variant replaces only the luma input of the cross terms; the production reading is the baseline.
+    @Test("M7: chroma MMR sensitivity to the luma downsampling at the chroma site", .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func lumaSiteSensitivity(name: String) throws {
+        let rec = try #require(DoviFelRealFileTests.RecordingComposer(limit: 6, stride: 40))
+        let s = try DoviFelRealFileTests.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        DoviFelRealFileTests.feed(s, count: 300)
+        s.decoder.flush()
+        let names = ["top row", "2x2 box", "vertical 2-tap", "bottom row"]
+        var sq = [Double](repeating: 0, count: names.count), mx = [Int](repeating: 0, count: names.count)
+        var n = 0
+        for cap in rec.captures {
+            let p = cap.params
+            let m = Model(p)
+            let bl = Self.plane(cap.bl, 0, components: 1), blUV = Self.plane(cap.bl, 1, components: 2)
+            func at(_ x: Int, _ y: Int) -> Int { bl.code(min(max(x, 0), bl.width - 1), min(max(y, 0), bl.height - 1)) }
+            for yy in stride(from: 1, to: blUV.height, by: 3) {
+                for xx in stride(from: 2, to: blUV.width, by: 5) {
+                    let cb = blUV.code(xx, yy, 0), cr = blUV.code(xx, yy, 1)
+                    let un = Double(cb) / m.blMax, vn = Double(cr) / m.blMax
+                    func pred(_ luma: Double) -> (Int, Int) {
+                        let yn = luma / m.blMax
+                        return (m.denormalize(m.predict(p.polyCb, p.mmrCb, blValue: cb, y: yn, u: un, v: vn)),
+                                m.denormalize(m.predict(p.polyCr, p.mmrCr, blValue: cr, y: yn, u: un, v: vn)))
+                    }
+                    let x0 = xx * 2, y0 = yy * 2
+                    let base = pred(Double(Model.chromaSiteLuma(bl, x: xx, y: yy)))
+                    let box = (at(x0, y0) + at(x0 + 1, y0) + at(x0, y0 + 1) + at(x0 + 1, y0 + 1))
+                    let variants = [pred(Double(at(x0, y0))), pred(Double(box) / 4),
+                                    pred(Double((at(x0, y0) + at(x0, y0 + 1) + 1) >> 1)), pred(Double(at(x0, y0 + 1)))]
+                    for (i, v) in variants.enumerated() {
+                        for d in [v.0 - base.0, v.1 - base.1] { sq[i] += Double(d * d); mx[i] = max(mx[i], abs(d)) }
+                    }
+                    n += 2
+                }
+            }
+        }
+        for i in 0..<names.count {
+            print(String(format: "[m7] %@: %@ vs [1 2 1] x 2-row: RMS %.3f codes (12-bit), max %d", name, names[i], (sq[i] / Double(n)).squareRoot(), mx[i]))
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
index 992f4bd41..b1f18cf58 100644
--- a/Tests/AetherEngineTests/DoviFelRealFileTests.swift
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -1,5 +1,10 @@
 import Testing
 import Foundation
+import CoreMedia
+import CoreVideo
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
 @testable import AetherEngine
 
 /// End-to-end FEL checks on real Profile 7 files, where the synthetic suites
@@ -43,4 +48,394 @@ struct DoviFelRealFileTests {
 
     /// The first two clips, when present: the ones long enough to seek into.
     static var firstTwoClips: [String] { [fixtures[0], fixtures[1]].filter(available) }
+
+    // MARK: - Harness
+
+    /// Forwards to the real composer while keeping the first few inputs, so a
+    /// test can re-run the same frame with different parameters.
+    final class RecordingComposer: FelComposing, @unchecked Sendable {
+        struct Capture { let bl: CVPixelBuffer; let el: CVPixelBuffer; let params: DoviMetalParams }
+        let inner: DoviFelComposer
+        private let lock = NSLock()
+        private var _captures: [Capture] = []
+        private let limit: Int
+        private let stride: Int
+        private var calls = 0
+
+        init?(limit: Int = 16, stride: Int = 15) {
+            self.stride = stride
+            guard let c = DoviFelComposer() else { return nil }
+            inner = c
+            self.limit = limit
+        }
+
+        var captures: [Capture] { lock.lock(); defer { lock.unlock() }; return _captures }
+
+        private func record(_ bl: CVPixelBuffer, _ el: CVPixelBuffer, _ p: DoviMetalParams) {
+            lock.lock()
+            if _captures.count < limit, calls % stride == 0 { _captures.append(Capture(bl: bl, el: el, params: p)) }
+            calls += 1
+            lock.unlock()
+        }
+
+        func composeAsync(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer, params: DoviMetalParams,
+                          frameIndex: UInt32, completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            record(baseBuffer, enhancementBuffer, params)
+            inner.composeAsync(baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer, params: params,
+                               frameIndex: frameIndex, completion: completion)
+        }
+        func composeAsyncWithAcquiredSlot(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer,
+                                          params: DoviMetalParams, frameIndex: UInt32,
+                                          completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            record(baseBuffer, enhancementBuffer, params)
+            inner.composeAsyncWithAcquiredSlot(baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer,
+                                               params: params, frameIndex: frameIndex, completion: completion)
+        }
+        func acquireSlot() { inner.acquireSlot() }
+        func releaseSlot() { inner.releaseSlot() }
+        func flush() { inner.flush() }
+        func flushTextureCache() { inner.flushTextureCache() }
+        func takePeakSlotsInUse() -> Int { inner.takePeakSlotsInUse() }
+        var allocatedPoolBuffers: Int { inner.allocatedPoolBuffers }
+        var meanGPUTimeMs: Double? { inner.meanGPUTimeMs }
+    }
+
+    final class Sink: @unchecked Sendable {
+        private let lock = NSLock()
+        private(set) var pts: [Double] = []
+        private(set) var withRPU = 0
+        private(set) var sizes = Set<String>()
+        private(set) var formats = Set<OSType>()
+
+        func take(_ buffer: CVPixelBuffer, _ time: CMTime) {
+            lock.lock(); defer { lock.unlock() }
+            pts.append(time.seconds)
+            sizes.insert("\(CVPixelBufferGetWidth(buffer))x\(CVPixelBufferGetHeight(buffer))")
+            formats.insert(CVPixelBufferGetPixelFormatType(buffer))
+            if CVBufferCopyAttachment(buffer, DoviDisplayMetadata.rpuDataKey as CFString, nil) != nil { withRPU += 1 }
+        }
+        func reset() { lock.lock(); pts = []; withRPU = 0; lock.unlock() }
+    }
+
+    struct Session {
+        let demuxer: Demuxer
+        let decoder: DualLayerVideoDecoder
+        let sink: Sink
+        let videoIndex: Int32
+    }
+
+    static func open(_ name: String, composer: (any FelComposing)? = DoviFelComposer()) throws -> Session {
+        let demuxer = Demuxer()
+        try demuxer.open(url: url(name))
+        let idx = demuxer.videoStreamIndex
+        let stream = try #require(demuxer.stream(at: idx))
+        let sink = Sink()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        try decoder.open(stream: stream) { buf, pts, _ in sink.take(buf, pts) }
+        return Session(demuxer: demuxer, decoder: decoder, sink: sink, videoIndex: Int32(idx))
+    }
+
+    /// Feeds up to `count` video packets; returns how many were fed.
+    @discardableResult
+    static func feed(_ s: Session, count: Int, epoch: UInt64? = nil) -> Int {
+        var fed = 0
+        while fed < count {
+            guard let pkt = try? s.demuxer.readPacket() else { break }
+            if pkt.pointee.stream_index == s.videoIndex {
+                fed += 1
+                s.decoder.decode(packet: pkt, epoch: epoch)
+            }
+            av_packet_unref(pkt)
+            var opt: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&opt)
+        }
+        return fed
+    }
+
+    static func lumaPlane(_ b: CVPixelBuffer) -> [UInt16] {
+        CVPixelBufferLockBaseAddress(b, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(b, .readOnly) }
+        let w = CVPixelBufferGetWidthOfPlane(b, 0), h = CVPixelBufferGetHeightOfPlane(b, 0)
+        let stride = CVPixelBufferGetBytesPerRowOfPlane(b, 0) / 2
+        let base = CVPixelBufferGetBaseAddressOfPlane(b, 0)!.assumingMemoryBound(to: UInt16.self)
+        var out = [UInt16](); out.reserveCapacity(w * h)
+        for y in 0..<h { for x in 0..<w { out.append(base[y * stride + x] >> 6) } }
+        return out
+    }
+
+    // MARK: - Tests
+
+    @Test("every real FEL file reconstructs nearly every packet, in presentation order, each with its RPU",
+          .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func reconstructsAndOrders(name: String) throws {
+        let s = try Self.open(name)
+        defer { s.decoder.close(); s.demuxer.close() }
+        let fed = Self.feed(s, count: 240)
+        s.decoder.flush()
+
+        #expect(s.decoder.streamClassification == .fel)
+        let got = s.sink.pts.count
+        #expect(fed == 240)
+        #expect(got >= Int(Double(fed) * 0.9), "\(got) frames from \(fed) packets")
+        #expect(s.sink.withRPU == got, "every output frame must carry display metadata")
+        // Frames that merely pass through as their base layer would satisfy every check above, so the
+        // composer must also have run on a clear majority of them (a few at the start wait for their
+        // enhancement layer's first picture, and a few at the end go out as the base layer).
+        let composed = s.decoder.composedFrameCount
+        print("[compose] \(name): composed \(composed) of \(got) delivered frames")
+        #expect(composed > 0, "no frame was composed: the whole file went out as its base layer")
+        #expect(composed * 10 >= got * 8, "only \(composed) of \(got) frames were composed")
+        #expect(s.sink.formats == [kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange])
+        #expect(s.sink.sizes.count == 1, "\(s.sink.sizes)")
+        // Delivery is in decode order by design; `SampleBufferRenderer` restores
+        // presentation order with a sorted buffer that releases once it holds more
+        // than `reorderDepth` (4) frames. Replay that exact rule: the file's reorder
+        // depth must fit, or the renderer would show frames out of order.
+        let pts = s.sink.pts
+        var buffer: [Double] = []
+        var released: [Double] = []
+        for t in pts {
+            buffer.insert(t, at: buffer.firstIndex(where: { $0 > t }) ?? buffer.endIndex)
+            while buffer.count > 4 { released.append(buffer.removeFirst()) }
+        }
+        released.append(contentsOf: buffer)
+        let bad = zip(released, released.dropFirst()).filter { $1 <= $0 }.count
+        let inversions = zip(pts, pts.dropFirst()).filter { $1 <= $0 }.count
+        print("[order] \(name): \(inversions) decode-order inversions of \(pts.count); after the renderer's 4-deep reorder: \(bad) regressions")
+        #expect(bad == 0, "reorder depth exceeds the renderer buffer: \(bad) regressions")
+        #expect(Set(pts).count == pts.count, "duplicate presentation timestamps delivered")
+    }
+
+    @Test("the enhancement layer is aligned with the base layer: the residual acts, and never exceeds vdr_in_max",
+          .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func residualIsAlignedAndNonTrivial(name: String) throws {
+        let rec = try #require(RecordingComposer())
+        let s = try Self.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        Self.feed(s, count: 300)
+        s.decoder.flush()
+
+        let caps = rec.captures
+        try #require(!caps.isEmpty, "no frames reached the composer")
+        // The frame whose enhancement layer carries the most signal.
+        func spread(_ c: RecordingComposer.Capture) -> Int {
+            let y = Self.lumaPlane(c.el); return Int(y.max() ?? 0) - Int(y.min() ?? 0)
+        }
+        let cap = caps.max(by: { spread($0) < spread($1) })!
+        let flatEverywhere = spread(cap) == 0
+        #expect(!cap.params.flags.contains(.disableResidual), "fixture is FEL, residual must be live")
+
+        var without = cap.params
+        without.flags.insert(.disableResidual)
+        without.ditherMode = .none
+        var with = cap.params
+        with.ditherMode = .none
+
+        let a = try #require(rec.inner.compose(baseBuffer: cap.bl, enhancementBuffer: cap.el, params: without, frameIndex: 0))
+        let b = try #require(rec.inner.compose(baseBuffer: cap.bl, enhancementBuffer: cap.el, params: with, frameIndex: 0))
+        let ya = Self.lumaPlane(a), yb = Self.lumaPlane(b)
+        #expect(ya.count == yb.count)
+
+        var differing = 0
+        var sumAbs = 0
+        var maxAbs = 0
+        for i in 0..<ya.count {
+            let d = abs(Int(ya[i]) - Int(yb[i]))
+            if d != 0 { differing += 1; sumAbs += d; maxAbs = max(maxAbs, d) }
+        }
+        func stat(_ v: [UInt16]) -> String {
+            let m = Double(v.reduce(0) { $0 + Int($1) }) / Double(v.count)
+            return "mean \(String(format: "%.1f", m)) min \(v.min() ?? 0) max \(v.max() ?? 0)"
+        }
+        let elY = Self.lumaPlane(cap.el)
+        print("[diag] \(name): BL \(CVPixelBufferGetWidth(cap.bl))x\(CVPixelBufferGetHeight(cap.bl)) EL \(CVPixelBufferGetWidth(cap.el))x\(CVPixelBufferGetHeight(cap.el)) flags=\(cap.params.flags.rawValue)")
+        print("[diag]   BL luma \(stat(Self.lumaPlane(cap.bl)))  EL luma \(stat(elY))  out(no res) \(stat(ya))  out(res) \(stat(yb))")
+        let n = cap.params.nlqY
+        print("[diag]   nlqY method=\(n.nlqMethod) offset=\(n.nlqOffset) scale=\(n.nlqScale) thr=\(n.nlqThreshold) vdrInMax=\(n.vdrInMax) shift=\(n.nlqShift) pivots=\(n.nlqPivots)")
+        print("[diag]   polyY pivots=\(cap.params.polyY.pivots.prefix(Int(cap.params.polyY.numPivots))) order=\(cap.params.polyY.order.prefix(3)) coef0=\(cap.params.polyY.coef[0]) shift0=\(cap.params.polyY.coefShift[0]) blMax=\(cap.params.blMax) vdrScale=\(cap.params.vdrScale)")
+        let fraction = Double(differing) / Double(ya.count)
+        let meanAbs = differing == 0 ? 0 : Double(sumAbs) / Double(differing)
+        // A misaligned or mis-scaled EL would either do nothing or look like noise
+        // of full amplitude; a genuine detail residual is sparse-to-moderate and small.
+        print("[residual] \(name): \(String(format: "%.1f", fraction * 100))% pixels differ, mean |d|=\(String(format: "%.2f", meanAbs)), max |d|=\(maxAbs)")
+        // The residual is bounded by construction: |r| <= vdr_in_max VDR codes, i.e. vdr_in_max / vdr_scale output codes.
+        let bound = Int(cap.params.nlqY.vdrInMax) / Int(cap.params.vdrScale) + 1
+        #expect(maxAbs <= bound, "residual \(maxAbs) exceeds vdr_in_max bound \(bound)")
+        if flatEverywhere {
+            print("[residual] \(name): EL flat in all \(caps.count) sampled frames; residual correctly does nothing")
+            #expect(differing == 0)
+        } else {
+            #expect(fraction > 0.001, "the residual had no effect on luma")
+        }
+    }
+
+    /// N5: what a base-layer fallback frame costs. When the output pool is empty the pipeline presents the
+    /// base layer as it is; this measures how far that frame is from the composed one on each real title,
+    /// in 10-bit codes per plane. The comment on the fallback used to claim ~2/4096 codes, which came from
+    /// the near-identity synthetic stream.
+    @Test("a base-layer fallback frame differs from the composed frame by a measured amount on real titles",
+          .enabled(if: !DoviFelRealFileTests.availableFixtures.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.availableFixtures)
+    func fallbackFrameDelta(name: String) throws {
+        let rec = try #require(RecordingComposer(limit: 6, stride: 40))
+        let s = try Self.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        Self.feed(s, count: 300)
+        s.decoder.flush()
+        let caps = rec.captures
+        try #require(!caps.isEmpty, "no frames reached the composer")
+
+        func planes(_ b: CVPixelBuffer) -> [[Int]] {
+            CVPixelBufferLockBaseAddress(b, .readOnly); defer { CVPixelBufferUnlockBaseAddress(b, .readOnly) }
+            let w = CVPixelBufferGetWidthOfPlane(b, 0), h = CVPixelBufferGetHeightOfPlane(b, 0)
+            let ys = CVPixelBufferGetBytesPerRowOfPlane(b, 0) / 2
+            let y = CVPixelBufferGetBaseAddressOfPlane(b, 0)!.assumingMemoryBound(to: UInt16.self)
+            let cw = CVPixelBufferGetWidthOfPlane(b, 1), ch = CVPixelBufferGetHeightOfPlane(b, 1)
+            let cs = CVPixelBufferGetBytesPerRowOfPlane(b, 1) / 2
+            let c = CVPixelBufferGetBaseAddressOfPlane(b, 1)!.assumingMemoryBound(to: UInt16.self)
+            var out = [(0..<(w * h)).map { Int(y[($0 / w) * ys + $0 % w] >> 6) }]
+            for k in 0..<2 { out.append((0..<(cw * ch)).map { Int(c[($0 / cw) * cs + ($0 % cw) * 2 + k] >> 6) }) }
+            return out
+        }
+        var worstMean = 0.0
+        for (i, cap) in caps.enumerated() {
+            var p = cap.params; p.ditherMode = .none
+            let composed = planes(try #require(rec.inner.compose(baseBuffer: cap.bl, enhancementBuffer: cap.el, params: p, frameIndex: 0)))
+            let base = planes(cap.bl)
+            for (k, plane) in ["Y", "Cb", "Cr"].enumerated() {
+                let d = zip(composed[k], base[k]).map { abs($0 - $1) }.sorted()
+                let mean = Double(d.reduce(0, +)) / Double(d.count)
+                worstMean = max(worstMean, mean)
+                print(String(format: "[fallback] %@ f%d %@: mean |d| %.2f codes (10-bit), p99 %d, max %d",
+                             name, i, plane, mean, d[Int(Double(d.count) * 0.99)], d.last ?? 0))
+            }
+        }
+        print(String(format: "[fallback] %@: worst per-plane mean |d| %.2f (10-bit codes)", name, worstMean))
+    }
+
+    @Test("a flush before the first enhancement packet leaves the enhancement decoder in step: its frames still arrive",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(2)), arguments: [DoviFelRealFileTests.fixtures[0]])
+    func flushBeforeFirstEnhancementPacket(name: String) async throws {
+        let rec = try #require(RecordingComposer())
+        let s = try Self.open(name, composer: rec)
+        defer { s.decoder.close(); s.demuxer.close() }
+        // The host seeks (flush) before the stream has been classified, so the enhancement decoder
+        // opens afterwards, at an epoch the decoder it belongs to has already moved past.
+        s.decoder.flush()
+        #expect(s.decoder.enhancementFeedEpochForTesting == nil)
+        // The host hands every packet the epoch it read, as it does in playback.
+        Self.feed(s, count: 60, epoch: s.decoder.feedEpoch)
+        #expect(s.decoder.enhancementFeedEpochForTesting == s.decoder.feedEpoch)
+        // A composition needs an enhancement frame, so the composer being called proves they arrive.
+        try await waitFor { !rec.captures.isEmpty }
+    }
+
+    @Test("a seek followed by a flush delivers only post-seek frames and recovers immediately",
+          .enabled(if: !DoviFelRealFileTests.firstTwoClips.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: DoviFelRealFileTests.firstTwoClips)
+    func seekFlushRecovers(name: String) throws {
+        let s = try Self.open(name)
+        defer { s.decoder.close(); s.demuxer.close() }
+        Self.feed(s, count: 60)
+        s.decoder.flush()
+        let before = s.sink.pts.count
+        #expect(before > 0)
+
+        #expect(s.demuxer.seek(to: 60.0))
+        s.sink.reset()
+        Self.feed(s, count: 90)
+        s.decoder.flush()
+
+        let after = s.sink.pts
+        #expect(after.count >= 60, "only \(after.count) frames after seek")
+        // Nothing from before the seek target's keyframe may leak through.
+        #expect((after.min() ?? 0) > 30, "pre-seek frame leaked: \(after.min() ?? -1)")
+        #expect(s.sink.withRPU == after.count)
+    }
+
+    @Test("repeated seeks back and forth never wedge the pipeline",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips))
+    func seekStorm() throws {
+        let name = Self.fixtures[0]
+        let s = try Self.open(name)
+        defer { s.decoder.close(); s.demuxer.close() }
+        for target in [10.0, 90.0, 5.0, 100.0, 0.0, 45.0] {
+            #expect(s.demuxer.seek(to: target))
+            s.sink.reset()
+            Self.feed(s, count: 40)
+            s.decoder.flush()
+            #expect(s.sink.pts.count >= 25, "target \(target): \(s.sink.pts.count) frames")
+        }
+    }
+
+    @Test("close without a flush, and immediate re-open, are safe and leave no session behind",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(3)))
+    func openCloseChurn() throws {
+        let name = Self.fixtures[2]
+        for round in 0..<6 {
+            let s = try Self.open(name)
+            Self.feed(s, count: round % 2 == 0 ? 5 : 40)
+            s.decoder.close()      // deliberately no flush first
+            s.demuxer.close()
+            // Packets fed after close must be refused, not resurrect the session.
+        }
+    }
+
+    @Test("feeding packets after close is ignored",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips))
+    func decodeAfterCloseIgnored() throws {
+        let name = Self.fixtures[2]
+        let s = try Self.open(name)
+        Self.feed(s, count: 20)
+        s.decoder.flush()
+        s.decoder.close()
+        s.sink.reset()
+        Self.feed(s, count: 20)
+        s.decoder.flush()
+        #expect(s.sink.pts.isEmpty, "frames delivered after close")
+        s.demuxer.close()
+    }
+
+    @Test("a full pass over a whole file keeps memory flat and never stalls",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[2]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(5)))
+    func longRunStable() throws {
+        let name = Self.fixtures[2]
+        let s = try Self.open(name)
+        defer { s.decoder.close(); s.demuxer.close() }
+
+        func rss() -> Int {
+            var info = mach_task_basic_info()
+            var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size / MemoryLayout<integer_t>.size)
+            _ = withUnsafeMutablePointer(to: &info) {
+                $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
+                    task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
+                }
+            }
+            return Int(info.resident_size) / (1024 * 1024)
+        }
+
+        var total = 0
+        var samples: [Int] = []
+        while true {
+            let fed = Self.feed(s, count: 200)
+            total += fed
+            samples.append(rss())
+            if fed < 200 { break }
+        }
+        s.decoder.flush()
+        print("[longRun] packets=\(total) frames=\(s.sink.pts.count) rss MiB by 200-packet step: \(samples)")
+        #expect(total > 300)
+        #expect(s.sink.pts.count >= Int(Double(total) * 0.95))
+        // Steady state: the last third may not sit more than 400 MiB above the first third.
+        if samples.count >= 6 {
+            let early = samples[1..<(samples.count / 3 + 1)].max() ?? 0
+            let late = samples[(samples.count * 2 / 3)...].max() ?? 0
+            #expect(late - early < 400, "resident memory grew \(early) -> \(late) MiB")
+        }
+    }
 }
diff --git a/Tests/AetherEngineTests/DoviRealFileExportTests.swift b/Tests/AetherEngineTests/DoviRealFileExportTests.swift
new file mode 100644
index 000000000..a08c97830
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviRealFileExportTests.swift
@@ -0,0 +1,96 @@
+import Testing
+import Foundation
+import CoreVideo
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+#if DEBUG
+/// Cross-check feed: writes four captured frames of each real FEL title (decoded BL and EL as
+/// yuv420p10le, an RPU.bin) next to our own raw 12-bit output with and without the residual, in a
+/// layout an independent implementation can read. These titles have no reference output, so comparing
+/// against another implementation is a second-implementation check of the MMR and 8-piece interpretation,
+/// not a ground truth.
+///
+/// `AETHER_REAL_EXPORT=<dir> swift test --filter exportRealTitle`
+struct DoviRealFileExportTests {
+
+    static func planar10(_ b: CVPixelBuffer) -> Data {
+        var d = Data()
+        func put(_ v: UInt16) { d.append(UInt8(v & 0xff)); d.append(UInt8(v >> 8)) }
+        let y = DoviCpuModelTests.plane(b, 0, components: 1)
+        for v in y.raw { put(v >> 6) }
+        let uv = DoviCpuModelTests.plane(b, 1, components: 2)
+        for c in 0..<2 { for i in stride(from: c, to: uv.raw.count, by: 2) { put(uv.raw[i] >> 6) } }
+        return d
+    }
+
+    @Test("export a real title for the DoViBaker cross-check",
+          .enabled(if: ProcessInfo.processInfo.environment["AETHER_REAL_EXPORT"] != nil),
+          .enabled(if: !DoviFelRealFileTests.firstTwoClips.isEmpty, DoviFelRealFileTests.needsClips),
+          arguments: [0, 1].filter { DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[$0]) })
+    func exportRealTitle(index: Int) throws {
+        let name = DoviFelRealFileTests.fixtures[index]
+        let dir = URL(fileURLWithPath: ProcessInfo.processInfo.environment["AETHER_REAL_EXPORT"]!)
+            .appendingPathComponent("title\(index)")
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+
+        let rec = try #require(DoviFelRealFileTests.RecordingComposer(limit: 4, stride: 40))
+        let sess = try DoviFelRealFileTests.open(name, composer: rec)
+        defer { sess.decoder.close(); sess.demuxer.close() }
+        DoviFelRealFileTests.feed(sess, count: 300)
+        sess.decoder.flush()
+        try #require(rec.captures.count == 4, "only \(rec.captures.count) frames reached the composer")
+        // Pair every captured frame with its own RPU: the survey's "one parameter set" holds per file section,
+        // not per frame. The key is the serialised block with the per-frame fields blanked.
+        func key(_ p: DoviMetalParams) -> Data {
+            var q = p; q.frameIndex = 0; q.ditherMode = .none; q.blWidth = 0; q.blHeight = 0; q.elWidth = 0; q.elHeight = 0; q.minPq = 0; q.maxPq = 0; q.avgPq = 0
+            return q.serialize()
+        }
+        var rpuByKey: [Data: [UInt8]] = [:]
+        let dm = Demuxer()
+        try dm.open(url: DoviFelRealFileTests.url(name))
+        defer { dm.close() }
+        let vi = Int32(dm.videoStreamIndex)
+        var seen = 0
+        while seen < 600, let pkt = try dm.readPacket() {
+            defer { av_packet_unref(pkt); var o: UnsafeMutablePointer<AVPacket>? = pkt; trackedPacketFree(&o) }
+            guard pkt.pointee.stream_index == vi else { continue }
+            seen += 1
+            let r = DoviRpuConverter.separateDualLayers(pkt, extractEL: false, useCustomBlockSource: true, extractParams: true)
+            if let raw = r.rpuData, let params = r.rpuParams { rpuByKey[key(params)] = raw }
+        }
+        var rpuBin = Data()
+        for cap in rec.captures {
+            let raw = try #require(rpuByKey[key(cap.params)], "no RPU in the first 600 packets matches a captured frame's parameters")
+            rpuBin.append(contentsOf: [0, 0, 0, 1])
+            rpuBin.append(contentsOf: raw.prefix(2) == [0x7c, 0x01] ? Array(raw.dropFirst(2)) : raw)
+        }
+        print("[export] \(name): \(rpuByKey.count) distinct parameter sets in \(seen) packets")
+
+        var bl = Data(), el = Data(), ours = Data(), base = Data()
+        for cap in rec.captures {
+            bl.append(Self.planar10(cap.bl)); el.append(Self.planar10(cap.el))
+            var raw = cap.params; raw.ditherMode = .debugRawVDR
+            var baseOnly = raw; baseOnly.flags.insert(.disableResidual)
+            for (p, out) in [(raw, 0), (baseOnly, 1)] {
+                let buf = try #require(rec.inner.compose(baseBuffer: cap.bl, enhancementBuffer: cap.el, params: p, frameIndex: 0))
+                for plane in DoviTestSupport.rawVDR(buf) { for v in plane {
+                    let bytes = [UInt8(v & 0xff), UInt8(v >> 8)]
+                    if out == 0 { ours.append(contentsOf: bytes) } else { base.append(contentsOf: bytes) }
+                } }
+            }
+        }
+        let first = try #require(rec.captures.first)
+        try bl.write(to: dir.appendingPathComponent("bl_dec.yuv"))
+        try el.write(to: dir.appendingPathComponent("el_dec.yuv"))
+        try rpuBin.write(to: dir.appendingPathComponent("out.rpu"))
+        try ours.write(to: dir.appendingPathComponent("ours12.yuv"))
+        try base.write(to: dir.appendingPathComponent("ours12_base.yuv"))
+        try "\(CVPixelBufferGetWidth(first.bl)) \(CVPixelBufferGetHeight(first.bl)) \(rec.captures.count)\n"
+            .write(to: dir.appendingPathComponent("geometry.txt"), atomically: true, encoding: .utf8)
+        print("[export] \(name): \(CVPixelBufferGetWidth(first.bl))x\(CVPixelBufferGetHeight(first.bl)) x\(rec.captures.count) -> \(dir.path)")
+    }
+}
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
new file mode 100644
index 000000000..2a494c1ed
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
@@ -0,0 +1,312 @@
+import Testing
+import CoreMedia
+import CoreVideo
+import Foundation
+@testable import AetherEngine
+
+/// The GPU slot wait must not hold the decoder lock.
+///
+/// With a composer whose in-flight limit is 1 and whose first completion is
+/// held by the test, a second composition started on another thread blocks in
+/// `acquireSlot()` with no lock held, so `flush()` returns promptly. On the
+/// pre-fix code the wait sat inside `composeAsync` while the VideoToolbox
+/// thread held the decoder lock, and `flush()` hung behind it.
+@Suite(.serialized, .timeLimit(.minutes(1)))
+struct DualLayerGpuSlotWaitTests {
+
+    /// Fake composer with an in-flight limit of 1. The first composition's
+    /// completion is held until the test releases it; the slot is held with
+    /// it, the way the real composer holds the slot until the command buffer
+    /// retires.
+    final class GatedFakeComposer: FelComposing, @unchecked Sendable {
+        private let slots = DispatchSemaphore(value: 1)
+        private let lock = NSLock()
+        private var held: (@Sendable (CVPixelBuffer?) -> Void)?
+        private var heldBase: CVPixelBuffer?
+        private(set) var acquireCalls = 0
+        private(set) var completedCount = 0
+        var acquireCallCount: Int { lock.lock(); defer { lock.unlock() }; return acquireCalls }
+
+        func acquireSlot() {
+            lock.lock(); acquireCalls += 1; lock.unlock()
+            slots.wait()
+        }
+
+        func releaseSlot() { slots.signal() }
+
+        func composeAsync(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            acquireSlot()
+            composeAsyncWithAcquiredSlot(
+                baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer,
+                params: params, frameIndex: frameIndex, completion: completion)
+        }
+
+        func composeAsyncWithAcquiredSlot(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            lock.lock()
+            let isFirst = held == nil && completedCount == 0
+            if isFirst {
+                held = completion
+                heldBase = baseBuffer
+            }
+            lock.unlock()
+            if !isFirst {
+                // Later frames finish synchronously through the base layer once
+                // the test has released the first slot. Ticket ordering in
+                // `deliver` is what the ordering test exercises, not the hop.
+                slots.signal()
+                lock.lock(); completedCount += 1; lock.unlock()
+                completion(baseBuffer)
+            }
+        }
+
+        /// Releases the held first composition: delivers its base layer as the
+        /// composed result and frees the slot.
+        func releaseFirst() {
+            let completion: (@Sendable (CVPixelBuffer?) -> Void)?
+            let base: CVPixelBuffer?
+            lock.lock()
+            completion = held; base = heldBase
+            held = nil; heldBase = nil
+            completedCount += 1
+            lock.unlock()
+            if let completion {
+                completion(base)
+            }
+            slots.signal()
+        }
+
+        func flush() {}
+    }
+
+    private static let frameTicks: Int64 = 3754
+    private static func pts(_ frame: Int64) -> CMTime {
+        CMTime(value: frame * frameTicks, timescale: 90000)
+    }
+
+    private static func makeBuffer(width: Int, height: Int) -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [kCVPixelBufferMetalCompatibilityKey: true,
+                                          kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary,
+                                         &out)
+        return status == kCVReturnSuccess ? out : nil
+    }
+
+    private final class Deliveries: @unchecked Sendable {
+        private let lock = NSLock()
+        private(set) var points: [CMTime] = []
+        private var metadata: [Data?] = []
+        func record(_ buffer: CVPixelBuffer, _ pts: CMTime, _ hdr10: Data?) {
+            let payload = CVBufferCopyAttachment(buffer, DoviDisplayMetadata.rpuDataKey as CFString, nil) as? Data
+            lock.lock(); points.append(pts); metadata.append(payload); lock.unlock()
+        }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return points.count }
+        var metadataPayloads: [Data?] { lock.lock(); defer { lock.unlock() }; return metadata }
+    }
+
+    /// Set once by a worker thread when it has finished; read by the test.
+    private final class Flag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value = false
+        func set() { lock.lock(); value = true; lock.unlock() }
+        var isSet: Bool { lock.lock(); defer { lock.unlock() }; return value }
+    }
+
+    /// Baton-pass box: the test thread stops touching the buffer once it is
+    /// handed to the background thread, mirroring the decoder's own handoff.
+    private struct SendablePixelBuffer: @unchecked Sendable {
+        let value: CVPixelBuffer
+    }
+
+    @Test("a second composition blocked on the GPU slot does not stall flush()")
+    func blockedSlotDoesNotStallFlush() async throws {
+        let bl0 = try #require(Self.makeBuffer(width: 64, height: 64))
+        let el0 = try #require(Self.makeBuffer(width: 32, height: 32))
+        let bl1 = try #require(Self.makeBuffer(width: 64, height: 64))
+        let el1 = try #require(Self.makeBuffer(width: 32, height: 32))
+
+        let composer = GatedFakeComposer()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: DoviMetalParams(), displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: DoviMetalParams(), displayMetadataNAL: nil)
+
+        // First pair composes and holds the only slot.
+        decoder.handleEnhancementLayerFrame(elBuffer: el0, pts: Self.pts(0))
+        decoder.handleBaseLayerFrame(baseBuffer: bl0, pts: Self.pts(0), hdr10Data: nil)
+
+        // Second pair on another thread: its enhancement layer queues without
+        // blocking, then its base layer matches and parks in acquireSlot().
+        let bl1Box = SendablePixelBuffer(value: bl1)
+        let el1Box = SendablePixelBuffer(value: el1)
+        // A dedicated thread, not the global queue: other suites run concurrently and
+        // can saturate GCD's pool, which starved this closure past the deadline.
+        let workerDone = Flag()
+        let worker = Thread {
+            decoder.handleEnhancementLayerFrame(elBuffer: el1Box.value, pts: Self.pts(1))
+            decoder.handleBaseLayerFrame(baseBuffer: bl1Box.value, pts: Self.pts(1), hdr10Data: nil)
+            workerDone.set()
+        }
+        worker.start()
+        // Wait until the background thread is inside the slot wait (on the
+        // pre-fix code it instead holds the decoder lock here, which is what
+        // made flush() hang). Then flush() must still return promptly.
+        try await waitFor { composer.acquireCallCount == 2 }
+
+        // flush() runs while the second composition is parked in `acquireSlot` and the first is held
+        // by the gate. Returning at all is the proof (it would wait on the decoder lock otherwise,
+        // and the suite's time limit would report the hang); no wall-clock bound is asserted.
+        decoder.flush()
+
+        // Release the held composition and let the second finish; the flush
+        // retired both tickets, so neither may be delivered after it.
+        composer.releaseFirst()
+        try await waitFor { workerDone.isSet }
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 0, "frames composed before flush() must not be delivered after it")
+        decoder.close()
+    }
+
+    @Test("a frame with no usable RPU borrows the previous frame's parameters, but only for a short run")
+    func missingRpuBorrowsPreviousParameters() async throws {
+        let composer = GatedFakeComposer()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        decoder.onFrame = { _, _, _ in }
+        decoder.primeForTesting(enhancementLayer: true)
+        let limit = DualLayerVideoDecoder.maxBorrowedParamsRun
+        // Packets in decode order: frame 0 has a real RPU, every later one has none.
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: DoviMetalParams(), displayMetadataNAL: nil)
+        for i in 1...(limit + 1) {
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: nil, displayMetadataNAL: nil)
+        }
+        let box = try (0...(limit + 1)).map { _ -> (SendablePixelBuffer, SendablePixelBuffer) in
+            let bl = try #require(Self.makeBuffer(width: 64, height: 64))
+            let el = try #require(Self.makeBuffer(width: 32, height: 32))
+            return (SendablePixelBuffer(value: bl), SendablePixelBuffer(value: el))
+        }
+        let workerDone = Flag()
+        let worker = Thread {
+            for (i, pair) in box.enumerated() {
+                decoder.handleEnhancementLayerFrame(elBuffer: pair.1.value, pts: Self.pts(Int64(i)))
+                decoder.handleBaseLayerFrame(baseBuffer: pair.0.value, pts: Self.pts(Int64(i)), hdr10Data: nil)
+            }
+            workerDone.set()
+        }
+        worker.start()
+        // Frame 0 holds the only slot. Frame 1 borrows and parks in acquireSlot (count 2). Frames after
+        // the borrow limit must bypass instead of reaching the composer.
+        try await waitFor { composer.acquireCallCount == 2 }
+        composer.releaseFirst()
+        try await waitFor { workerDone.isSet }
+        #expect(composer.acquireCallCount == 1 + limit)
+        decoder.close()
+    }
+
+    @Test("borrowed parameters carry display metadata only within the borrow limit, and flush clears it")
+    func missingRpuBorrowsPreviousDisplayMetadata() async throws {
+        let composer = GatedFakeComposer()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        defer { decoder.close() }
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        let nal: [UInt8] = [0x7C, 0x01, 0x19, 0x42, 0x03]
+        let payload = Data(nal.dropFirst(2))
+        let limit = DualLayerVideoDecoder.maxBorrowedParamsRun
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: DoviMetalParams(), displayMetadataNAL: nal)
+        for i in 1...(limit + 1) {
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: nil, displayMetadataNAL: nil)
+        }
+
+        for i in 0...(limit + 1) {
+            let bl = try #require(Self.makeBuffer(width: 64, height: 64))
+            let el = try #require(Self.makeBuffer(width: 32, height: 32))
+            let pts = Self.pts(Int64(i))
+            if i.isMultiple(of: 2) {
+                decoder.handleEnhancementLayerFrame(elBuffer: el, pts: pts)
+                decoder.handleBaseLayerFrame(baseBuffer: bl, pts: pts, hdr10Data: nil)
+            } else {
+                decoder.handleBaseLayerFrame(baseBuffer: bl, pts: pts, hdr10Data: nil)
+                decoder.handleEnhancementLayerFrame(elBuffer: el, pts: pts)
+            }
+            if i == 0 { composer.releaseFirst() }
+        }
+        try await waitFor { deliveries.count >= limit + 2 }
+        #expect(deliveries.metadataPayloads == Array(repeating: Optional(payload), count: limit + 1) + [nil])
+        #expect(composer.acquireCallCount == 1 + limit)
+
+        decoder.seedRPUForTesting(pts: Self.pts(10), params: DoviMetalParams(), displayMetadataNAL: nal)
+        let bl = try #require(Self.makeBuffer(width: 64, height: 64))
+        let el = try #require(Self.makeBuffer(width: 32, height: 32))
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(10), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(10))
+        try await waitFor { deliveries.count >= limit + 3 }
+        #expect(deliveries.count == limit + 3)
+        decoder.flush()
+        for i in 11...12 {
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: nil, displayMetadataNAL: nil)
+            let bl = try #require(Self.makeBuffer(width: 64, height: 64))
+            let el = try #require(Self.makeBuffer(width: 32, height: 32))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+        }
+        try await waitFor { deliveries.count >= limit + 5 }
+        #expect(deliveries.metadataPayloads == Array(repeating: Optional(payload), count: limit + 1) + [nil, payload, nil, nil])
+        #expect(composer.acquireCallCount == 2 + limit)
+    }
+
+    @Test("ordering still holds across two gated compositions")
+    func gatedCompositionsDeliverInOrder() async throws {
+        let bl0 = try #require(Self.makeBuffer(width: 64, height: 64))
+        let el0 = try #require(Self.makeBuffer(width: 32, height: 32))
+        let bl1 = try #require(Self.makeBuffer(width: 64, height: 64))
+        let el1 = try #require(Self.makeBuffer(width: 32, height: 32))
+
+        let composer = GatedFakeComposer()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        defer { decoder.close() }
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: DoviMetalParams(), displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: DoviMetalParams(), displayMetadataNAL: nil)
+
+        decoder.handleEnhancementLayerFrame(elBuffer: el0, pts: Self.pts(0))
+        decoder.handleBaseLayerFrame(baseBuffer: bl0, pts: Self.pts(0), hdr10Data: nil)
+        // Second composition blocks on the held slot on another thread.
+        let bl1Box = SendablePixelBuffer(value: bl1)
+        let el1Box = SendablePixelBuffer(value: el1)
+        // A dedicated thread, not the global queue: other suites run concurrently and
+        // can saturate GCD's pool, which starved this closure past the deadline.
+        let worker = Thread {
+            decoder.handleEnhancementLayerFrame(elBuffer: el1Box.value, pts: Self.pts(1))
+            decoder.handleBaseLayerFrame(baseBuffer: bl1Box.value, pts: Self.pts(1), hdr10Data: nil)
+        }
+        worker.start()
+        try await waitFor { composer.acquireCallCount == 2 }
+        composer.releaseFirst()
+
+        try await waitFor { deliveries.count >= 2 }
+        #expect(deliveries.count == 2)
+        let points = deliveries.points
+        if points.count == 2 {
+            #expect(CMTimeCompare(points[0], Self.pts(0)) == 0)
+            #expect(CMTimeCompare(points[1], Self.pts(1)) == 0)
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
new file mode 100644
index 000000000..79f5ae60d
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
@@ -0,0 +1,307 @@
+import Testing
+import CoreMedia
+import CoreVideo
+import Foundation
+import AetherLibavformat
+@_spi(Diagnostics) @testable import AetherEngine
+
+/// A seek on the Profile 7 FEL route has to flush and realign both layers on the same picture
+/// (the maintainer's parity requirement). The AV1/VP9 software path has one decoder to flush; here
+/// there are two VideoToolbox sessions, the composer, the ordered delivery, the two frame queues and
+/// the side-data ring, and a seek lands on timestamps the pre-seek frames may already have used (a
+/// backward seek replays the same PTS keys). These tests drive the frame handlers with tagged
+/// synthetic buffers and check what the composer was asked to pair and what reached `onFrame`.
+@Suite(.serialized, .timeLimit(.minutes(2)))
+struct DualLayerSeekRealignmentTests {
+
+    // MARK: - Fixtures
+
+    private static let frameTicks: Int64 = 3754
+    private static func pts(_ frame: Int64) -> CMTime { CMTime(value: frame * frameTicks, timescale: 90000) }
+
+    private static func buffer(width: Int, height: Int) -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary,
+                                         &out)
+        return status == kCVReturnSuccess ? out : nil
+    }
+
+    private static func params() -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.blWidth = 64; p.blHeight = 64; p.elWidth = 32; p.elHeight = 32
+        return p
+    }
+
+    private struct Pair { let base: CVPixelBuffer; let enhancement: CVPixelBuffer }
+
+    /// Records every pairing the decoder asks for and counts flushes. Completes at once with the
+    /// base buffer, unless `holdFirst` is set: then the first composition's completion is parked
+    /// until `releaseHeld()`, the way a command buffer still on the GPU holds it.
+    private final class FakeComposer: FelComposing, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _pairs: [Pair] = []
+        private var _flushes = 0
+        private var held: (@Sendable (CVPixelBuffer?) -> Void)?
+        private var heldBase: CVPixelBuffer?
+        private let holdFirst: Bool
+
+        init(holdFirst: Bool = false) { self.holdFirst = holdFirst }
+
+        var pairs: [Pair] { lock.lock(); defer { lock.unlock() }; return _pairs }
+        var flushCount: Int { lock.lock(); defer { lock.unlock() }; return _flushes }
+
+        func acquireSlot() {}
+        func releaseSlot() {}
+        func flush() { lock.lock(); _flushes += 1; lock.unlock() }
+        func composeAsync(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer, params: DoviMetalParams,
+                          frameIndex: UInt32, completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            composeAsyncWithAcquiredSlot(baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer,
+                                         params: params, frameIndex: frameIndex, completion: completion)
+        }
+        func composeAsyncWithAcquiredSlot(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer,
+                                          params: DoviMetalParams, frameIndex: UInt32,
+                                          completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            lock.lock()
+            let first = _pairs.isEmpty
+            _pairs.append(Pair(base: baseBuffer, enhancement: enhancementBuffer))
+            if holdFirst, first {
+                held = completion
+                heldBase = baseBuffer
+                lock.unlock()
+                return
+            }
+            lock.unlock()
+            completion(baseBuffer)
+        }
+
+        func releaseHeld() {
+            lock.lock()
+            let completion = held, base = heldBase
+            held = nil; heldBase = nil
+            lock.unlock()
+            completion?(base)
+        }
+    }
+
+    /// A VideoToolbox session stand-in that only counts what the decoder does to it.
+    private final class FakeSession: SingleLayerVideoDecoder, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _flushes = 0
+        var flushCount: Int { lock.lock(); defer { lock.unlock() }; return _flushes }
+        var onFrame: DecodedFrameHandler?
+        var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+        var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+        var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+        var skipUntilPTS: CMTime?
+        var feedEpoch: UInt64 = 0
+        func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {}
+        func open(parameterSets: [[UInt8]], timeBase: AVRational,
+                  onFrame: @escaping DecodedFrameHandler) throws {}
+        func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?) {}
+        func flush() { lock.lock(); _flushes += 1; lock.unlock() }
+        func close() {}
+    }
+
+    private final class Deliveries: @unchecked Sendable {
+        struct Frame { let buffer: CVPixelBuffer; let pts: CMTime; let afterMarker: Bool }
+        private let lock = NSLock()
+        private var frames: [Frame] = []
+        private var marker = false
+        func record(_ buffer: CVPixelBuffer, _ pts: CMTime) {
+            lock.lock(); frames.append(Frame(buffer: buffer, pts: pts, afterMarker: marker)); lock.unlock()
+        }
+        func setMarker() { lock.lock(); marker = true; lock.unlock() }
+        var afterMarker: [Frame] { lock.lock(); defer { lock.unlock() }; return frames.filter(\.afterMarker) }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return frames.count }
+    }
+
+    private struct Rig {
+        let decoder: DualLayerVideoDecoder
+        let composer: FakeComposer
+        let primary: FakeSession
+        let enhancement: FakeSession
+        let deliveries: Deliveries
+    }
+
+    private static func rig(holdFirst: Bool = false) -> Rig {
+        let composer = FakeComposer(holdFirst: holdFirst)
+        let primary = FakeSession(), enhancement = FakeSession()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer, primaryDecoder: primary,
+                                            enhancementDecoder: enhancement)
+        decoder.onFrame = { buffer, pts, _ in deliveries.record(buffer, pts) }
+        decoder.primeForTesting(enhancementLayer: true)
+        return Rig(decoder: decoder, composer: composer, primary: primary, enhancement: enhancement,
+                   deliveries: deliveries)
+    }
+
+    // MARK: - Tests
+
+    @Test("a seek flushes both VideoToolbox sessions and the composer, and empties the pairing state")
+    func flushReachesEveryStage() throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+
+        // Two complete pairs, a lone EL and a lone BL: every queue and the side-data ring hold something.
+        for i in 0..<4 {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+        }
+        for i in 0..<2 {
+            let bl = try #require(Self.buffer(width: 64, height: 64))
+            let el = try #require(Self.buffer(width: 32, height: 32))
+            r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        r.decoder.handleEnhancementLayerFrame(elBuffer: try #require(Self.buffer(width: 32, height: 32)), pts: Self.pts(2))
+        r.decoder.handleBaseLayerFrame(baseBuffer: try #require(Self.buffer(width: 64, height: 64)),
+                                       pts: Self.pts(3), hdr10Data: nil)
+        let before = r.decoder.stateSnapshotForTesting
+        #expect(before.rpuCacheCount > 0)
+        #expect(before.elQueueCount + before.blQueueCount > 0)
+
+        let epoch = r.decoder.feedEpoch
+        r.decoder.flush()
+
+        #expect(r.primary.flushCount == 1)
+        #expect(r.enhancement.flushCount == 1)
+        #expect(r.composer.flushCount == 1)
+        #expect(r.decoder.feedEpoch == epoch + 1)
+        let after = r.decoder.stateSnapshotForTesting
+        #expect(after.blQueueCount == 0 && after.elQueueCount == 0)
+        #expect(after.rpuCacheCount == 0 && after.dmRpuCacheCount == 0)
+        #expect(!after.draining)
+    }
+
+    @Test("an enhancement layer from before a seek is never composed onto a post-seek base layer")
+    func staleEnhancementLayerIsNotPaired() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+
+        // The pre-seek EL for frame 10 is decoded, its base layer never is: the seek retires it.
+        let staleEL = try #require(Self.buffer(width: 32, height: 32))
+        r.decoder.handleEnhancementLayerFrame(elBuffer: staleEL, pts: Self.pts(10))
+        r.decoder.flush()
+        r.deliveries.setMarker()
+
+        // A backward seek replays the same timestamps. The base layer comes first this time.
+        let postBL = try #require(Self.buffer(width: 64, height: 64))
+        let postEL = try #require(Self.buffer(width: 32, height: 32))
+        r.decoder.seedRPUForTesting(pts: Self.pts(10), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleBaseLayerFrame(baseBuffer: postBL, pts: Self.pts(10), hdr10Data: nil)
+        r.decoder.quiesceForTesting()
+        #expect(r.composer.pairs.isEmpty, "the post-seek base layer was composed with a pre-seek enhancement layer")
+
+        r.decoder.handleEnhancementLayerFrame(elBuffer: postEL, pts: Self.pts(10))
+        try await waitFor { r.deliveries.afterMarker.count == 1 }
+        let pairs = r.composer.pairs
+        #expect(pairs.count == 1)
+        #expect(pairs.first?.base === postBL)
+        #expect(pairs.first?.enhancement === postEL)
+        #expect(pairs.allSatisfy { $0.enhancement !== staleEL })
+    }
+
+    @Test("a base layer waiting for its enhancement layer when the seek lands is dropped, not delivered late")
+    func staleBaseLayerIsNotDelivered() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+
+        let staleBL = try #require(Self.buffer(width: 64, height: 64))
+        r.decoder.seedRPUForTesting(pts: Self.pts(5), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleBaseLayerFrame(baseBuffer: staleBL, pts: Self.pts(5), hdr10Data: nil)
+        r.decoder.flush()
+        r.deliveries.setMarker()
+
+        // The post-seek EL for the same key must not find the pre-seek base layer.
+        let postEL = try #require(Self.buffer(width: 32, height: 32))
+        r.decoder.handleEnhancementLayerFrame(elBuffer: postEL, pts: Self.pts(5))
+        r.decoder.quiesceForTesting()
+        #expect(r.composer.pairs.isEmpty)
+        #expect(r.deliveries.afterMarker.isEmpty)
+
+        let postBL = try #require(Self.buffer(width: 64, height: 64))
+        r.decoder.seedRPUForTesting(pts: Self.pts(5), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleBaseLayerFrame(baseBuffer: postBL, pts: Self.pts(5), hdr10Data: nil)
+        try await waitFor { r.deliveries.afterMarker.count == 1 }
+        #expect(r.deliveries.afterMarker.first?.buffer === postBL)
+        #expect(r.composer.pairs.first?.base === postBL)
+        #expect(r.composer.pairs.first?.enhancement === postEL)
+    }
+
+    @Test("after a seek every frame is composed with its own layer's picture, in either arrival order")
+    func postSeekFramesPairByPicture() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+
+        // Pre-seek leftovers on keys the replay is about to reuse.
+        for i in 10..<13 {
+            r.decoder.handleEnhancementLayerFrame(elBuffer: try #require(Self.buffer(width: 32, height: 32)), pts: Self.pts(Int64(i)))
+        }
+        r.decoder.handleBaseLayerFrame(baseBuffer: try #require(Self.buffer(width: 64, height: 64)), pts: Self.pts(13), hdr10Data: nil)
+        r.decoder.flush()
+        r.deliveries.setMarker()
+
+        var bases: [CVPixelBuffer] = [], enhancements: [CVPixelBuffer] = []
+        for i in 0..<6 {
+            let bl = try #require(Self.buffer(width: 64, height: 64))
+            let el = try #require(Self.buffer(width: 32, height: 32))
+            bases.append(bl); enhancements.append(el)
+            let key = Int64(10 + i)
+            r.decoder.seedRPUForTesting(pts: Self.pts(key), params: Self.params(), displayMetadataNAL: nil)
+            if i % 2 == 0 {
+                r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(key), hdr10Data: nil)
+                r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(key))
+            } else {
+                r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(key))
+                r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(key), hdr10Data: nil)
+            }
+        }
+        try await waitFor { r.deliveries.afterMarker.count == 6 }
+        let delivered = r.deliveries.afterMarker
+        #expect(zip(delivered, delivered.dropFirst()).allSatisfy { CMTimeCompare($0.pts, $1.pts) < 0 })
+        #expect(zip(delivered, bases).allSatisfy { $0.buffer === $1 })
+        let pairs = r.composer.pairs
+        #expect(pairs.count == 6)
+        for pair in pairs {
+            let i = bases.firstIndex { $0 === pair.base }
+            #expect(i != nil && pair.enhancement === enhancements[i!], "base and enhancement are not the same picture")
+        }
+    }
+
+    @Test("a seek during an in-flight composition drops that frame, and the first post-seek frame is the paired one")
+    func seekDuringInFlightCompose() async throws {
+        let r = Self.rig(holdFirst: true)
+        defer { r.decoder.close() }
+
+        let staleBL = try #require(Self.buffer(width: 64, height: 64))
+        let staleEL = try #require(Self.buffer(width: 32, height: 32))
+        r.decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleEnhancementLayerFrame(elBuffer: staleEL, pts: Self.pts(1))
+        r.decoder.handleBaseLayerFrame(baseBuffer: staleBL, pts: Self.pts(1), hdr10Data: nil)
+        #expect(r.composer.pairs.count == 1, "the first composition must be on the GPU")
+
+        // The seek lands while it is there.
+        r.decoder.flush()
+        r.deliveries.setMarker()
+
+        let postBL = try #require(Self.buffer(width: 64, height: 64))
+        let postEL = try #require(Self.buffer(width: 32, height: 32))
+        r.decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleEnhancementLayerFrame(elBuffer: postEL, pts: Self.pts(1))
+        r.decoder.handleBaseLayerFrame(baseBuffer: postBL, pts: Self.pts(1), hdr10Data: nil)
+        try await waitFor { r.deliveries.afterMarker.count == 1 }
+
+        // The pre-seek composition retires last, after the post-seek frame is already out.
+        r.composer.releaseHeld()
+        r.decoder.quiesceForTesting()
+
+        let late = r.deliveries.afterMarker
+        #expect(late.count == 1)
+        #expect(late.first?.buffer === postBL)
+        #expect(late.allSatisfy { $0.buffer !== staleBL })
+        let pairs = r.composer.pairs
+        #expect(pairs.count == 2)
+        #expect(pairs.last?.base === postBL && pairs.last?.enhancement === postEL)
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
new file mode 100644
index 000000000..5fcadd62c
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
@@ -0,0 +1,240 @@
+import Testing
+import CoreMedia
+import CoreVideo
+import Foundation
+import Metal
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Stream classification is decided once, from the first RPU's `el_type`, before
+/// the enhancement decoder opens. A per-frame `disable_residual_flag` is a kernel flag
+/// (`DoviComposerFlags.disableResidual`, honoured by the composer) and must never shut
+/// off the enhancement layer for the rest of the session.
+@Suite(.serialized, .timeLimit(.minutes(1)))
+struct DualLayerStreamClassificationTests {
+
+    // MARK: - Fixtures
+
+    private static let frameTicks: Int64 = 3754
+
+    private static func pts(_ frame: Int64) -> CMTime {
+        CMTime(value: frame * frameTicks, timescale: 90000)
+    }
+
+    private static var metalAvailable: Bool { MTLCreateSystemDefaultDevice() != nil }
+
+    private static func hexToBytes(_ hex: String) -> [UInt8] {
+        var bytes: [UInt8] = []
+        var i = hex.startIndex
+        while i < hex.endIndex {
+            let next = hex.index(i, offsetBy: 2)
+            if let byte = UInt8(hex[i..<next], radix: 16) { bytes.append(byte) }
+            i = next
+        }
+        return bytes
+    }
+
+    /// 2-byte HEVC NAL header + payload.
+    private func hevcNAL(type: UInt8, payload: [UInt8]) -> [UInt8] {
+        [UInt8(type << 1), 0x01] + payload
+    }
+
+    /// Pack complete NALs into an AVCC (4-byte BE length prefix) AVPacket.
+    private func avccPacket(_ nals: [[UInt8]]) -> UnsafeMutablePointer<AVPacket> {
+        var bytes: [UInt8] = []
+        for nal in nals {
+            let n = nal.count
+            bytes.append(UInt8((n >> 24) & 0xFF))
+            bytes.append(UInt8((n >> 16) & 0xFF))
+            bytes.append(UInt8((n >> 8) & 0xFF))
+            bytes.append(UInt8(n & 0xFF))
+            bytes.append(contentsOf: nal)
+        }
+        let pkt = av_packet_alloc()!
+        _ = av_new_packet(pkt, Int32(bytes.count))
+        bytes.withUnsafeBytes { src in
+            _ = memcpy(pkt.pointee.data, src.baseAddress, bytes.count)
+        }
+        return pkt
+    }
+
+    private func free(_ pkt: UnsafeMutablePointer<AVPacket>) {
+        var p: UnsafeMutablePointer<AVPacket>? = pkt
+        av_packet_free(&p)
+    }
+
+    private func packetResult(
+        isFEL: Bool,
+        isMEL: Bool = false,
+        params: DoviMetalParams? = nil
+    ) -> DoviRpuConverter.DualLayerPacketResult {
+        DoviRpuConverter.DualLayerPacketResult(
+            elPacket: nil, rpuData: nil, rpuParams: params,
+            isFEL: isFEL, isMEL: isMEL, success: true
+        )
+    }
+
+    private static func makeBuffer(width: Int, height: Int) -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [kCVPixelBufferMetalCompatibilityKey: true,
+                                          kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary,
+                                         &out)
+        guard status == kCVReturnSuccess, let buf = out else { return nil }
+        return buf
+    }
+
+    private static func baseLayer() -> CVPixelBuffer? { makeBuffer(width: 256, height: 256) }
+    private static func enhancementLayer() -> CVPixelBuffer? { makeBuffer(width: 128, height: 128) }
+
+    private static func params() -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.blWidth = 256; p.blHeight = 256; p.elWidth = 128; p.elHeight = 128
+        return p
+    }
+
+    private final class Deliveries: @unchecked Sendable {
+        private let lock = NSLock()
+        private var buffers: [(CVPixelBuffer, CMTime)] = []
+
+        func record(_ buffer: CVPixelBuffer, _ pts: CMTime, _ hdr10: Data?) {
+            lock.lock()
+            buffers.append((buffer, pts))
+            lock.unlock()
+        }
+
+        var snapshot: [(CVPixelBuffer, CMTime)] {
+            lock.lock(); defer { lock.unlock() }; return buffers
+        }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return buffers.count }
+    }
+
+    // MARK: - classifyStream unit tests
+
+    @Test("classifyStream maps a FEL packet result to FEL")
+    func classifyFEL() {
+        #expect(DoviRpuConverter.classifyStream(packetResult(isFEL: true)) == .fel)
+    }
+
+    @Test("classifyStream maps a MEL packet result to MEL")
+    func classifyMEL() {
+        #expect(DoviRpuConverter.classifyStream(packetResult(isFEL: false, isMEL: true)) == .mel)
+    }
+
+    @Test("classifyStream maps a packet with no RPU signal to undetermined")
+    func classifyUndetermined() {
+        #expect(DoviRpuConverter.classifyStream(packetResult(isFEL: false)) == .undetermined)
+    }
+
+    @Test("classifyStream ignores the per-frame disable_residual kernel flag")
+    func classifyIgnoresDisableResidualFlag() {
+        var p = Self.params()
+        p.flags.insert(.disableResidual)
+        // This is what `separateDualLayers` now produces for a FEL RPU with
+        // `disable_residual_flag` set: FEL reporting plus the kernel flag.
+        let result = packetResult(isFEL: true, params: p)
+        #expect(DoviRpuConverter.classifyStream(result) == .fel)
+    }
+
+    // MARK: - Converter integration over a real RPU
+
+    @Test("a real FEL RPU classifies FEL, not MEL")
+    func realFELRPUClassifiesFEL() {
+        // Raw unspec62 NAL (header included) from a FEL title; shared with DoviFelMathTests.
+        let rpu = Self.hexToBytes(DoviFelMathTests.clipARpuHex)
+        let pkt = avccPacket([hevcNAL(type: 1, payload: [0xAA, 0xBB]), rpu])
+        defer { free(pkt) }
+
+        let result = DoviRpuConverter.separateDualLayers(pkt)
+        #expect(result.isFEL)
+        #expect(!result.isMEL)
+        #expect(DoviRpuConverter.classifyStream(result) == .fel)
+        #expect(result.rpuParams != nil)
+    }
+
+    // MARK: - Decoder one-shot latch
+
+    @Test("a FEL stream stays FEL across a disable_residual RPU and later reports")
+    func felStaysFELAcrossDisableResidualFrame() {
+        let decoder = DualLayerVideoDecoder()
+        defer { decoder.close() }
+        #expect(decoder.streamClassificationForTesting == .undetermined)
+
+        var residualParams = Self.params()
+        residualParams.flags.insert(.disableResidual)
+
+        decoder.classifyPacketResultForTesting(packetResult(isFEL: true))
+        #expect(decoder.streamClassificationForTesting == .fel)
+        #expect(decoder.engagesEnhancementLayerForTesting())
+
+        // One RPU with the residual switched off: kernel flag only, the EL keeps decoding.
+        decoder.classifyPacketResultForTesting(packetResult(isFEL: true, params: residualParams))
+        #expect(decoder.streamClassificationForTesting == .fel)
+        #expect(decoder.engagesEnhancementLayerForTesting())
+
+        // A later MEL report cannot flip the one-shot latch either.
+        decoder.classifyPacketResultForTesting(packetResult(isFEL: false, isMEL: true))
+        #expect(decoder.streamClassificationForTesting == .fel)
+        #expect(decoder.engagesEnhancementLayerForTesting())
+    }
+
+    @Test("the first RPU decides: MEL never engages the enhancement layer")
+    func melNeverEngagesEnhancementLayer() {
+        let decoder = DualLayerVideoDecoder()
+        defer { decoder.close() }
+
+        decoder.classifyPacketResultForTesting(packetResult(isFEL: false, isMEL: true))
+        #expect(decoder.streamClassificationForTesting == .mel)
+        #expect(!decoder.engagesEnhancementLayerForTesting())
+
+        // A later FEL report cannot reopen what MEL never opened.
+        decoder.classifyPacketResultForTesting(packetResult(isFEL: true))
+        #expect(decoder.streamClassificationForTesting == .mel)
+        #expect(!decoder.engagesEnhancementLayerForTesting())
+    }
+
+    @Test("a MEL-primed decoder delivers the base layer directly")
+    func melBypassesToBaseLayer() async throws {
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeStreamForTesting(.mel)
+        defer { decoder.close() }
+
+        let bl = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(0), hdr10Data: nil)
+
+        // A bypass is a `fulfil` onto `OrderedDelivery`'s queue
+        // (`queue.async`), not a synchronous call to `onFrame` on the calling
+        // thread, so `handleBaseLayerFrame` returning is no longer proof the
+        // frame has been delivered.
+        try await waitFor { deliveries.count == 1 }
+        let got = deliveries.snapshot
+        #expect(got.count == 1)
+        #expect(got.first?.0 === bl)
+    }
+
+    @Test("a frame whose RPU disables the residual still composes with its enhancement layer")
+    func disableResidualFrameStillComposes() async throws {
+        guard Self.metalAvailable else { return }
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeStreamForTesting(.fel)
+        defer { decoder.close() }
+
+        var p = Self.params()
+        p.flags.insert(.disableResidual)
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: p, displayMetadataNAL: nil)
+
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+
+        try await waitFor { deliveries.count == 1 }
+        let got = try #require(deliveries.snapshot.first)
+        #expect(got.0 !== bl, "a disable_residual RPU must not bypass composition")
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
new file mode 100644
index 000000000..8cb32b33e
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -0,0 +1,2535 @@
+import Testing
+import CoreMedia
+import CoreVideo
+import Foundation
+import Metal
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+import Dovi
+@_spi(Diagnostics) @testable import AetherEngine
+
+/// `DualLayerVideoDecoder` pairs a 4K base-layer frame with its 1080p enhancement-layer frame and
+/// the RPU cached for that PTS, composes them on the GPU, and delivers the result in decode order.
+/// Both layers arrive on VideoToolbox callback threads, in either order, and compositions retire
+/// asynchronously. These tests drive the two frame handlers directly with synthetic P010 buffers,
+/// using `primeForTesting` / `seedRPUForTesting` to stand in for what `decode(packet:)` sets up, so
+/// the pairing, ordering, metadata and flush behaviour is covered without a real stream.
+@Suite(.serialized, .timeLimit(.minutes(2)))
+struct DualLayerVideoDecoderTests {
+
+    // MARK: - Fixtures
+
+    /// 23.976 fps at 90 kHz, rounded; only monotonic, well-separated keys matter here.
+    private static let frameTicks: Int64 = 3754
+
+    private static func pts(_ frame: Int64, offsetTicks: Int64 = 0) -> CMTime {
+        CMTime(value: frame * frameTicks + offsetTicks, timescale: 90000)
+    }
+
+    private static var metalAvailable: Bool { MTLCreateSystemDefaultDevice() != nil }
+
+    private static func makeBuffer(width: Int, height: Int, fill: UInt16) -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [kCVPixelBufferMetalCompatibilityKey: true,
+                                          kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary,
+                                         &out)
+        guard status == kCVReturnSuccess, let buf = out else { return nil }
+        CVPixelBufferLockBaseAddress(buf, [])
+        defer { CVPixelBufferUnlockBaseAddress(buf, []) }
+        for plane in 0..<CVPixelBufferGetPlaneCount(buf) {
+            guard let base = CVPixelBufferGetBaseAddressOfPlane(buf, plane) else { continue }
+            let rows = CVPixelBufferGetHeightOfPlane(buf, plane)
+            let stride = CVPixelBufferGetBytesPerRowOfPlane(buf, plane)
+            for r in 0..<rows {
+                let row = base.advanced(by: r * stride).assumingMemoryBound(to: UInt16.self)
+                for c in 0..<(stride / 2) { row[c] = fill }
+            }
+        }
+        return buf
+    }
+
+    private static func baseLayer() -> CVPixelBuffer? { makeBuffer(width: 256, height: 256, fill: 0x8000) }
+    private static func enhancementLayer() -> CVPixelBuffer? { makeBuffer(width: 128, height: 128, fill: 0x8000) }
+
+    /// Identity reshaping at the test plane sizes; the plumbing is under test, not the curve.
+    private static func params() -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.blWidth = 256; p.blHeight = 256; p.elWidth = 128; p.elHeight = 128
+        return p
+    }
+
+    /// A Profile 8.1 `unspec62` NAL shaped like `dovi_write_unspec62_nalu` output: header
+    /// `0x7C 0x01`, then a payload starting with the RPU prefix `0x19`, tagged so frames differ.
+    private static func rpuNAL(tag: UInt8) -> [UInt8] { [0x7C, 0x01, 0x19, 0x08, tag, 0xA5, 0x80] }
+
+    /// Records what reached `onFrame`, reading the Dolby Vision attachments at delivery time,
+    /// which is when the display layer would read them.
+    private final class Deliveries: @unchecked Sendable {
+        struct Frame {
+            let buffer: CVPixelBuffer
+            let pts: CMTime
+            let hdr10: Data?
+            let rpuPayload: Data?
+            let compatibilityID: CFTypeRef?
+            let afterMarker: Bool
+        }
+
+        private let lock = NSLock()
+        private var frames: [Frame] = []
+        private var marker = false
+
+        func record(_ buffer: CVPixelBuffer, _ pts: CMTime, _ hdr10: Data?) {
+            let payload = CVBufferCopyAttachment(buffer, DoviDisplayMetadata.rpuDataKey as CFString, nil) as? Data
+            let compat = CVBufferCopyAttachment(buffer, DoviDisplayMetadata.compatibilityIDKey as CFString, nil)
+            lock.lock()
+            frames.append(Frame(buffer: buffer, pts: pts, hdr10: hdr10, rpuPayload: payload,
+                                compatibilityID: compat, afterMarker: marker))
+            lock.unlock()
+        }
+
+        /// Marks the point a test's flush/close returned; frames delivered later carry the mark.
+        func setMarker() { lock.lock(); marker = true; lock.unlock() }
+
+        var snapshot: [Frame] { lock.lock(); defer { lock.unlock() }; return frames }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return frames.count }
+    }
+
+    private static func decoder(recordingInto deliveries: Deliveries, enhancementLayer: Bool) -> DualLayerVideoDecoder {
+        let decoder = DualLayerVideoDecoder()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: enhancementLayer)
+        return decoder
+    }
+
+    private static func isStrictlyIncreasing(_ frames: [Deliveries.Frame]) -> Bool {
+        zip(frames, frames.dropFirst()).allSatisfy { CMTimeCompare($0.pts, $1.pts) < 0 }
+    }
+
+    // MARK: - Single layer
+
+    @Test("without an enhancement layer every base-layer frame is delivered untouched, in order")
+    func singleLayerBypassesInOrder() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: false)
+        defer { decoder.close() }
+        var sent: [CVPixelBuffer] = []
+        for i in 0..<5 {
+            let bl = try #require(Self.baseLayer())
+            sent.append(bl)
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+
+        // A bypass is now a `fulfil` onto `OrderedDelivery`'s queue
+        // (`queue.async`) rather than a synchronous call to `onFrame` on
+        // whichever thread paired the frame, so `handleBaseLayerFrame`
+        // returning is no longer a guarantee the frame has been delivered.
+        try await waitFor { deliveries.count == 5 }
+        let got = deliveries.snapshot
+        #expect(got.count == 5)
+        #expect(zip(got, sent).allSatisfy { $0.buffer === $1 })
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+
+    // MARK: - Pairing
+
+    @Test("base layer first, then enhancement layer: the pair is composed and delivered at the base layer's PTS", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func pairsWhenBaseLayerArrivesFirst() async throws {
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: nil)
+        // Not `deliveries.count == 0`: delivery is one more `queue.async` hop
+        // away, so that would hold whether or not the frame is still waiting.
+        // `blQueueCount` is synchronous and deterministic:
+        // `handleBaseLayerFrame` decides queued-vs-ticketed entirely under
+        // `lock`, so by the time it returns, the frame is provably still
+        // sitting in `blFrameQueue` (not bypassed, not composed) if and only
+        // if it is still waiting for its enhancement layer.
+        #expect(decoder.stateSnapshotForTesting.blQueueCount == 1, "a base-layer frame with a pending enhancement layer must wait for it")
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+
+        try await waitFor { deliveries.count == 1 }
+        let got = try #require(deliveries.snapshot.first)
+        #expect(got.buffer !== bl, "expected the composer's output, got the bypassed base layer")
+        #expect(CVPixelBufferGetWidth(got.buffer) == 256 && CVPixelBufferGetHeight(got.buffer) == 256)
+        #expect(CMTimeCompare(got.pts, Self.pts(1)) == 0)
+    }
+
+    @Test("enhancement layer first, then base layer: the pair is composed and delivered at the base layer's PTS", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func pairsWhenEnhancementLayerArrivesFirst() async throws {
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: nil)
+
+        try await waitFor { deliveries.count == 1 }
+        let got = try #require(deliveries.snapshot.first)
+        #expect(got.buffer !== bl)
+        #expect(CMTimeCompare(got.pts, Self.pts(1)) == 0)
+    }
+
+    @Test("six enhancement-layer frames arriving ahead of the base layer all compose", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func pairsWhenEnhancementLayerRunsSixFramesAhead() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        for i in 0..<6 {
+            let el = try #require(Self.enhancementLayer())
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+        }
+
+        var sent: [CVPixelBuffer] = []
+        for i in 0..<6 {
+            let bl = try #require(Self.baseLayer())
+            sent.append(bl)
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+
+        try await waitFor { deliveries.count == 6 }
+        let got = deliveries.snapshot
+        #expect(got.count == 6)
+        #expect(zip(got, sent).allSatisfy { $0.buffer !== $1 }, "every frame must use the composed path, not bypass for a missing EL")
+        #expect(got.enumerated().allSatisfy { CMTimeCompare($0.element.pts, Self.pts(Int64($0.offset))) == 0 })
+    }
+
+    @Test("layers up to 300 ticks apart still pair; further apart they do not", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func jitterTolerance() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        let bl1 = try #require(Self.baseLayer())
+        let el1 = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el1, pts: Self.pts(1, offsetTicks: 300))
+        decoder.handleBaseLayerFrame(baseBuffer: bl1, pts: Self.pts(1), hdr10Data: nil)
+        try await waitFor { deliveries.count == 1 }
+        #expect(deliveries.count == 1)
+        #expect(deliveries.snapshot.first?.buffer !== bl1)
+
+        let bl2 = try #require(Self.baseLayer())
+        let el2 = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(2), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el2, pts: Self.pts(2, offsetTicks: 301))
+        decoder.handleBaseLayerFrame(baseBuffer: bl2, pts: Self.pts(2), hdr10Data: nil)
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 1, "301 ticks apart must not pair")
+    }
+
+    @Test("a pair with no cached RPU is not composed with invented coefficients: the base layer goes out", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func missingRPUBypassesToBaseLayer() async throws {
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: nil)
+
+        try await waitFor { deliveries.count == 1 }
+        #expect(deliveries.snapshot.first?.buffer === bl)
+    }
+
+    // MARK: - Ordering
+
+    @Test("a composition still on the GPU is not overtaken by a later frame that bypasses synchronously", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func asyncCompositionKeepsItsPlace() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        for round in 0..<8 {
+            let composed = Int64(round * 2), bypassed = Int64(round * 2 + 1)
+            let bl0 = try #require(Self.baseLayer())
+            let el0 = try #require(Self.enhancementLayer())
+            let bl1 = try #require(Self.baseLayer())
+            let el1 = try #require(Self.enhancementLayer())
+            decoder.seedRPUForTesting(pts: Self.pts(composed), params: Self.params(), displayMetadataNAL: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el0, pts: Self.pts(composed))
+            decoder.handleBaseLayerFrame(baseBuffer: bl0, pts: Self.pts(composed), hdr10Data: nil)
+            // No RPU for this one: it bypasses on the calling thread, ahead of the GPU.
+            decoder.handleEnhancementLayerFrame(elBuffer: el1, pts: Self.pts(bypassed))
+            decoder.handleBaseLayerFrame(baseBuffer: bl1, pts: Self.pts(bypassed), hdr10Data: nil)
+        }
+
+        try await waitFor { deliveries.count == 16 }
+        let got = deliveries.snapshot
+        #expect(got.count == 16)
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+
+    @Test("a base layer whose enhancement layer never arrives is still delivered, in order", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func orphanedBaseLayerIsEventuallyDelivered() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        let frames = 40
+        for i in 0..<frames {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+
+        // Every bypass goes through the async delivery hop. Wait for the bound
+        // this test actually asserts (`frames - 16`), then drain the queue
+        // for any stragglers still landing, before taking the final snapshot.
+        try await waitFor { deliveries.count >= frames - 16 }
+        decoder.quiesceForTesting()
+        let got = deliveries.snapshot
+        // Whatever the queue bound is, a lost enhancement layer must not swallow the picture:
+        // all but a bounded tail of frames go out, as base layer, oldest first.
+        #expect(got.count >= frames - 16)
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+
+    @Test("enhancement-layer frames with no base layer are bounded: the oldest can no longer pair", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func orphanedEnhancementLayersAreBounded() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        for i in 0..<40 {
+            let el = try #require(Self.enhancementLayer())
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+        }
+        let oldest = try #require(Self.baseLayer())
+        let newest = try #require(Self.baseLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: Self.params(), displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(39), params: Self.params(), displayMetadataNAL: nil)
+
+        decoder.handleBaseLayerFrame(baseBuffer: oldest, pts: Self.pts(0), hdr10Data: nil)
+        decoder.handleBaseLayerFrame(baseBuffer: newest, pts: Self.pts(39), hdr10Data: nil)
+        // Frame 0's enhancement layer is gone, so it waits for `maxLayerSkewFrames` further base-layer
+        // arrivals and then goes out alone; frame 39 is delivered behind it, in order. Without
+        // these arrivals nothing is delivered at all, which an earlier version of this test read as a
+        // pass: its bounded wait ran out and `first?.buffer !== newest` held for `nil`.
+        for i in 0..<DualLayerVideoDecoder.maxLayerSkewFrames {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(40 + i)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count >= 2 }
+        let got = deliveries.snapshot
+        #expect(CMTimeCompare(got[0].pts, Self.pts(0)) == 0)
+        #expect(got[0].buffer === oldest, "the enhancement layer for frame 0 should have been evicted: it goes out as its base layer")
+        #expect(CMTimeCompare(got[1].pts, Self.pts(39)) == 0)
+        #expect(got[1].buffer !== newest, "the newest enhancement layer should still pair")
+    }
+
+    // MARK: - Dolby Vision display metadata
+
+    @Test("every delivered frame carries its own RPU payload; a frame without one borrows the previous frame's", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func displayMetadataTravelsWithItsFrame() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        for i in 0..<4 {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            let nal = Self.rpuNAL(tag: UInt8(i))
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nal)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        // Frame 4 has no RPU at all: it borrows frame 3's parameters and payload (E1), and the stale
+        // attachment its recycled buffer arrived with must be replaced, not kept.
+        decoder.seedRPUForTesting(pts: Self.pts(4), params: nil, displayMetadataNAL: nil)
+        let recycled = try #require(Self.baseLayer())
+        DoviDisplayMetadata.attach(rpuNAL: Self.rpuNAL(tag: 0xEE), to: recycled)
+        decoder.handleBaseLayerFrame(baseBuffer: recycled, pts: Self.pts(4), hdr10Data: nil)
+        let el4 = try #require(Self.enhancementLayer())
+        decoder.handleEnhancementLayerFrame(elBuffer: el4, pts: Self.pts(4))
+
+        try await waitFor { deliveries.count == 5 }
+        let got = deliveries.snapshot
+        #expect(got.count == 5)
+        for i in 0..<4 where i < got.count {
+            #expect(got[i].rpuPayload == Data(Self.rpuNAL(tag: UInt8(i)).dropFirst(2)), "frame \(i) carries the wrong RPU")
+            #expect((got[i].compatibilityID as? String) == "1", "DolbyCompatibilityID must be the CFString \"1\"")
+        }
+        if got.count == 5 {
+            #expect(got[4].rpuPayload == Data(Self.rpuNAL(tag: 3).dropFirst(2)), "a borrowed frame carries the previous payload")
+            #expect((got[4].compatibilityID as? String) == "1")
+        }
+    }
+
+    @Test("a run of use_prev_vdr_rpu_flag frames keeps composing with the previous mapping, past the corrupt-RPU borrow limit", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func usePreviousRunIsNotCapped() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        let frames = DualLayerVideoDecoder.maxBorrowedParamsRun + 6
+        var inputs: [CVPixelBuffer] = []
+        for i in 0..<frames {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            inputs.append(bl)
+            if i == 0 {
+                decoder.seedRPUForTesting(pts: Self.pts(0), params: Self.params(), displayMetadataNAL: Self.rpuNAL(tag: 0))
+            } else {
+                decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: nil, displayMetadataNAL: nil, usesPrevious: true)
+            }
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == frames }
+        let got = deliveries.snapshot
+        #expect(got.count == frames)
+        // A bypassed frame is delivered as the base buffer itself; a composed one is a new pool buffer.
+        for (i, f) in got.enumerated() where i < inputs.count {
+            #expect(f.buffer !== inputs[i], "frame \(i) fell back to the base layer")
+        }
+    }
+
+    /// Hands compositions straight back, remembering which parameters each base buffer was composed with.
+    private final class ParamsRecordingComposer: FelComposing, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _blMaxByBase: [ObjectIdentifier: UInt32] = [:]
+        private var _flagsByBase: [ObjectIdentifier: DoviComposerFlags] = [:]
+        func blMax(of base: CVPixelBuffer) -> UInt32? {
+            lock.lock(); defer { lock.unlock() }
+            return _blMaxByBase[ObjectIdentifier(base)]
+        }
+        func flags(of base: CVPixelBuffer) -> DoviComposerFlags? {
+            lock.lock(); defer { lock.unlock() }
+            return _flagsByBase[ObjectIdentifier(base)]
+        }
+        func acquireSlot() {}
+        func releaseSlot() {}
+        func flush() {}
+        func composeAsync(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer, params: DoviMetalParams,
+                          frameIndex: UInt32, completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            composeAsyncWithAcquiredSlot(baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer,
+                                         params: params, frameIndex: frameIndex, completion: completion)
+        }
+        func composeAsyncWithAcquiredSlot(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer,
+                                          params: DoviMetalParams, frameIndex: UInt32,
+                                          completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            lock.lock()
+            _blMaxByBase[ObjectIdentifier(baseBuffer)] = params.blMax
+            _flagsByBase[ObjectIdentifier(baseBuffer)] = params.flags
+            lock.unlock()
+            completion(baseBuffer)
+        }
+    }
+
+    @Test("the previous mapping is the previous frame in the stream, not the previous frame to finish pairing")
+    func previousMappingFollowsDecodeOrder() async throws {
+        let composer = ParamsRecordingComposer()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        defer { decoder.close() }
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+
+        func mapping(_ tag: UInt32) -> DoviMetalParams { var p = Self.params(); p.blMax = tag; return p }
+        // Packets, in decode order: A, B, "same as before", an RPU that failed, then C.
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: mapping(100), displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: mapping(200), displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(2), params: nil, displayMetadataNAL: nil, usesPrevious: true)
+        decoder.seedRPUForTesting(pts: Self.pts(3), params: nil, displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(4), params: mapping(300), displayMetadataNAL: nil)
+
+        // The layers pair in a different order: 0, then 4 and 2 and 3 before 1.
+        var bases: [Int: CVPixelBuffer] = [:]
+        for frame in [0, 4, 2, 3, 1] {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            bases[frame] = bl
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(frame)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(frame)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == 5 }
+        let blMax = (0..<5).map { composer.blMax(of: bases[$0]!) }
+        #expect(blMax == [100, 200, 200, 200, 300])
+    }
+
+    @Test("a use_prev frame keeps the previous mapping but takes its own disable_residual_flag")
+    func usePreviousTakesOwnResidualFlag() async throws {
+        let composer = ParamsRecordingComposer()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        defer { decoder.close() }
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+
+        var full = Self.params(); full.blMax = 100
+        var noResidual = full; noResidual.flags.insert(.disableResidual)
+        // A residual-less RPU, then "same mapping" frames that switch the residual on and off again.
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: noResidual, displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: nil, displayMetadataNAL: nil, usesPrevious: true, disableResidual: false)
+        decoder.seedRPUForTesting(pts: Self.pts(2), params: nil, displayMetadataNAL: nil, usesPrevious: true, disableResidual: true)
+
+        var bases: [CVPixelBuffer] = []
+        for frame in 0..<3 {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            bases.append(bl)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(frame)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(frame)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == 3 }
+        #expect(bases.map { composer.blMax(of: $0) } == [100, 100, 100], "the mapping carries over")
+        #expect(bases.map { composer.flags(of: $0)?.contains(.disableResidual) } == [true, false, true],
+                "each frame's own disable_residual_flag wins over the borrowed parameters'")
+    }
+
+    #if DEBUG
+    @Test("side data recorded for post-seek packets while flush() drains survives the flush and composes")
+    func sideDataRecordedDuringTheDrainSurvivesFlush() async throws {
+        let composer = ParamsRecordingComposer()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        defer {
+            decoder.flushRaceHookForTesting = nil
+            decoder.close()
+        }
+
+        func mapping(_ tag: UInt32) -> DoviMetalParams { var p = Self.params(); p.blMax = tag; return p }
+        // A pre-seek RPU that the flush must discard, and a post-seek one the demux thread records
+        // while the hardware drain is still running (the hook runs between the two critical sections).
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: mapping(100), displayMetadataNAL: nil)
+        decoder.flushRaceHookForTesting = { [weak decoder] in
+            decoder?.seedRPUForTesting(pts: Self.pts(10), params: mapping(777), displayMetadataNAL: nil)
+        }
+        decoder.flush()
+
+        let staleBL = try #require(Self.baseLayer())
+        let staleEL = try #require(Self.enhancementLayer())
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        decoder.handleEnhancementLayerFrame(elBuffer: staleEL, pts: Self.pts(0))
+        decoder.handleBaseLayerFrame(baseBuffer: staleBL, pts: Self.pts(0), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(10))
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(10), hdr10Data: nil)
+        try await waitFor { deliveries.count == 2 }
+        #expect(composer.blMax(of: bl) == 777, "the RPU recorded during the drain must compose its frame")
+        #expect(composer.blMax(of: staleBL) == nil, "the pre-seek RPU is gone")
+    }
+
+    @Test("two flushes gated at the same point run one after the other: no interleaving, no stall, no stale delivery")
+    func concurrentFlushesAreSerialised() async throws {
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: false)
+        defer {
+            decoder.flushRaceHookForTesting = nil
+            decoder.close()
+        }
+        for i in 0..<3 {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == 3 }
+
+        let firstInHook = BoolFlag()
+        let hookCalls = LockedCounter()
+        let release = DispatchSemaphore(value: 0)
+        decoder.flushRaceHookForTesting = {
+            // Only the first flush to get here is held; the second must never get this far while it is.
+            if hookCalls.incrementAndCheckFirst() {
+                firstInHook.set()
+                release.wait()
+            }
+        }
+        let epochBefore = decoder.feedEpoch
+        let firstDone = BoolFlag()
+        let secondDone = BoolFlag()
+        BlockingWork.detached { decoder.flush(); firstDone.set() }
+        try await waitFor { firstInHook.isSet }
+        #expect(decoder.feedEpoch == epochBefore + 1)
+
+        let secondArrived = BoolFlag()
+        decoder.flushWillTakeLifecycleLockHookForTesting = { secondArrived.set() }
+        BlockingWork.detached { decoder.flush(); secondDone.set() }
+        // The second flush must stay out of its critical section (the epoch must not move, `draining`
+        // must stay owned by the first) while the first is held. Wait until it has reached the lock,
+        // by a hook rather than by a delay, then check: if the lock were missing it would be past
+        // the epoch bump within a few instructions, and `release` is still unsignalled, so the first
+        // flush cannot be what moved it.
+        try await waitFor { secondArrived.isSet }
+        #expect(!secondDone.isSet)
+        #expect(decoder.feedEpoch == epochBefore + 1, "the second flush interleaved with the first")
+
+        release.signal()
+        try await waitFor { firstDone.isSet && secondDone.isSet }
+        #expect(decoder.feedEpoch == epochBefore + 2)
+
+        // Delivery works afterwards: new frames take tickets under the final epoch and come out in order.
+        for i in 3..<6 {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == 6 }
+        let got = deliveries.snapshot
+        #expect(got.count == 6, "a frame was delivered twice or a ticket was lost")
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+    #endif
+
+    @Test("composedFrameCount counts compositions only, not bypasses, and survives flush()")
+    func composedFrameCountIgnoresBypassesAndFlush() async throws {
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ParamsRecordingComposer())
+        defer { decoder.close() }
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        #expect(decoder.composedFrameCount == 0)
+
+        // Frame 0 has an RPU and its enhancement layer: composed. Frame 1 has no RPU: bypassed.
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: Self.params(), displayMetadataNAL: nil)
+        for frame in 0..<2 {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(frame)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(frame)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == 2 }
+        #expect(decoder.composedFrameCount == 1)
+        decoder.flush()
+        #expect(decoder.composedFrameCount == 1, "the 1 Hz summary and flush reset their own counters, not this one")
+    }
+
+    @Test("frames without a timestamp pair with nothing, and never trap the key arithmetic")
+    func missingTimestampNeverMatchesOrTraps() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+        let waitingBL = try #require(Self.baseLayer())
+        let waitingEL = try #require(Self.enhancementLayer())
+        let noPtsBL = try #require(Self.baseLayer())
+        let noPtsEL = try #require(Self.enhancementLayer())
+
+        // A base-layer frame and an enhancement-layer frame are each waiting on a partner at a normal time.
+        decoder.handleBaseLayerFrame(baseBuffer: waitingBL, pts: Self.pts(5), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: waitingEL, pts: Self.pts(9))
+        // Then a frame of each layer arrives with no PTS (`AV_NOPTS_VALUE` is `Int64.min`).
+        decoder.handleEnhancementLayerFrame(elBuffer: noPtsEL, pts: .invalid)
+        decoder.handleBaseLayerFrame(baseBuffer: noPtsBL, pts: .invalid, hdr10Data: nil)
+
+        // The enhancement layer without a timestamp was dropped, and the two waiting frames are untouched.
+        let snapshot = decoder.stateSnapshotForTesting
+        #expect(snapshot.elQueueCount == 1)
+        #expect(snapshot.blQueueCount == 1)
+        // The base layer without a timestamp bypassed at once, but under its own ticket: it stays behind
+        // the waiting frame that arrived first.
+        #expect(deliveries.count == 0)
+        // Completing the waiting pair releases both, in arrival order.
+        decoder.handleEnhancementLayerFrame(elBuffer: Self.enhancementLayer()!, pts: Self.pts(5))
+        try await waitFor { deliveries.count == 2 }
+        #expect(deliveries.snapshot.last?.buffer === noPtsBL)
+    }
+
+    @Test("the side-data ring does not trap on, or match, a missing key")
+    func ringIgnoresMissingKeys() {
+        var ring = FrameSideDataRing()
+        ring.insert(key: 1_000_000, params: DoviMetalParams(), dmNAL: [1, 2, 3])
+        ring.insert(key: -5_000_000_000, params: DoviMetalParams())
+        #expect(ring.find(key: Int64.min) == nil)
+        #expect(ring.removeParams(key: Int64.min) == nil)
+        #expect(ring.removeDisplayMetadata(key: Int64.min) == nil)
+        #expect(ring.count == 2)
+        #expect(FrameSideDataRing.distance(Int64.max, -Int64.max) == nil)
+        #expect(FrameSideDataRing.distance(10, 4) == 6)
+        #expect(!FrameSideDataRing.isWithinJitter(Int64.min, Int64.min))
+        #expect(FrameSideDataRing.isWithinJitter(1000, 1300))
+        #expect(!FrameSideDataRing.isWithinJitter(1000, 1301))
+    }
+
+    // MARK: - Flush and close
+
+    @Test("nothing composed before a flush is delivered after the flush returns", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func flushRetiresOutstandingFrames() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        for i in 0..<6 {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        decoder.flush()
+        deliveries.setMarker()
+
+        // The decoder is usable after a flush: a fresh single-layer frame goes straight out.
+        decoder.primeForTesting(enhancementLayer: false)
+        let after = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: after, pts: Self.pts(100), hdr10Data: nil)
+        decoder.quiesceForTesting()
+
+        let late = deliveries.snapshot.filter { $0.afterMarker }
+        #expect(late.count == 1)
+        #expect(late.first?.buffer === after)
+    }
+
+    @Test("nothing is delivered after close returns", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func closeStopsDelivery() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+
+        for i in 0..<6 {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        decoder.close()
+        deliveries.setMarker()
+        decoder.quiesceForTesting()
+
+        #expect(deliveries.snapshot.allSatisfy { !$0.afterMarker })
+    }
+
+    @Test("close resets stream state and the decoder refuses to reopen")
+    func closeResetsStreamStateAndRefusesReopen() async throws {
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+
+        // Latch the MEL state a reopened instance must never inherit.
+        decoder.primeStreamForTesting(.mel)
+        #expect(decoder.streamClassificationForTesting == .mel)
+
+        decoder.close()
+
+        let snap = decoder.stateSnapshotForTesting
+        #expect(snap.isClosed)
+        #expect(!snap.isFEL && !snap.isMEL && !snap.streamClassified)
+        #expect(!snap.primaryDecoderInitialized)
+        #expect(!snap.enhancementEngaged)
+        #expect(snap.frameIndex == 0)
+        #expect(snap.blQueueCount == 0)
+        #expect(snap.elQueueCount == 0)
+        #expect(snap.rpuCacheCount == 0)
+        #expect(snap.dmRpuCacheCount == 0)
+        #expect(snap.deliveryPendingCount == 0)
+        #expect(snap.deliveryNextTicket == 0)
+        #expect(snap.deliveryNextToEmit == 0)
+        // Additional fields made explicit in snapshot (cheap to check):
+        #expect(!snap.draining)
+        #expect(snap.timeBaseNum == 1 && snap.timeBaseDen == 90000)
+        #expect(!snap.hasBLVPS && !snap.hasBLSPS && !snap.hasBLPPS)
+        #expect(!snap.hasELVPS && !snap.hasELSPS && !snap.hasELPPS)
+        #expect(!snap.hasSkipUntilPTS)
+        #expect(!snap.hasOnFrame)
+
+        // Single use: `open` after `close` refuses. `open` checks the flag
+        // before touching `stream`, so uninitialized storage suffices here.
+        let raw = UnsafeMutableRawPointer.allocate(
+            byteCount: MemoryLayout<AVStream>.size,
+            alignment: MemoryLayout<AVStream>.alignment)
+        defer { raw.deallocate() }
+        let stream = raw.assumingMemoryBound(to: AVStream.self)
+        do {
+            try decoder.open(stream: stream) { _, _, _ in }
+            Issue.record("open after close must refuse with VideoDecoderError.decoderClosed")
+        } catch VideoDecoderError.decoderClosed {
+            // Expected: single-use decoder.
+        }
+
+        // A post-close base-layer frame must not reach the cleared `onFrame`.
+        // `isClosed` gates `handleBaseLayerFrame` before any ticket is issued;
+        // settling before the negative check makes that hold by construction,
+        // as in every other post-teardown check in this file.
+        let bl = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(0), hdr10Data: nil)
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 0)
+        #expect(decoder.stateSnapshotForTesting.deliveryPendingCount == 0)
+
+        // decode-after-close early-returns before touching the packet payload:
+        // the entry gate refuses without forwarding to either sub-decoder.
+        let packet = try #require(av_packet_alloc())
+        defer { var p: UnsafeMutablePointer<AVPacket>? = packet; av_packet_free(&p) }
+        decoder.decode(packet: packet)
+        decoder.decode(packet: packet, epoch: decoder.feedEpoch)
+        // No sub-decoders to check here (real decoders), but entry gate blocks.
+
+        // flush-after-close is a no-op: still closed, epoch untouched, silent.
+        decoder.flush()
+        #expect(decoder.stateSnapshotForTesting.isClosed)
+        #expect(decoder.feedEpoch == decoder.stateSnapshotForTesting.feedEpoch)
+
+        // Double close is safe and idempotent.
+        decoder.close()
+        #expect(decoder.stateSnapshotForTesting.isClosed)
+    }
+
+    @Test("decode and flush after close are no-ops; double close is safe")
+    func closeRefusesDecodeAndFlushAndDoubleClose() async throws {
+        let primary = CountingFakeDecoder()
+        let enhancement = CountingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        let deliveries = Deliveries()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+
+        let epochBeforeClose = decoder.feedEpoch
+        decoder.close()
+        let snap = decoder.stateSnapshotForTesting
+        #expect(snap.isClosed)
+        #expect(snap.blQueueCount == 0 && snap.elQueueCount == 0)
+        #expect(snap.rpuCacheCount == 0 && snap.dmRpuCacheCount == 0)
+        #expect(snap.deliveryPendingCount == 0)
+        #expect(decoder.feedEpoch == epochBeforeClose + 1)
+
+        // decode-after-close early-returns before touching the packet payload:
+        // the entry gate refuses without forwarding to either sub-decoder.
+        let packet = try #require(av_packet_alloc())
+        defer { var p: UnsafeMutablePointer<AVPacket>? = packet; av_packet_free(&p) }
+        decoder.decode(packet: packet)
+        decoder.decode(packet: packet, epoch: decoder.feedEpoch)
+        #expect(primary.decodeCount == 0)
+        #expect(enhancement.decodeCount == 0)
+        #expect(!decoder.stateSnapshotForTesting.enhancementEngaged)
+
+        // flush-after-close is a no-op: still closed, epoch untouched, silent.
+        decoder.flush()
+        #expect(decoder.stateSnapshotForTesting.isClosed)
+        #expect(decoder.feedEpoch == epochBeforeClose + 1)
+        #expect(primary.flushCount == 0)
+        #expect(enhancement.flushCount == 0)
+
+        // Post-close frame handlers and in-flight deliveries stay silent and
+        // issue no tickets.
+        let ticketsBefore = decoder.stateSnapshotForTesting.deliveryNextTicket
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(0), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(0))
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 0)
+        #expect(decoder.stateSnapshotForTesting.deliveryNextTicket == ticketsBefore)
+
+        // Double close is safe and idempotent.
+        decoder.close()
+        #expect(decoder.stateSnapshotForTesting.isClosed)
+        #expect(primary.closeCount >= 1)
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 0)
+    }
+
+    @Test("frames emitted from inside flush() are dropped and never delivered")
+    func flushDropsFramesEmittedFromInsideFlush() async throws {
+        // Synchronous composer, so any composition a drained frame managed to
+        // start would retire — and deliver — on the calling thread. If nothing
+        // arrives, the draining gate held on every path.
+        let primary = FlushEmittingFakeDecoder()
+        let enhancement = FlushEmittingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        let deliveries = Deliveries()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        defer { decoder.close() }
+
+        let drainBL0 = try #require(Self.baseLayer())
+        let drainEL0 = try #require(Self.enhancementLayer())
+        let drainBL2 = try #require(Self.baseLayer())
+        let drainEL2 = try #require(Self.enhancementLayer())
+        let pre0 = SendableFrameBuffer(value: drainBL0)
+        let pre0e = SendableFrameBuffer(value: drainEL0)
+        let pre2 = SendableFrameBuffer(value: drainBL2)
+        let pre2e = SendableFrameBuffer(value: drainEL2)
+        decoder.seedRPUForTesting(pts: Self.pts(0), params: Self.params(), displayMetadataNAL: nil)
+        decoder.seedRPUForTesting(pts: Self.pts(2), params: Self.params(), displayMetadataNAL: nil)
+        // What the installed `onFrame` closures would do with owed pre-seek
+        // frames: re-enter the pairing handlers from inside the flush, in both
+        // arrival orders (primary drains first, then enhancement).
+        primary.emitFromInsideFlush = {
+            decoder.handleBaseLayerFrame(baseBuffer: pre0.value, pts: Self.pts(0), hdr10Data: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: pre0e.value, pts: Self.pts(0))
+        }
+        enhancement.emitFromInsideFlush = {
+            decoder.handleEnhancementLayerFrame(elBuffer: pre2e.value, pts: Self.pts(2))
+            decoder.handleBaseLayerFrame(baseBuffer: pre2.value, pts: Self.pts(2), hdr10Data: nil)
+        }
+
+        decoder.flush()
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 0, "pre-seek frames drained during flush() must never be delivered")
+
+        // The decoder is usable after the flush: a fresh pair composes and delivers.
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: nil)
+        // Even a synchronous composition's delivery is one more
+        // `queue.async` hop through `OrderedDelivery` away, so
+        // `handleBaseLayerFrame` returning is not a guarantee `onFrame` has
+        // run yet for it.
+        try await waitFor { deliveries.count == 1 }
+        #expect(deliveries.count == 1)
+        #expect(CMTimeCompare(deliveries.snapshot.first?.pts ?? .invalid, Self.pts(1)) == 0)
+    }
+
+    // MARK: - Thread safety
+
+    /// Synchronous composer so the stress test needs no GPU: every composition
+    /// retires on the calling thread instead of on a Metal completion queue.
+    ///
+    /// Delivery is still asynchronous: every frame, composed or bypassed, is
+    /// one more `queue.async` hop away from `onFrame` regardless of how this
+    /// fake calls its `completion`. What this fake buys a test: pairing and composition finish deterministically, in program
+    /// order, with no GPU and no wait for a command buffer to retire, so a
+    /// test can reason about ticket order and queue depth without also
+    /// reasoning about the exactly-once assertions being asynchronous;
+    /// tests below still have to wait for the frame to actually leave
+    /// `OrderedDelivery`'s own queue (`waitFor`/`settle`).
+    private final class ImmediateFakeComposer: FelComposing, @unchecked Sendable {
+        func acquireSlot() {}
+        func releaseSlot() {}
+        func flush() {}
+        func composeAsync(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            completion(baseBuffer)
+        }
+        func composeAsyncWithAcquiredSlot(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            completion(baseBuffer)
+        }
+    }
+
+    private struct SendableFrameBuffer: @unchecked Sendable {
+        let value: CVPixelBuffer
+    }
+
+    /// Fake single-layer decoder: runs a hook from inside `flush()`,
+    /// the way `HardwareVideoDecoder.flush()` re-enters the frame callbacks
+    /// with the frames VideoToolbox still owes while the host thread is
+    /// blocked inside the flush.
+    private final class FlushEmittingFakeDecoder: SingleLayerVideoDecoder, @unchecked Sendable {
+        var onFrame: DecodedFrameHandler?
+        var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+        var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+        var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+        var skipUntilPTS: CMTime?
+        var feedEpoch: UInt64 = 0
+        var emitFromInsideFlush: (() -> Void)?
+        func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {
+            self.onFrame = onFrame
+        }
+        func open(
+            parameterSets: [[UInt8]],
+            timeBase: AVRational,
+            onFrame: @escaping DecodedFrameHandler
+        ) throws {
+            self.onFrame = onFrame
+        }
+        func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?) {}
+        func flush() { emitFromInsideFlush?() }
+        func close() { onFrame = nil }
+    }
+
+    /// Counting fake: records sub-decoder traffic so tests can prove
+    /// post-close `decode`/`flush` never reach the torn-down sessions.
+    private final class CountingFakeDecoder: SingleLayerVideoDecoder, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _decodeCount = 0
+        private var _flushCount = 0
+        private var _closeCount = 0
+        var decodeCount: Int { lock.lock(); defer { lock.unlock() }; return _decodeCount }
+        var flushCount: Int { lock.lock(); defer { lock.unlock() }; return _flushCount }
+        var closeCount: Int { lock.lock(); defer { lock.unlock() }; return _closeCount }
+        var onFrame: DecodedFrameHandler?
+        var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+        var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+        var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+        var skipUntilPTS: CMTime?
+        var feedEpoch: UInt64 = 0
+        func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {
+            self.onFrame = onFrame
+        }
+        func open(
+            parameterSets: [[UInt8]],
+            timeBase: AVRational,
+            onFrame: @escaping DecodedFrameHandler
+        ) throws {
+            self.onFrame = onFrame
+        }
+        func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?) {
+            lock.lock(); _decodeCount += 1; lock.unlock()
+        }
+        func flush() { lock.lock(); _flushCount += 1; lock.unlock() }
+        func close() { lock.lock(); _closeCount += 1; lock.unlock(); onFrame = nil }
+    }
+
+    @Test("concurrent layer arrivals and control-plane churn keep exactly-once delivery; close under load stays silent")
+    func concurrentArrivalsAndTeardown() async throws {
+        let frames = 64
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        for i in 0..<frames {
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+        }
+        let bl: [SendableFrameBuffer] = try (0..<frames).map { _ in
+            guard let b = Self.baseLayer() else { throw CancellationError() }
+            return SendableFrameBuffer(value: b)
+        }
+        let el: [SendableFrameBuffer] = try (0..<frames).map { _ in
+            guard let e = Self.enhancementLayer() else { throw CancellationError() }
+            return SendableFrameBuffer(value: e)
+        }
+
+        let group = DispatchGroup()
+        for i in 0..<frames {
+            group.enter()
+            DispatchQueue.global().async {
+                // Alternate arrival order per pair to hit both pairing paths.
+                if i % 2 == 0 {
+                    decoder.handleBaseLayerFrame(baseBuffer: bl[i].value, pts: Self.pts(Int64(i)), hdr10Data: nil)
+                    decoder.handleEnhancementLayerFrame(elBuffer: el[i].value, pts: Self.pts(Int64(i)))
+                } else {
+                    decoder.handleEnhancementLayerFrame(elBuffer: el[i].value, pts: Self.pts(Int64(i)))
+                    decoder.handleBaseLayerFrame(baseBuffer: bl[i].value, pts: Self.pts(Int64(i)), hdr10Data: nil)
+                }
+                group.leave()
+            }
+            // Control-plane churn on the same shared state the VT threads touch.
+            group.enter()
+            DispatchQueue.global().async {
+                decoder.skipUntilPTS = Self.pts(Int64(i))
+                _ = decoder.skipUntilPTS
+                _ = decoder.streamClassificationForTesting
+                _ = decoder.engagesEnhancementLayerForTesting()
+                decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+                group.leave()
+            }
+        }
+        // `notify` parks nothing; a hang is reported by the suite's `.timeLimit`.
+        await withCheckedContinuation { cont in group.notify(queue: .global()) { cont.resume() } }
+
+        // Every base layer is delivered exactly once however it got out (paired,
+        // pruned or bypassed); enhancement-only orphans never deliver alone.
+        // The `DispatchGroup` above only covers pairing — each frame's
+        // actual delivery is one more `queue.async` hop through
+        // `OrderedDelivery` beyond that, so it can still be in flight once
+        // every pairing call has returned.
+        let sentIDs = Set(bl.map { ObjectIdentifier($0.value) })
+        var nudgeIDs: Set<ObjectIdentifier> = []
+        do {
+            // Nudged unconditionally, so the test does not have to decide by a timeout whether
+            // frames are stranded. `collectDueBypasses` ages a queued base-layer frame out after
+            // `K` further base-layer *arrivals*, not elapsed time, and only runs from inside
+            // `handleBaseLayerFrame`. This test's 64-way unthrottled fan-out delivers each layer
+            // out of decode order essentially every run (measured: 2–3 of 64 base-layer frames
+            // stranded in `blFrameQueue` in 40 of 40 runs; two threads delivering each layer in
+            // decode order stranded 0 of 40). That cannot happen mid-stream in production, where
+            // VideoToolbox outputs each layer in decode order; the only production exposure is
+            // the last base-layer frames at end of stream whose enhancement layer never arrives,
+            // which is the K-frame bound itself. A base layer can be scheduled so late that
+            // "newest settled base layer" has already raced ahead of it; its enhancement layer is
+            // then correctly dropped as stale, and no further base-layer arrival happens within
+            // this batch to age it out before the `DispatchGroup` above finishes. It is still
+            // queued, not lost: a few harmless, never-pairing nudges (fresh buffers, PTS values
+            // outside this test's range) advance `blArrivalSeq` past it.
+            for i in 0..<(DualLayerVideoDecoder.maxLayerSkewFrames + 1) {
+                guard let nudge = Self.baseLayer() else { break }
+                nudgeIDs.insert(ObjectIdentifier(nudge))
+                decoder.handleBaseLayerFrame(baseBuffer: nudge, pts: Self.pts(Int64(900 + i)), hdr10Data: nil)
+            }
+            try await waitFor {
+                deliveries.snapshot.filter { sentIDs.contains(ObjectIdentifier($0.buffer)) }.count >= frames
+            }
+        }
+        // `allSatisfy`, not a `filter`: an enhancement-layer buffer (or
+        // anything else) delivered on its own is what this catches; sent
+        // base-layer frames and the nudges above are the only buffers ever
+        // allowed out.
+        let allowed = sentIDs.union(nudgeIDs)
+        #expect(deliveries.snapshot.allSatisfy { allowed.contains(ObjectIdentifier($0.buffer)) },
+                "only sent base-layer frames or the nudges that age out stranded ones may ever be delivered")
+        let got = deliveries.snapshot.filter { sentIDs.contains(ObjectIdentifier($0.buffer)) }
+        #expect(got.count == frames)
+        #expect(Set(got.map { ObjectIdentifier($0.buffer) }).count == frames)
+
+        // Teardown under load: arrivals racing close() are either delivered
+        // before it or dropped after it; nothing lands past the marker.
+        let teardown = DispatchGroup()
+        for i in frames..<(frames + 8) {
+            teardown.enter()
+            DispatchQueue.global().async {
+                if let b = Self.baseLayer(), let e = Self.enhancementLayer() {
+                    decoder.handleBaseLayerFrame(baseBuffer: b, pts: Self.pts(Int64(i)), hdr10Data: nil)
+                    decoder.handleEnhancementLayerFrame(elBuffer: e, pts: Self.pts(Int64(i)))
+                }
+                teardown.leave()
+            }
+        }
+        teardown.enter()
+        DispatchQueue.global().async {
+            decoder.flush()
+            decoder.close()
+            teardown.leave()
+        }
+        await withCheckedContinuation { cont in teardown.notify(queue: .global()) { cont.resume() } }
+        deliveries.setMarker()
+        if let b = Self.baseLayer(), let e = Self.enhancementLayer() {
+            decoder.handleBaseLayerFrame(baseBuffer: b, pts: Self.pts(10_000), hdr10Data: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: e, pts: Self.pts(10_000))
+        }
+        decoder.quiesceForTesting()
+        #expect(deliveries.snapshot.allSatisfy { !$0.afterMarker })
+    }
+
+    // MARK: - Delivery queue
+
+    /// Fake composer whose Nth call (1-indexed) never calls its completion at
+    /// all — the one failure mode a ticket cannot self-report, unlike a
+    /// bypass or a "compose failed" fallback. Every other call completes
+    /// synchronously with the base layer, like `ImmediateFakeComposer`.
+    private final class DroppingFakeComposer: FelComposing, @unchecked Sendable {
+        private let dropOnCall: Int
+        private let lock = NSLock()
+        private var calls = 0
+        init(dropOnCall: Int) { self.dropOnCall = dropOnCall }
+        func acquireSlot() {}
+        func releaseSlot() {}
+        func flush() {}
+        func composeAsync(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            composeAsyncWithAcquiredSlot(baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer, params: params, frameIndex: frameIndex, completion: completion)
+        }
+        func composeAsyncWithAcquiredSlot(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            lock.lock(); calls += 1; let n = calls; lock.unlock()
+            if n == dropOnCall {
+                // Simulates a completion that never fires: no call to
+                // `completion`, so the ticket this composition took is never
+                // fulfilled at all.
+                return
+            }
+            completion(baseBuffer)
+        }
+    }
+
+    @Test("a composition whose completion never fires costs exactly one frame, not the session")
+    func lostCompletionCostsExactlyOneFrame() async throws {
+        let threshold = DoviFelComposer.maxFramesInFlight + DualLayerVideoDecoder.maxLayerSkewFrames + 2
+        let composer = DroppingFakeComposer(dropOnCall: 1)
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        defer { decoder.close() }
+
+        // Every frame pairs immediately (EL arrives first, so `handleBaseLayerFrame`
+        // composes on the spot) so ticket `i` and loop index `i` coincide. The
+        // first composition's ticket (0) is the one `DroppingFakeComposer` drops;
+        // enough frames follow to push it past `orderedDelivery`'s stall
+        // threshold (`maxFramesInFlight + K + 2`).
+        let frames = threshold + 6
+        for i in 0..<frames {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+
+        try await waitFor { deliveries.count == frames - 1 }
+        let got = deliveries.snapshot
+        #expect(got.count == frames - 1, "every frame but the one lost ticket must still be delivered")
+        #expect(Self.isStrictlyIncreasing(got), "the stall guard must not disturb the order of the frames it does deliver")
+    }
+
+    #if DEBUG
+    @Test("a ticket raced into the gap between flush()'s unlock and its delivery barrier is not lost")
+    func flushDoesNotLosePostFlushTicketInTheUnlockToBarrierGap() async throws {
+        // Regression test for an ordering race in `flush()`: drives a ticket
+        // through the window a post-flush ticket could be lost in —
+        // right after the critical section that bumps `_feedEpoch`, captures
+        // `nextTicket` and enqueues `orderedDelivery.resetAsync` releases
+        // `lock`, but before `orderedDelivery.barrier()` confirms that reset
+        // has actually run — using `flushRaceHookForTesting`/
+        // `raceTicketForTesting` rather than waiting on a real, sub-
+        // microsecond production race.
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: false)
+        defer {
+            decoder.flushRaceHookForTesting = nil
+            decoder.close()
+        }
+
+        for i in 0..<5 {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { deliveries.count == 5 }
+
+        let racer = try #require(Self.baseLayer())
+        decoder.flushRaceHookForTesting = { [weak decoder] in
+            decoder?.raceTicketForTesting(buffer: racer, pts: Self.pts(5))
+        }
+
+        decoder.flush()
+
+        // The raced ticket must have been delivered exactly once — not
+        // dropped as stale-epoch, and not left stalled
+        // behind a hole that never fills.
+        try await waitFor { deliveries.count == 6 }
+        let got = deliveries.snapshot
+        let late = got.filter { CMTimeCompare($0.pts, Self.pts(5)) == 0 }
+        #expect(late.count == 1, "the ticket raced into the unlock-to-barrier gap must be delivered exactly once, not dropped")
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+    #endif
+
+    /// A packet carrying in-band parameter sets and one (garbage) slice, as `decode(packet:)` sees it.
+    private static func inBandPacket(pts: Int64) throws -> UnsafeMutablePointer<AVPacket> {
+        let slice = hevcNAL(type: 1, payload: [0x11, 0x22, 0x33, 0x44])
+        return try #require(makeAvccPacket([hevcVPS, hevcSPS, hevcPPS, slice], pts: pts))
+    }
+
+    #if DEBUG
+    @Test("a post-seek packet fed with the new epoch between the dual epoch bump and the sub-decoder flush reaches VideoToolbox; a pre-seek one does not")
+    func postSeekPacketInTheFlushWindowIsNotDropped() async throws {
+        // The host feeds from the demux thread while a seek's flush() runs. It reads the new epoch the
+        // moment flush() publishes it. The sub-decoders used to move only in their own flush(), later,
+        // so a packet fed in this window passed the dual gate and was refused by a decoder still on
+        // the old epoch: the post-seek IRAP never reached VideoToolbox.
+        let primary = HardwareVideoDecoder()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer(), primaryDecoder: primary, enhancementDecoder: nil)
+        decoder.onFrame = { _, _, _ in }
+        defer { decoder.flushWillTakeLifecycleLockHookForTesting = nil; decoder.flushRaceHookForTesting = nil; decoder.close() }
+        let submitted = LockedCounter()
+        primary.onSubmittedToVideoToolboxForTesting = { submitted.increment() }
+
+        // The first packet opens the primary decoder from its in-band parameter sets.
+        let pre = try Self.inBandPacket(pts: 0)
+        defer { var p: UnsafeMutablePointer<AVPacket>? = pre; trackedPacketFree(&p) }
+        decoder.decode(packet: pre, epoch: decoder.feedEpoch)
+        if decoder.fatalDecodeError != nil { try Test.cancel("hardware HEVC session unavailable: \(decoder.fatalDecodeError!)") }
+        #expect(submitted.value == 1)
+        let oldEpoch = decoder.feedEpoch
+
+        let post = try Self.inBandPacket(pts: 90000)
+        defer { var p: UnsafeMutablePointer<AVPacket>? = post; trackedPacketFree(&p) }
+        let submittedInWindow = LockedCounter()
+        decoder.flushRaceHookForTesting = {
+            // flush() has published the new epoch and not yet touched the sub-decoders.
+            decoder.decode(packet: post, epoch: decoder.feedEpoch)
+            submittedInWindow.set(submitted.value)
+        }
+        decoder.flush()
+        #expect(decoder.feedEpoch == oldEpoch + 1)
+        #expect(primary.feedEpoch == oldEpoch + 1, "the sub-decoder's own flush must not move the epoch a second time")
+        #expect(submittedInWindow.value == 2, "the post-seek packet fed inside the window never reached VideoToolbox")
+
+        // DEC-4: a packet decided under the old epoch must not enter VideoToolbox after the flush.
+        decoder.decode(packet: pre, epoch: oldEpoch)
+        #expect(submitted.value == 2)
+        // And the epoch the host would read next is accepted.
+        decoder.decode(packet: post, epoch: decoder.feedEpoch)
+        #expect(submitted.value == 3)
+    }
+    #endif
+
+    /// Fake whose in-band open always fails.
+    private final class FailingOpenFakeDecoder: SingleLayerVideoDecoder, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _opens = 0, _decodes = 0
+        var openCount: Int { lock.lock(); defer { lock.unlock() }; return _opens }
+        var decodeCount: Int { lock.lock(); defer { lock.unlock() }; return _decodes }
+        struct OpenFailed: Error {}
+        var onFrame: DecodedFrameHandler?
+        var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+        var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+        var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+        var skipUntilPTS: CMTime?
+        var feedEpoch: UInt64 = 0
+        func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {}
+        func open(parameterSets: [[UInt8]], timeBase: AVRational, onFrame: @escaping DecodedFrameHandler) throws {
+            lock.lock(); _opens += 1; lock.unlock()
+            throw OpenFailed()
+        }
+        func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?) { lock.lock(); _decodes += 1; lock.unlock() }
+        func flush() {}
+        func close() {}
+    }
+
+    @Test("an in-band primary open that fails is reported once and not retried on every later packet")
+    func failedInBandOpenFailsOnce() throws {
+        let primary = FailingOpenFakeDecoder()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer(), primaryDecoder: primary, enhancementDecoder: nil)
+        defer { decoder.close() }
+        let reported = LockedCounter()
+        decoder.onFatalDecodeError = { _ in reported.increment() }
+        let lines = LockedCounter()
+        let previous = EngineLog.handler
+        EngineLog.handler = { line in if line.contains("failed to open the primary decoder") { lines.increment() } }
+        defer { EngineLog.handler = previous }
+
+        for i in 0..<5 {
+            let pkt = try Self.inBandPacket(pts: Int64(i) * 3000)
+            decoder.decode(packet: pkt)
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+        #expect(primary.openCount == 1, "the open was retried on a later packet")
+        #expect(reported.value == 1)
+        #expect(lines.value == 1)
+        #expect(decoder.fatalDecodeError is FailingOpenFakeDecoder.OpenFailed)
+        #expect(primary.decodeCount == 0)
+    }
+
+    @Test("an enhancement decoder that fails to open is logged once and not retried on every later packet")
+    func failedEnhancementOpenFailsOnce() throws {
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer(), primaryDecoder: FailingOpenFakeDecoder(), enhancementDecoder: nil)
+        let enhancement = FailingOpenFakeDecoder()
+        let built = LockedCounter()
+        decoder.makeEnhancementDecoder = { built.increment(); return enhancement }
+        defer { decoder.close() }
+        let lines = LockedCounter()
+        let previous = EngineLog.handler
+        EngineLog.handler = { line in if line.contains("failed to initialize EL decoder") { lines.increment() } }
+        defer { EngineLog.handler = previous }
+
+        for i in 0..<5 {
+            let pkt = try Self.inBandPacket(pts: Int64(i) * 3000)
+            decoder.ensureEnhancementDecoder(from: pkt)
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+        #expect(enhancement.openCount == 1, "the open was retried on a later packet")
+        #expect(built.value == 1, "a new session was built for a later packet")
+        #expect(lines.value == 1)
+        #expect(decoder.enhancementDecoderOpenError is FailingOpenFakeDecoder.OpenFailed)
+        #expect(decoder.fatalDecodeError == nil, "a missing enhancement layer leaves the base layer to show")
+        // close() starts the next session clean.
+        decoder.close()
+        #expect(decoder.enhancementDecoderOpenError == nil)
+    }
+
+    @Test("the alignment's restamp bound is what the pairing skew bound can absorb")
+    func alignmentBoundTracksSkewBound() {
+        #expect(DualLayerVideoDecoder.makeAlignment().maxBackwardRestamp == DualLayerVideoDecoder.maxLayerSkewFrames - 1)
+    }
+
+    @Test("a crafted raw timestamp that overflows the time-base product yields no key instead of trapping")
+    func canonicalKeyIsOverflowSafe() {
+        let tb = AVRational(num: 1, den: 90000)
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: 90000, timeBase: tb) == 90000)
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: Int64.min, timeBase: tb) == Int64.min)
+        let wide = AVRational(num: 1_000_000, den: 1)
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: Int64.max, timeBase: wide) == Int64.min)
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: Int64.min + 1, timeBase: wide) == Int64.min)
+        // Large but representable products saturate in CoreMedia rather than trapping.
+        _ = DualLayerVideoDecoder.canonicalKey(rawPTS: Int64.max / 2, timeBase: AVRational(num: 2, den: 1))
+    }
+
+    @Test("a slow onFrame does not block pairing or flush() behind the decoder lock",
+          .timeLimit(.minutes(1)))
+    func slowOnFrameDoesNotBlockDecoderOperations() async throws {
+        // The old `deliver()` took the decoder's lock and called `emit` (hence
+        // `onFrame`) from inside it, so a slow host callback would have stalled
+        // every later frame handler and `flush()` behind the same lock. With
+        // `OrderedDelivery` owning `emit` on its own queue, pairing a new frame
+        // never waits on `onFrame` at all — but `flush()` is a different claim:
+        // its `orderedDelivery.barrier()` call legitimately waits for whatever
+        // `emit` is currently in the middle of before draining can proceed. The
+        // bound here is "as long as `onFrame` itself takes", not "instantly"
+        // and not "forever".
+        // `firstCallStarted` is polled rather than waited on with a semaphore:
+        // `DispatchSemaphore.wait` is unavailable from this `async` test body
+        // (it would block the cooperative thread pool), but it is exactly
+        // right *inside* the plain, non-async `onFrame` closure below, which
+        // runs on `OrderedDelivery`'s own queue and is what this test needs
+        // to hold still to prove pairing is not waiting on it.
+        let firstCallStarted = BoolFlag()
+        let releaseFirstCall = DispatchSemaphore(value: 0)
+        let callCount = LockedCounter()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        decoder.onFrame = { buffer, pts, hdr10 in
+            let isFirst = callCount.incrementAndCheckFirst()
+            if isFirst {
+                firstCallStarted.set()
+                releaseFirstCall.wait()
+            }
+            deliveries.record(buffer, pts, hdr10)
+        }
+        decoder.primeForTesting(enhancementLayer: false)
+        defer {
+            releaseFirstCall.signal() // in case an assertion below fails first
+            decoder.close()
+        }
+
+        let bl0 = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: bl0, pts: Self.pts(0), hdr10Data: nil)
+        try await waitFor { firstCallStarted.isSet }
+        #expect(firstCallStarted.isSet, "onFrame for frame 0 never started")
+
+        // While that first `onFrame` call is still parked, pairing a new frame
+        // must not wait on it at all: `handleBaseLayerFrame` only ever
+        // `fulfil`s a ticket onto `OrderedDelivery`'s queue (`queue.async`,
+        // non-blocking) and never calls into `emit`. The call returning at all,
+        // with the release semaphore still unsignalled, is the proof: if it
+        // waited on the parked `onFrame` it would never return and the test's
+        // time limit would report it. No wall-clock threshold is involved.
+        let bl1 = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: bl1, pts: Self.pts(1), hdr10Data: nil)
+
+        // `flush()` legitimately waits for the in-flight `emit` (its `barrier()`
+        // waits on the queue `emit` runs on), so it runs on a thread of its own
+        // and the release is signalled from here. It must then finish; if the
+        // decoder's lock were held across the wait it would hang, and the time
+        // limit would say so.
+        let flushDone = BoolFlag()
+        Thread.detachNewThread {
+            decoder.flush()
+            flushDone.set()
+        }
+        releaseFirstCall.signal()
+        try await waitFor { flushDone.isSet }
+        #expect(flushDone.isSet, "flush() never returned after the slow onFrame call was released")
+
+        decoder.quiesceForTesting()
+    }
+
+    /// Thread-safe increment that also reports whether this call was the
+    /// first one, without a data race between the check and the increment.
+    private final class LockedCounter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var count = 0
+        func incrementAndCheckFirst() -> Bool {
+            lock.lock(); defer { lock.unlock() }
+            count += 1
+            return count == 1
+        }
+        func increment() { lock.lock(); count += 1; lock.unlock() }
+        func set(_ v: Int) { lock.lock(); count = v; lock.unlock() }
+        var value: Int { lock.lock(); defer { lock.unlock() }; return count }
+    }
+
+    /// A boolean settable from one thread and polled from another, with no
+    /// torn reads. Used both as a "stop requested" flag and, in
+    /// `slowOnFrameDoesNotBlockDecoderOperations`, as a "started" flag — the
+    /// name is generic on purpose.
+    private final class BoolFlag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value = false
+        func set() { lock.lock(); value = true; lock.unlock() }
+        var isSet: Bool { lock.lock(); defer { lock.unlock() }; return value }
+    }
+
+    /// Lock-protected "flushes started"/"flushes returned" counters for the
+    /// per-flush I3 detector in `flushFromAnotherThreadInATightLoopKeepsInvariantI3`.
+    private final class FlushCounters: @unchecked Sendable {
+        private let lock = NSLock()
+        private var started = 0
+        private var returned = 0
+        /// Call immediately before `decoder.flush()`. Returns the new count.
+        @discardableResult
+        func beginFlush() -> Int { lock.lock(); started += 1; defer { lock.unlock() }; return started }
+        /// Call immediately after `decoder.flush()` returns.
+        func endFlush() { lock.lock(); returned += 1; lock.unlock() }
+        var startedCount: Int { lock.lock(); defer { lock.unlock() }; return started }
+        var returnedCount: Int { lock.lock(); defer { lock.unlock() }; return returned }
+    }
+
+    /// Records each frame's "started" tag (keyed by its unique PTS value) and
+    /// any I3 violation the detector in
+    /// `flushFromAnotherThreadInATightLoopKeepsInvariantI3` finds — a class,
+    /// like `Deliveries`/`FlushCounters` above, so the producer task and the
+    /// `onFrame` closure can share it as a `let` capture rather than a `var`
+    /// one, which Swift 6 strict concurrency refuses to let a closure and a
+    /// detached task mutate directly.
+    private final class ViolationTracker: @unchecked Sendable {
+        private let lock = NSLock()
+        private var startedTagByPTS: [Int64: Int] = [:]
+        private var violations: [String] = []
+
+        /// Marks a frame as being inside its pairing call. Delivery is asynchronous and can run before
+        /// the call returns, so the frame has to be known to the detector before the call starts; the
+        /// real tag replaces this once the call returns.
+        func registerInFlight(ptsValue: Int64) {
+            lock.lock(); startedTagByPTS[ptsValue] = Self.inFlight; lock.unlock()
+        }
+
+        func recordStartedTag(_ tag: Int, forPTSValue ptsValue: Int64) {
+            lock.lock(); startedTagByPTS[ptsValue] = tag; lock.unlock()
+        }
+
+        private static let inFlight = Int.max
+
+        /// Checks one delivery against the rule and records a violation if
+        /// found. Call from `onFrame`, passing the "returned" count read at
+        /// that moment.
+        func checkDelivery(ptsValue: Int64, returnedAtDelivery: Int) {
+            lock.lock()
+            defer { lock.unlock() }
+            guard let startedTag = startedTagByPTS[ptsValue] else {
+                violations.append("pts=\(ptsValue) delivered with no tag registered")
+                return
+            }
+            // Still inside its pairing call: it cannot have been paired before a flush that has since returned.
+            guard startedTag != Self.inFlight, startedTag < returnedAtDelivery else { return }
+            violations.append("pts=\(ptsValue) startedTag=\(startedTag) returnedAtDelivery=\(returnedAtDelivery)")
+        }
+
+        var snapshot: [String] { lock.lock(); defer { lock.unlock() }; return violations }
+    }
+
+    @Test("flushing from another thread in a tight loop, while frames keep arriving, never delivers a frame paired before flush k started after flush k returns (I3)")
+    func flushFromAnotherThreadInATightLoopKeepsInvariantI3() async throws {
+        // An elapsed-time bound and the epoch bump cannot detect an I3
+        // violation, and neither can `isStrictlyIncreasing` alone: a pre-flush
+        // frame delivered late still carries a lower PTS than every post-flush
+        // frame the ever-increasing producer goes on to emit.
+        //
+        // So this test uses a per-flush detector: two lock-protected counters, "flushes started" and
+        // "flushes returned". Each frame is tagged, the instant its pairing
+        // call returns, with the "started" count at that moment — how many
+        // flushes had already been kicked off by the time this frame took
+        // its ticket. Each delivery reads the "returned" count at the moment
+        // `onFrame` fires — how many flushes have already fully completed by
+        // the time this frame reached the host. The rule: a frame whose
+        // pairing call returned before flush k started (tag < k) must never
+        // reach `onFrame` after flush k has returned (returnedAtDelivery >=
+        // k). Collapsing "there exists such a k" to a single per-frame
+        // comparison is valid because the tightest possible k for any
+        // violation is the number of flushes already returned at delivery
+        // time itself: if `tag < returnedAtDelivery`, then k =
+        // returnedAtDelivery satisfies `tag < k` and `k <= returnedAtDelivery`
+        // simultaneously, which is exactly the violation shape.
+        let counters = FlushCounters()
+        let tracker = ViolationTracker()
+
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        decoder.onFrame = { buffer, pts, hdr10 in
+            let returnedAtDelivery = counters.returnedCount
+            tracker.checkDelivery(ptsValue: pts.value, returnedAtDelivery: returnedAtDelivery)
+            deliveries.record(buffer, pts, hdr10)
+        }
+        decoder.primeForTesting(enhancementLayer: false)
+        defer { decoder.close() }
+
+        let stop = BoolFlag()
+
+        let producing = BlockingWork.detached { () -> Void in
+            var i: Int64 = 0
+            while !stop.isSet {
+                if let bl = Self.baseLayer() {
+                    let pts = Self.pts(i)
+                    tracker.registerInFlight(ptsValue: pts.value)
+                    decoder.handleBaseLayerFrame(baseBuffer: bl, pts: pts, hdr10Data: nil)
+                    // The real tag is taken AFTER the handler returns, matching the detector's rule.
+                    let tag = counters.startedCount
+                    tracker.recordStartedTag(tag, forPTSValue: pts.value)
+                }
+                i += 1
+            }
+        }
+
+        // Flush back-to-back, on another thread, for as long as the producer
+        // above keeps feeding frames concurrently. Each call must still
+        // return promptly (proving no deadlock under contention) and bump the
+        // feed epoch (proving it actually ran, not a silent no-op).
+        for _ in 0..<200 {
+            counters.beginFlush()
+            let epochBefore = decoder.feedEpoch
+            // A deadlock under producer load shows as this loop never finishing, which the suite's
+            // time limit reports; a wall-clock bound per flush would only add scheduler noise.
+            decoder.flush()
+            counters.endFlush()
+            #expect(decoder.feedEpoch == epochBefore + 1)
+        }
+
+        stop.set()
+        await producing.value
+        decoder.quiesceForTesting()
+
+        let finalViolations = tracker.snapshot
+        #expect(finalViolations.isEmpty, "I3 violated: \(finalViolations.prefix(5))")
+
+        // Order is still a real property worth keeping, just not the one
+        // that actually proves I3 (see the comment above): any I3 violation
+        // this detector doesn't already flag would have to slip a stale
+        // frame in without disturbing PTS order at all, which the pairing
+        // ticket order already makes exceedingly unlikely — but it costs
+        // nothing extra to keep checking.
+        #expect(Self.isStrictlyIncreasing(deliveries.snapshot))
+    }
+
+    // MARK: - Known defects
+
+    @Test("a pruned base-layer frame cannot be delivered after a newer composed frame", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func prunedFrameDoesNotOvertakeNewerFrames() async throws {
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+
+        // Frame 0's enhancement layer is lost, so it waits in the base-layer queue.
+        let orphan = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: orphan, pts: Self.pts(0), hdr10Data: nil)
+        // Frame 1 pairs immediately and is composed.
+        let bl1 = try #require(Self.baseLayer())
+        let el1 = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: el1, pts: Self.pts(1))
+        decoder.handleBaseLayerFrame(baseBuffer: bl1, pts: Self.pts(1), hdr10Data: nil)
+        // More orphans until frame 0 is pushed out of the queue.
+        var next: Int64 = 2
+        while !deliveries.snapshot.contains(where: { $0.buffer === orphan }) && next < 60 {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(next), hdr10Data: nil)
+            next += 1
+        }
+        try await waitFor { deliveries.snapshot.contains { $0.buffer !== orphan && CMTimeCompare($0.pts, Self.pts(1)) == 0 } }
+
+        let got = deliveries.snapshot
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+
+    @Test("a lost enhancement layer delays its base layer by at most K frames, in order")
+    func lostEnhancementLayerDelaysBaseLayerByAtMostKFrames() async throws {
+        // Synchronous composer, so delivery is synchronous and the bound is exact:
+        // frame 0 waits while newer pairs settle, then goes out under its own
+        // (oldest) ticket once K newer base-layer frames have arrived.
+        let k = DualLayerVideoDecoder.maxLayerSkewFrames
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        defer { decoder.close() }
+
+        // Not `deliveries.count == 0`: delivery is always one more
+        // `queue.async` hop away, so it would read 0 whether or not frame 0
+        // was still held back. `blQueueCount` is synchronous and
+        // deterministic: `collectDueBypasses` runs entirely under `lock`
+        // inside `handleBaseLayerFrame`, so by the time that call returns,
+        // frame 0 is provably still queued (not yet bypassed) if and only
+        // if fewer than K newer base-layer frames have arrived.
+        let orphan = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: orphan, pts: Self.pts(0), hdr10Data: nil)
+        #expect(decoder.stateSnapshotForTesting.blQueueCount == 1, "a base-layer frame with a pending enhancement layer must wait for it")
+
+        for i in 1..<k {
+            let bl = try #require(Self.baseLayer())
+            let el = try #require(Self.enhancementLayer())
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        #expect(decoder.stateSnapshotForTesting.blQueueCount == 1, "only \(k - 1) newer frames have arrived; frame 0 must still wait")
+
+        let blK = try #require(Self.baseLayer())
+        let elK = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(Int64(k)), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: elK, pts: Self.pts(Int64(k)))
+        decoder.handleBaseLayerFrame(baseBuffer: blK, pts: Self.pts(Int64(k)), hdr10Data: nil)
+
+        // Releasing frame 0 (and composing frame k) both still end in
+        // a `queue.async` hop through `OrderedDelivery`, so give it a chance
+        // to drain before reading the final snapshot.
+        try await waitFor { deliveries.count == k + 1 }
+        let got = deliveries.snapshot
+        #expect(got.count == k + 1, "the Kth newer frame must release frame 0")
+        #expect(got.first?.buffer === orphan, "frame 0 kept its arrival ticket, so it goes out first")
+        #expect(Self.isStrictlyIncreasing(got))
+    }
+
+    @Test("HDR10+ side data survives whichever layer arrives last", .enabled(if: Self.metalAvailable, "needs a Metal device"))
+    func hdr10SideDataSurvivesArrivalOrder() async throws {
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        let deliveries = Deliveries()
+        let decoder = Self.decoder(recordingInto: deliveries, enhancementLayer: true)
+        defer { decoder.close() }
+        let side = Data([0xB5, 0x00, 0x3C])
+
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: side)
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+
+        try await waitFor { deliveries.count == 1 }
+        let got = deliveries.snapshot.first?.hdr10
+        #expect(got == side)
+    }
+
+    // MARK: - Composer unavailable
+
+    @Test("with no composer, EL decoder is never engaged and base layer is delivered")
+    func noComposerDisablesEnhancementLayerAndDeliversBaseLayer() async throws {
+        // Inject nil composer via internal initializer (bypasses open() which would throw).
+        let primary = CountingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: nil,
+            primaryDecoder: primary,
+            enhancementDecoder: nil
+        )
+        let deliveries = Deliveries()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        // Prime as FEL stream (what classifyPacketResultForTesting would set after first RPU)
+        decoder.primeStreamForTesting(.fel)
+        defer { decoder.close() }
+
+        // Even though stream is classified FEL, no composer → no EL engagement
+        #expect(decoder.engagesEnhancementLayerForTesting() == false, "no composer must disable EL engagement")
+        #expect(decoder.stateSnapshotForTesting.enhancementEngaged == false)
+
+        // Simulate a FEL packet: EL packet would be freed, not fed to any decoder
+        let bl = try #require(Self.baseLayer())
+        let el = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+
+        // EL arrives first - should be queued but never paired because no EL decoder exists
+        decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(1))
+        // BL arrives - should bypass and deliver immediately (no composition possible)
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(1), hdr10Data: nil)
+
+        try await waitFor { deliveries.count == 1 }
+        let got = deliveries.snapshot.first
+        #expect(got != nil, "base layer must be delivered")
+        #expect(got?.buffer === bl, "delivered buffer must be the base layer (bypass)")
+        #expect(CMTimeCompare(got?.pts ?? .invalid, Self.pts(1)) == 0)
+
+        // Primary decoder never received the EL packet (it doesn't exist), but BL was fed
+        // Note: primary.decodeCount would be 0 because we bypassed decode(packet:) and called handlers directly
+        // The key assertion is that no enhancement decoder was created/engaged.
+    }
+
+    // MARK: - HardwareVideoDecoder.CustomBlockSource Lifecycle
+
+    @Test("CustomBlockSource holds av_buffer_ref and unrefs idempotently")
+    func customBlockSourceLifecycle() throws {
+        guard let buf = av_buffer_alloc(256) else {
+            Issue.record("Failed to allocate AVBuffer")
+            return
+        }
+        var bufRef: UnsafeMutablePointer<AVBufferRef>? = buf
+        defer {
+            if bufRef != nil {
+                av_buffer_unref(&bufRef)
+            }
+        }
+
+        #expect(av_buffer_get_ref_count(buf) == 1)
+
+        do {
+            let source = try #require(HardwareVideoDecoder.CustomBlockSource(buf: buf))
+            #expect(av_buffer_get_ref_count(buf) == 2)
+            #expect(source.dataPtr == UnsafeMutableRawPointer(buf.pointee.data!))
+
+            // Test idempotent releaseBuffer
+            source.releaseBuffer()
+            #expect(av_buffer_get_ref_count(buf) == 1)
+            #expect(source.avBuf == nil)
+
+            // Second releaseBuffer call is a no-op (idempotent, no double-unref)
+            source.releaseBuffer()
+            #expect(av_buffer_get_ref_count(buf) == 1)
+        }
+        // After deinit of source, refcount stays 1 (no double-unref)
+        #expect(av_buffer_get_ref_count(buf) == 1)
+    }
+
+    @Test("CustomBlockSource addresses the packet payload, not buf->data, when they differ (Matroska packets sit at +4)")
+    func customBlockSourceHonoursPacketDataOffset() throws {
+        let buf = try #require(av_buffer_alloc(256))
+        var bufRef: UnsafeMutablePointer<AVBufferRef>? = buf
+        defer { av_buffer_unref(&bufRef) }
+
+        let payload = try #require(buf.pointee.data).advanced(by: 4)
+        let source = try #require(HardwareVideoDecoder.CustomBlockSource(buf: buf, data: payload))
+        #expect(source.dataPtr == UnsafeMutableRawPointer(payload))
+        #expect(source.dataPtr != UnsafeMutableRawPointer(buf.pointee.data!))
+        source.releaseBuffer()
+    }
+
+    @Test("CMBlockBuffer with CustomBlockSource holds av_buffer_ref and unrefs on deallocation")
+    func cmBlockBufferWithCustomBlockSourceLifecycle() throws {
+        guard let buf = av_buffer_alloc(512) else {
+            Issue.record("Failed to allocate AVBuffer")
+            return
+        }
+        var bufRef: UnsafeMutablePointer<AVBufferRef>? = buf
+        defer {
+            if bufRef != nil {
+                av_buffer_unref(&bufRef)
+            }
+        }
+
+        #expect(av_buffer_get_ref_count(buf) == 1)
+
+        do {
+            let size = 512
+            let blockSource = try #require(HardwareVideoDecoder.CustomBlockSource(buf: buf))
+            let (blockBuffer, status) = HardwareVideoDecoder.makeBlockBuffer(wrapping: blockSource, size: size)
+            #expect(status == kCMBlockBufferNoErr)
+            #expect(blockBuffer != nil)
+            // Block buffer holds av_buffer_ref
+            #expect(av_buffer_get_ref_count(buf) == 2)
+
+            // Verify memory block pointer is accessible and matches buf data
+            var lengthAtOffset = 0
+            var totalLength = 0
+            var dataPointer: UnsafeMutablePointer<CChar>?
+            let accessStatus = CMBlockBufferGetDataPointer(
+                blockBuffer!,
+                atOffset: 0,
+                lengthAtOffsetOut: &lengthAtOffset,
+                totalLengthOut: &totalLength,
+                dataPointerOut: &dataPointer
+            )
+            #expect(accessStatus == kCMBlockBufferNoErr)
+            #expect(totalLength == size)
+            #expect(dataPointer == UnsafeMutablePointer<CChar>(OpaquePointer(buf.pointee.data)))
+        }
+
+        // CMBlockBuffer went out of scope: FreeBlock ran takeRetainedValue and unref'd avBuf
+        #expect(av_buffer_get_ref_count(buf) == 1)
+    }
+
+    @Test("CustomBlockSource cleanup on CMBlockBuffer creation failure balances retain")
+    func customBlockSourceCleanupOnCreationFailure() throws {
+        guard let buf = av_buffer_alloc(256) else {
+            Issue.record("Failed to allocate AVBuffer")
+            return
+        }
+        var bufRef: UnsafeMutablePointer<AVBufferRef>? = buf
+        defer {
+            if bufRef != nil {
+                av_buffer_unref(&bufRef)
+            }
+        }
+
+        #expect(av_buffer_get_ref_count(buf) == 1)
+
+        let blockSource = try #require(HardwareVideoDecoder.CustomBlockSource(buf: buf))
+        // A payload longer than the block is refused by CoreMedia, which is the failure the decoder's
+        // own wrapper has to clean up after.
+        let (blockBuffer, status) = HardwareVideoDecoder.makeBlockBuffer(wrapping: blockSource, size: 256, dataLength: 512)
+        #expect(status != kCMBlockBufferNoErr)
+        #expect(blockBuffer == nil)
+
+        // Retain count of AVBuffer drops back to 1 and blockSource is deallocated without leaking
+        #expect(av_buffer_get_ref_count(buf) == 1)
+    }
+
+    // MARK: - HardwareVideoDecoder.decode with CustomBlockSource vs Fallback Copy
+
+    private static let hevcVPS: [UInt8] = [
+        0x40, 0x01, 0x0c, 0x01, 0xff, 0xff, 0x02, 0x20, 0x00, 0x00, 0x03, 0x00,
+        0x90, 0x00, 0x00, 0x03, 0x00, 0x00, 0x03, 0x00, 0x78, 0x95, 0x94, 0x09
+    ]
+    private static let hevcSPS: [UInt8] = [
+        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, 0xd9, 0x65, 0x65, 0x4a, 0x4c, 0x2f, 0x01, 0x6a, 0x12, 0x20, 0x12,
+        0x08, 0x00, 0x00, 0x03, 0x00, 0x08, 0x00, 0x00, 0x03, 0x00, 0xc0, 0x40
+    ]
+    private static let hevcPPS: [UInt8] = [
+        0x44, 0x01, 0xc0, 0x73, 0xc1, 0x89
+    ]
+
+    @Test("CustomBlockSource failable initializer returns nil if data is nil")
+    func customBlockSourceFailableInit() throws {
+        guard let buf = av_buffer_alloc(64) else {
+            Issue.record("Failed to allocate AVBuffer")
+            return
+        }
+        var bufRef: UnsafeMutablePointer<AVBufferRef>? = buf
+        defer {
+            if bufRef != nil {
+                av_buffer_unref(&bufRef)
+            }
+        }
+
+        #expect(av_buffer_get_ref_count(buf) == 1)
+
+        // Valid buffer succeeds
+        let validSource = HardwareVideoDecoder.CustomBlockSource(buf: buf)
+        #expect(validSource != nil)
+        validSource?.releaseBuffer()
+        #expect(av_buffer_get_ref_count(buf) == 1)
+
+        // Buffer with nil data returns nil without leaking av_buffer_ref
+        let originalData = buf.pointee.data
+        buf.pointee.data = nil
+        let nilSource = HardwareVideoDecoder.CustomBlockSource(buf: buf)
+        #expect(nilSource == nil)
+        #expect(av_buffer_get_ref_count(buf) == 1)
+        buf.pointee.data = originalData
+    }
+
+    @Test("HardwareVideoDecoder.decode with useCustomBlockSource holds av_buffer_ref and decrements on release")
+    func hardwareVideoDecoderHoldsAndDecrementsBufferRef() throws {
+        let decoder = HardwareVideoDecoder()
+        do {
+            try decoder.open(
+                parameterSets: [Self.hevcVPS, Self.hevcSPS, Self.hevcPPS],
+                timeBase: AVRational(num: 1, den: 90000),
+                onFrame: { _, _, _ in }
+            )
+        } catch {
+            // Hardware HEVC decompression session might not be supported in some environments:
+            // reported as skipped, not passed.
+            try Test.cancel("hardware HEVC session creation failed: \(error)")
+        }
+        defer { decoder.close() }
+
+        decoder.useCustomBlockSource = true
+
+        guard let avBuf = av_buffer_alloc(64) else {
+            Issue.record("Failed to allocate AVBuffer")
+            return
+        }
+        var avBufRef: UnsafeMutablePointer<AVBufferRef>? = avBuf
+        defer {
+            if avBufRef != nil {
+                av_buffer_unref(&avBufRef)
+            }
+        }
+
+        // Initialize with a 4-byte length-prefixed NAL (SEI prefix)
+        let dataPtr = avBuf.pointee.data!
+        dataPtr[0] = 0; dataPtr[1] = 0; dataPtr[2] = 0; dataPtr[3] = 60
+        dataPtr[4] = 0x4E; dataPtr[5] = 0x01
+        for i in 6..<64 { dataPtr[i] = 0x80 }
+
+        #expect(av_buffer_get_ref_count(avBuf) == 1)
+
+        guard let packet = trackedPacketAlloc() else {
+            Issue.record("Failed to allocate AVPacket")
+            return
+        }
+        defer {
+            var p: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&p)
+        }
+        packet.pointee.buf = av_buffer_ref(avBuf)
+        packet.pointee.data = avBuf.pointee.data
+        packet.pointee.size = 64
+        packet.pointee.pts = 0
+        packet.pointee.dts = 0
+
+        #expect(av_buffer_get_ref_count(avBuf) == 2)
+
+        var refCountWhileHeld = 0
+        var heldBlockBuffer: CMBlockBuffer?
+        decoder.onBlockBufferAllocatedForTesting = { bb in
+            refCountWhileHeld = Int(av_buffer_get_ref_count(avBuf))
+            heldBlockBuffer = bb
+        }
+
+        decoder.decode(packet: packet)
+
+        // CustomBlockSource took an av_buffer_ref when wrapping into CMBlockBuffer
+        #expect(refCountWhileHeld >= 3)
+        #expect(heldBlockBuffer != nil)
+
+        // Release caller's packet reference
+        av_buffer_unref(&packet.pointee.buf)
+        // Still held by avBufRef and heldBlockBuffer's CustomBlockSource
+        #expect(av_buffer_get_ref_count(avBuf) == 2)
+
+        // Releasing the block buffer decrements the ref count back to 1
+        heldBlockBuffer = nil
+        #expect(av_buffer_get_ref_count(avBuf) == 1)
+
+        // Flush and close decoder to release asynchronous frames and invalidate session
+        decoder.flush()
+        decoder.close()
+
+        #expect(av_buffer_get_ref_count(avBuf) == 1)
+    }
+
+    @Test("HardwareVideoDecoder.decode falls back cleanly to copy when buf == nil")
+    func hardwareVideoDecoderFallsBackToCopyWhenBufNil() throws {
+        let decoder = HardwareVideoDecoder()
+        do {
+            try decoder.open(
+                parameterSets: [Self.hevcVPS, Self.hevcSPS, Self.hevcPPS],
+                timeBase: AVRational(num: 1, den: 90000),
+                onFrame: { _, _, _ in }
+            )
+        } catch {
+            try Test.cancel("hardware HEVC session creation failed: \(error)")
+        }
+        defer { decoder.close() }
+
+        decoder.useCustomBlockSource = true
+
+        let rawData = UnsafeMutablePointer<UInt8>.allocate(capacity: 64)
+        defer { rawData.deallocate() }
+        rawData.initialize(repeating: 0x80, count: 64)
+        rawData[0] = 0; rawData[1] = 0; rawData[2] = 0; rawData[3] = 60
+        rawData[4] = 0x4E; rawData[5] = 0x01
+
+        guard let packet = trackedPacketAlloc() else {
+            Issue.record("Failed to allocate AVPacket")
+            return
+        }
+        defer {
+            var p: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&p)
+        }
+        packet.pointee.buf = nil // Force fallback to copy path
+        packet.pointee.data = rawData
+        packet.pointee.size = 64
+        packet.pointee.pts = 0
+        packet.pointee.dts = 0
+
+        // Must decode without crashing or throwing
+        decoder.decode(packet: packet)
+
+        decoder.flush()
+        decoder.close()
+    }
+
+    // MARK: - DualLayerVideoDecoder Untouched Packet Delivery
+
+    private static func makeAvccPacket(_ nals: [[UInt8]], pts: Int64 = 0) -> UnsafeMutablePointer<AVPacket>? {
+        var total = 0
+        for nal in nals { total += 4 + nal.count }
+        guard let avBuf = av_buffer_alloc(total + Int(AV_INPUT_BUFFER_PADDING_SIZE)) else { return nil }
+        guard let dst = avBuf.pointee.data else {
+            var b: UnsafeMutablePointer<AVBufferRef>? = avBuf
+            av_buffer_unref(&b)
+            return nil
+        }
+        var w = 0
+        for nal in nals {
+            let n = nal.count
+            dst[w + 0] = UInt8((n >> 24) & 0xFF)
+            dst[w + 1] = UInt8((n >> 16) & 0xFF)
+            dst[w + 2] = UInt8((n >> 8) & 0xFF)
+            dst[w + 3] = UInt8(n & 0xFF)
+            w += 4
+            nal.withUnsafeBytes { raw in
+                if let base = raw.baseAddress {
+                    memcpy(dst + w, base, n)
+                }
+            }
+            w += n
+        }
+        memset(dst + total, 0, Int(AV_INPUT_BUFFER_PADDING_SIZE))
+        guard let pkt = trackedPacketAlloc() else {
+            var b: UnsafeMutablePointer<AVBufferRef>? = avBuf
+            av_buffer_unref(&b)
+            return nil
+        }
+        pkt.pointee.buf = avBuf
+        pkt.pointee.data = dst
+        pkt.pointee.size = Int32(total)
+        pkt.pointee.pts = pts
+        pkt.pointee.dts = pts
+        return pkt
+    }
+
+    private static func hevcNAL(type: UInt8, payload: [UInt8]) -> [UInt8] {
+        [UInt8(type << 1), 0x01] + payload
+    }
+
+    private static func hexToBytes(_ hex: String) -> [UInt8] {
+        var bytes: [UInt8] = []
+        var i = hex.startIndex
+        while i < hex.endIndex {
+            let next = hex.index(i, offsetBy: 2)
+            if let byte = UInt8(hex[i..<next], radix: 16) {
+                bytes.append(byte)
+            }
+            i = next
+        }
+        return bytes
+    }
+
+    private static func makeMelRpuBytes() -> [UInt8] {
+        let felBytes = Self.hexToBytes(DoviFelMathTests.clipARpuHex)
+        guard let rpu = dovi_parse_unspec62_nalu(felBytes, felBytes.count) else { return [] }
+        defer { dovi_rpu_free(rpu) }
+        // libdovi returns a handle even when parsing fails; an error means there is nothing to convert.
+        guard dovi_rpu_get_error(rpu) == nil else { return [] }
+        _ = dovi_convert_rpu_with_mode(rpu, 1)
+        guard let out = dovi_write_unspec62_nalu(rpu) else { return [] }
+        defer { dovi_data_free(out) }
+        return [UInt8](UnsafeBufferPointer(start: out.pointee.data, count: out.pointee.len))
+    }
+
+    @Test("DualLayerVideoDecoder leaves FEL packet untouched and extracts EL and RPU")
+    func dualLayerVideoDecoderLeavesFELPacketUntouched() throws {
+        let primary = CountingFakeDecoder()
+        let enhancement = CountingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        defer { decoder.close() }
+
+        let vps = Self.hevcNAL(type: 32, payload: [0x0c, 0x01, 0xff, 0xff])
+        let sps = Self.hevcNAL(type: 33, payload: [0x01, 0x02, 0x20, 0x00])
+        let pps = Self.hevcNAL(type: 34, payload: [0xc0, 0x73])
+        let bl = Self.hevcNAL(type: 1, payload: [0x11, 0x22, 0x33, 0x44])
+        let rpu = Self.hexToBytes(DoviFelMathTests.clipARpuHex)
+        let el = Self.hevcNAL(type: 63, payload: [0x55, 0x66, 0x77, 0x88])
+
+        guard let pkt = Self.makeAvccPacket([vps, sps, pps, bl, rpu, el], pts: 1000) else {
+            Issue.record("Failed to build AVCC packet")
+            return
+        }
+        defer {
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+
+        let originalData = pkt.pointee.data
+        let originalSize = pkt.pointee.size
+        let originalBuf = pkt.pointee.buf
+
+        decoder.decode(packet: pkt)
+
+        // Packet pointer, size, and buffer must be COMPLETELY UNTOUCHED
+        #expect(pkt.pointee.data == originalData)
+        #expect(pkt.pointee.size == originalSize)
+        #expect(pkt.pointee.buf == originalBuf)
+
+        // Classified as FEL
+        #expect(decoder.streamClassificationForTesting == .fel)
+
+        // Primary received the base layer
+        #expect(primary.decodeCount == 1)
+
+        // Enhancement decoder was engaged and received the extracted EL packet
+        #expect(enhancement.decodeCount == 1)
+
+        // Display metadata RPU was extracted and cached
+        #expect(decoder.stateSnapshotForTesting.dmRpuCacheCount == 1)
+        // RPU params were extracted and cached
+        #expect(decoder.stateSnapshotForTesting.rpuCacheCount == 1)
+    }
+
+    @Test("DualLayerVideoDecoder leaves MEL packet untouched and extracts RPU without engaging EL decoder")
+    func dualLayerVideoDecoderLeavesMELPacketUntouched() throws {
+        let primary = CountingFakeDecoder()
+        let enhancement = CountingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        defer { decoder.close() }
+
+        let vps = Self.hevcNAL(type: 32, payload: [0x0c, 0x01, 0xff, 0xff])
+        let sps = Self.hevcNAL(type: 33, payload: [0x01, 0x02, 0x20, 0x00])
+        let pps = Self.hevcNAL(type: 34, payload: [0xc0, 0x73])
+        let bl = Self.hevcNAL(type: 1, payload: [0x11, 0x22, 0x33, 0x44])
+        let melRpu = Self.makeMelRpuBytes()
+        #expect(!melRpu.isEmpty)
+        let el = Self.hevcNAL(type: 63, payload: [0x55, 0x66])
+
+        guard let pkt = Self.makeAvccPacket([vps, sps, pps, bl, melRpu, el], pts: 2000) else {
+            Issue.record("Failed to build AVCC packet")
+            return
+        }
+        defer {
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+
+        let originalData = pkt.pointee.data
+        let originalSize = pkt.pointee.size
+        let originalBuf = pkt.pointee.buf
+
+        decoder.decode(packet: pkt)
+
+        // Base-layer packet pointer, size, and buffer must be COMPLETELY UNTOUCHED
+        #expect(pkt.pointee.data == originalData)
+        #expect(pkt.pointee.size == originalSize)
+        #expect(pkt.pointee.buf == originalBuf)
+
+        // Classified as MEL
+        #expect(decoder.streamClassificationForTesting == .mel)
+
+        // Primary received the base layer
+        #expect(primary.decodeCount == 1)
+
+        // Enhancement decoder was NOT engaged for MEL
+        #expect(enhancement.decodeCount == 0)
+
+        // Display metadata RPU was extracted and cached
+        #expect(decoder.stateSnapshotForTesting.dmRpuCacheCount == 1)
+    }
+
+    // MARK: - Per-Frame Logging & 1 Hz Summary
+
+    @Test("per-frame logs (QUEUE, Bypass, DROP) are NOT emitted at default info level")
+    func fel14PerFrameLogsNotEmittedAtDefaultInfoLevel() throws {
+        let prevHandler = EngineLog.handler
+        defer { EngineLog.handler = prevHandler }
+
+        var emittedLines: [String] = []
+        let logLock = NSLock()
+        EngineLog.handler = { line in
+            logLock.lock()
+            emittedLines.append(line)
+            logLock.unlock()
+        }
+
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        defer { decoder.close() }
+
+        // Send a base-layer frame with no EL / no RPU (will bypass)
+        let buf1 = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: buf1, pts: Self.pts(1), hdr10Data: nil)
+
+        // Simulate FEL stream with EL decoder active:
+        decoder.primeForTesting(enhancementLayer: true)
+
+        // Send unmatched BL (will queue BL)
+        let buf2 = try #require(Self.baseLayer())
+        decoder.handleBaseLayerFrame(baseBuffer: buf2, pts: Self.pts(2), hdr10Data: nil)
+
+        // Send unmatched EL (will queue EL)
+        let buf3 = try #require(Self.enhancementLayer())
+        decoder.handleEnhancementLayerFrame(elBuffer: buf3, pts: Self.pts(3))
+
+        logLock.lock()
+        let captured = emittedLines
+        logLock.unlock()
+
+        let forbiddenPrefixes = [
+            "[DualLayer] QUEUE BL",
+            "[DualLayer] QUEUE EL",
+            "[DualLayer] Bypass:",
+            "[DualLayer] DROP stale EL",
+            "[DualLayer] PRUNED EL",
+            "[DualLayer] BYPASS no-EL"
+        ]
+        for prefix in forbiddenPrefixes {
+            let found = captured.filter { $0.contains(prefix) }
+            #expect(found.isEmpty, "Found forbidden per-frame log at info level: \(found)")
+        }
+    }
+
+    @Test("1 Hz summary aggregates and emits expected fields, then resets interval")
+    func fel14OneHzSummaryAggregationAndFormat() throws {
+        let prevHandler = EngineLog.handler
+        defer { EngineLog.handler = prevHandler }
+
+        var summaryLines: [String] = []
+        let logLock = NSLock()
+        EngineLog.handler = { line in
+            if line.contains("[DualLayer] summary:") {
+                logLock.lock()
+                summaryLines.append(line)
+                logLock.unlock()
+            }
+        }
+
+        let composer = ImmediateFakeComposer()
+        let decoder = DualLayerVideoDecoder(composer: composer)
+        defer { decoder.close() }
+
+        var currentTime: TimeInterval = 10.0
+        decoder.summaryTimestampProviderForTesting = { currentTime }
+
+        decoder.primeForTesting(enhancementLayer: true)
+
+        let baseBuf = try #require(Self.baseLayer())
+        let elBuf = try #require(Self.enhancementLayer())
+
+        // Inject cached RPU and pair a frame at t = 10.0
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+
+        // Base layer arrives at t = 10.0: sets lastSummaryTimestamp = 10.0
+        decoder.handleBaseLayerFrame(baseBuffer: baseBuf, pts: Self.pts(1), hdr10Data: nil)
+
+        // Enhancement layer arrives at t = 10.0: pairs and composes
+        decoder.handleEnhancementLayerFrame(elBuffer: elBuf, pts: Self.pts(1))
+
+        // Advance by 0.5s to 10.5: interval (1.0s) has not elapsed yet
+        currentTime = 10.5
+        decoder.maybeEmitSummary()
+        logLock.lock()
+        #expect(summaryLines.isEmpty)
+        logLock.unlock()
+
+        // Advance by 1.1s to 11.1 (currentTime >= 10.0 + 1.0): summary emits!
+        currentTime = 11.1
+        decoder.maybeEmitSummary()
+        logLock.lock()
+        #expect(summaryLines.count == 1)
+        let summary = summaryLines.first ?? ""
+        logLock.unlock()
+
+        #expect(summary.contains("[DualLayer] summary:"))
+        #expect(summary.contains("composed=1"))
+        #expect(summary.contains("bypassNoEL=0"))
+        #expect(summary.contains("bypassNoRPU=0"))
+        #expect(summary.contains("staleELDropped=0"))
+        #expect(summary.contains("peakGpuSlots="))
+        #expect(summary.contains("poolBuffers="))
+        #expect(summary.contains("deliveryPendingPeak="))
+        #expect(summary.contains("meanGpuMs="))
+
+        // Next call immediately at 11.2 does not emit again until another second passes
+        currentTime = 11.2
+        decoder.maybeEmitSummary()
+        logLock.lock()
+        #expect(summaryLines.count == 1)
+        logLock.unlock()
+
+        // After another 1.0s at 12.2, emits interval 2 with composed=0
+        currentTime = 12.2
+        decoder.maybeEmitSummary()
+        logLock.lock()
+        #expect(summaryLines.count == 2)
+        let summary2 = summaryLines.last ?? ""
+        logLock.unlock()
+        #expect(summary2.contains("composed=0"))
+    }
+
+    @Test("flush and close reset 1 Hz summary counters")
+    func fel14FlushAndCloseResetSummaryCounters() throws {
+        let prevHandler = EngineLog.handler
+        defer { EngineLog.handler = prevHandler }
+
+        var summaryLines: [String] = []
+        let logLock = NSLock()
+        EngineLog.handler = { line in
+            if line.contains("[DualLayer] summary:") {
+                logLock.lock()
+                summaryLines.append(line)
+                logLock.unlock()
+            }
+        }
+
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        defer { decoder.close() }
+
+        var currentTime: TimeInterval = 20.0
+        decoder.summaryTimestampProviderForTesting = { currentTime }
+        decoder.primeForTesting(enhancementLayer: true)
+
+        let baseBuf = try #require(Self.baseLayer())
+        let elBuf = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleBaseLayerFrame(baseBuffer: baseBuf, pts: Self.pts(1), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: elBuf, pts: Self.pts(1))
+
+        // Flush resets counters and timestamp
+        decoder.flush()
+
+        // Advance time to 21.5 and call maybeEmitSummary: since flush reset lastSummaryTimestamp to 0,
+        // this call merely records the new baseline and does NOT emit
+        currentTime = 21.5
+        decoder.maybeEmitSummary()
+
+        logLock.lock()
+        #expect(summaryLines.isEmpty)
+        logLock.unlock()
+
+        // Advance by 1.1s to 22.6: summary emits with 0 composed frames
+        currentTime = 22.6
+        decoder.maybeEmitSummary()
+
+        logLock.lock()
+        #expect(summaryLines.count == 1)
+        let summary = summaryLines.first ?? ""
+        logLock.unlock()
+        #expect(summary.contains("composed=0"))
+    }
+
+    // MARK: - Memory Limits & Queue Bounds
+
+    @Test("output pool enforces its allocation threshold")
+    func fel18OutputPoolEnforcesAllocationThreshold() throws {
+        guard let composer = DoviFelComposer() else {
+            Issue.record("Failed to create DoviFelComposer")
+            return
+        }
+        guard let pool = composer.ensurePoolForTesting(width: 256, height: 256) else {
+            Issue.record("Failed to create pixel buffer pool")
+            return
+        }
+
+        var heldBuffers: [CVPixelBuffer] = []
+        // Allocate up to the threshold
+        for _ in 0..<DoviFelComposer.outputPoolAllocationThreshold {
+            let res = composer.createOutputBufferForTesting(pool: pool)
+            #expect(res.status == kCVReturnSuccess)
+            if let buf = res.buffer { heldBuffers.append(buf) }
+        }
+        #expect(heldBuffers.count == DoviFelComposer.outputPoolAllocationThreshold)
+
+        // 6th allocation exceeds the allocation threshold
+        let excessRes = composer.createOutputBufferForTesting(pool: pool)
+        #expect(excessRes.status == kCVReturnWouldExceedAllocationThreshold)
+        #expect(excessRes.buffer == nil)
+
+        // Release one buffer back to the pool
+        heldBuffers.removeFirst()
+
+        // Now allocation succeeds again
+        let retryRes = composer.createOutputBufferForTesting(pool: pool)
+        #expect(retryRes.status == kCVReturnSuccess)
+        #expect(retryRes.buffer != nil)
+    }
+
+    @Test("P2: past the threshold the pool grows into a bounded reserve instead of refusing")
+    func outputPoolReserveIsBounded() throws {
+        let composer = try #require(DoviFelComposer())
+        let pool = try #require(composer.ensurePoolForTesting(width: 256, height: 256))
+        var held: [CVPixelBuffer] = []
+        for _ in 0..<DoviFelComposer.outputPoolAllocationThreshold {
+            held.append(try #require(composer.createOutputBufferForTesting(pool: pool).buffer))
+        }
+        #expect(composer.createOutputBufferForTesting(pool: pool).status == kCVReturnWouldExceedAllocationThreshold)
+        for _ in 0..<DoviFelComposer.outputPoolReserve {
+            let res = composer.createOutputBufferForTesting(pool: pool, reserve: true)
+            #expect(res.status == kCVReturnSuccess)
+            if let b = res.buffer { held.append(b) }
+        }
+        #expect(held.count == DoviFelComposer.outputPoolAllocationThreshold + DoviFelComposer.outputPoolReserve)
+        // The reserve is a hard limit too.
+        #expect(composer.createOutputBufferForTesting(pool: pool, reserve: true).status == kCVReturnWouldExceedAllocationThreshold)
+        // Once the burst drains, the pool hands the buffers back out without allocating.
+        held.removeLast(DoviFelComposer.outputPoolReserve + 1)
+        #expect(composer.createOutputBufferForTesting(pool: pool).status == kCVReturnSuccess)
+    }
+
+    @Test("a seek flush keeps the output pool, so buffers the renderer still holds count against the same threshold")
+    func flushKeepsOutputPool() throws {
+        let composer = try #require(DoviFelComposer())
+        let pool = try #require(composer.ensurePoolForTesting(width: 256, height: 256))
+        var held: [CVPixelBuffer] = []
+        for _ in 0..<DoviFelComposer.outputPoolAllocationThreshold {
+            held.append(try #require(composer.createOutputBufferForTesting(pool: pool).buffer))
+        }
+        composer.flush()
+        // Same pool object: a replacement would hand out a second threshold's worth on top of `held`,
+        // the transient footprint doubling a seek used to cost.
+        let after = try #require(composer.ensurePoolForTesting(width: 256, height: 256))
+        #expect(after === pool)
+        #expect(composer.createOutputBufferForTesting(pool: after).status == kCVReturnWouldExceedAllocationThreshold)
+        held.removeFirst()
+        #expect(composer.createOutputBufferForTesting(pool: after).status == kCVReturnSuccess)
+        // Teardown does drop it, and no pool is built after it.
+        composer.releaseOutputPool()
+        #expect(composer.ensurePoolForTesting(width: 256, height: 256) == nil)
+    }
+
+    @Test("base-layer and enhancement-layer queues are strictly bounded at their own caps")
+    func fel18QueuesBoundedAtK() throws {
+        let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
+        defer { decoder.close() }
+
+        decoder.primeForTesting(enhancementLayer: true)
+
+        // Feed 6 consecutive base-layer frames without any EL
+        for i in 1...6 {
+            let bl = try #require(Self.baseLayer())
+            decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+            // blFrameQueue count must never exceed maxLayerSkewFrames (3)
+            #expect(decoder.stateSnapshotForTesting.blQueueCount <= DualLayerVideoDecoder.maxLayerSkewFrames)
+        }
+
+        // Feed more enhancement-layer frames than their cap without any BL
+        for i in 10..<(10 + DualLayerVideoDecoder.maxEnhancementLayerQueueFrames + 3) {
+            let el = try #require(Self.enhancementLayer())
+            decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            // elFrameQueue count must never exceed its own cap (10)
+            #expect(decoder.stateSnapshotForTesting.elQueueCount <= DualLayerVideoDecoder.maxEnhancementLayerQueueFrames)
+        }
+    }
+
+    // MARK: - Stream Classification & Packet Balance Tracking
+
+    @Test("DualLayerVideoDecoder reports streamClassification accurately and balances packets")
+    func fel22StreamClassificationAndPacketBalance() throws {
+        let aliveBefore = PacketBalanceTracker.alive
+
+        let primary = CountingFakeDecoder()
+        let enhancement = CountingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        defer { decoder.close() }
+
+        #expect(decoder.streamClassification == .undetermined)
+
+        // Feed a MEL packet
+        let vps = Self.hevcNAL(type: 32, payload: [0x0c, 0x01, 0xff, 0xff])
+        let sps = Self.hevcNAL(type: 33, payload: [0x01, 0x02, 0x20, 0x00])
+        let pps = Self.hevcNAL(type: 34, payload: [0xc0, 0x73])
+        let bl = Self.hevcNAL(type: 1, payload: [0x11, 0x22, 0x33, 0x44])
+        let melRpu = Self.makeMelRpuBytes()
+
+        guard let melPkt = Self.makeAvccPacket([vps, sps, pps, bl, melRpu], pts: 1000) else {
+            Issue.record("Failed to make MEL packet")
+            return
+        }
+
+        decoder.decode(packet: melPkt)
+
+        var optMel: UnsafeMutablePointer<AVPacket>? = melPkt
+        trackedPacketFree(&optMel)
+
+        // Classification must be MEL, not FEL
+        #expect(decoder.streamClassification == .mel)
+
+        // PacketBalanceTracker must return to baseline
+        #expect(PacketBalanceTracker.alive == aliveBefore)
+    }
+}
diff --git a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
index ac6bf6a8e..f2f3ae95f 100644
--- a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
+++ b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
@@ -203,6 +203,39 @@ struct SubtitleFrameCompositorTests {
         }
     }
 
+    /// The Profile 7 FEL route hands the renderer composed P010 frames carrying the Dolby Vision RPU
+    /// and compatibility ID. In PiP with a cue up, the frame the layer receives is the compositor's
+    /// copy: it has to carry the source frame's attachments (the CFString "1" among them, which the
+    /// render server parses with `CFStringGetIntValue`) and must not inherit a previous frame's RPU
+    /// from the recycled pool buffer, which is the stale-trims failure the design doc describes.
+    @Test("a composited Dolby Vision frame carries its own RPU attachments and a recycled buffer drops stale ones")
+    func compositedFrameCarriesDolbyVisionAttachments() throws {
+        let compositor = SubtitleFrameCompositor()
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true, delaySeconds: 0)
+        let format = kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange
+
+        let rpuNAL: [UInt8] = [0x7C, 0x01, 0x19, 0x08, 0x42, 0xA5, 0x80]
+        let dv = try blackFrame(format)
+        DoviDisplayMetadata.attach(rpuNAL: rpuNAL, to: dv)
+        let sourcePayload = try #require(attachment(dv, DoviDisplayMetadata.rpuDataKey as CFString) as? Data)
+
+        // Several rounds, so the pool hands out a buffer that already held an RPU.
+        for _ in 0..<4 {
+            let out = compositor.composite(dv, ptsSeconds: 5)
+            #expect(out !== dv)
+            #expect(attachment(out, DoviDisplayMetadata.rpuDataKey as CFString) as? Data == sourcePayload)
+            #expect(attachment(out, DoviDisplayMetadata.compatibilityIDKey as CFString) as? String == "1")
+        }
+
+        // A frame with no RPU (a bypass without display metadata) must not pick one up.
+        let plain = try blackFrame(format)
+        for _ in 0..<4 {
+            let out = compositor.composite(plain, ptsSeconds: 5)
+            #expect(attachment(out, DoviDisplayMetadata.rpuDataKey as CFString) == nil)
+            #expect(attachment(out, DoviDisplayMetadata.compatibilityIDKey as CFString) == nil)
+        }
+    }
+
     @Test("an untagged source renders through BT.709")
     func untaggedSourceFallsBackTo709() throws {
         let space = SubtitleFrameCompositor.renderColorSpace(for: try blackFrame(kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange))
diff --git a/docs/architecture.md b/docs/architecture.md
index 3746316d2..297cfe309 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -414,6 +414,7 @@ Sources/AetherEngine/
 │   ├── InterlaceProbe.swift                 Decodes a sample and applies the deinterlacer's own engagement predicate, so a declared field order that no frame backs up (PsF) stops costing a SW decode (#232)
 │   ├── VideoRoutingPolicy.swift             Pure codec-and-field-order dispatch rule: AV1 gated on HW, VP9/VP8/MPEG4/MPEG2/VC1 always SW, interlaced H.264 SW so bwdif can deinterlace (#107, verified against decoded frames on VOD, #232), plus a second-stage gate routing H.264 High 4:2:2/4:4:4/10 + HEVC Rext to SW where VideoToolbox has no HW decoder (#2)
 │   ├── HardwareVideoDecoder.swift           SW path: VideoToolbox HW HEVC / AV1 decoder for sources routed away from AVPlayer
+│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL. Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame; see [dolby-vision-fel.md](dolby-vision-fel.md)
 │   ├── SoftwareVideoDecoder.swift           SW path: libavcodec/dav1d → CVPixelBuffer (NV12 / P010), HDR10+ side data
 │   ├── SubtitleDecoder.swift                Sidecar URL one-shot decode (text only); decodes several streams of one container in a single pass (#266)
 │   ├── VideoDecoderTypes.swift              DecodedFrameHandler typealias + VideoDecoderError

From f31b67c61e7528e76791535e68cc4044cf2f7976 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:36:42 +0100
Subject: [PATCH 015/132] feat(dovi): route Profile 7 FEL to the dual-layer
 decoder behind preferDualLayerDolbyVision

Host wiring for the composer and decoder. LoadOptions.preferDualLayerDolbyVision
(default false) makes a Profile 7 FEL file play through SoftwarePlaybackHost
and DualLayerVideoDecoder when the box can afford it; otherwise the existing
Profile 8.1 conversion is untouched. With the flag off no source plays
differently.

- DualLayerRouteDecision: a pure capability gate. The route is taken only
  for FEL, with a proven hardware HEVC session, a seekable VOD,
  dolbyVisionHandling .automatic and a stream inside the real-time budget
  ((3840x2160 + 1920x1080) x 30 = 311.04 Mpx/s; a 24p UHD FEL with a
  quarter-area EL needs 80%; an unknown frame rate is budgeted as 24). Every
  Profile 7 load logs exactly one `DV P7 dual-layer route: taken|not taken
  (<reason>)` line. It fails closed: when the base-layer size is unknown the
  budget cannot be evaluated, so the route is refused rather than assumed.
  The budget is an assumption until the Apple TV run confirms it.
- Wiring in AetherEngine, SoftwarePlaybackHost, VideoRoutingPolicy,
  CodecRoutePolicy and the reload path (preferDualLayerDolbyVision is a
  tuning field, correctable through reloadAtCurrentPosition(applying:)).
  An `hev1` source with in-band parameter sets (an empty hvcC) is completed
  from the head of the stream so it can be classified and take the route,
  the same rebuild the native path already does for its init.mp4.
- Audio trade-off, documented in LoadOptions, api.md and
  dolby-vision-fel.md and pinned by DualLayerRouteAudioTests: the route runs
  on the software host, whose audio FFmpeg decodes and the sample-buffer
  audio renderer plays, and on tvOS only AVPlayer emits Atmos objects. An
  E-AC-3 (JOC) track therefore plays as its 5.1 / 7.1 channel-bed core,
  without the objects, where the native route would hand it to AVPlayer
  unchanged. Not engineered around.
- Docs: dolby-vision-fel.md (the design), api.md, formats.md, README, and
  the DocumentedConstantsTests pins that tie the document's numbers to the
  code (route budget, pipeline bounds, picture-order pairing bound). The
  document arrives here, whole; code comments in the earlier PRs cite its
  section numbers.

Mac soak, measured BEFORE the output-pool fix of the decoder PR (peaks are
pre-fix; with it 12 seeks peak at 500 MB instead of 674 MB), M2 Pro, debug
aetherctl, --window:

| Run | Route | Composed / failures | Seeks landed | Drops | Steady | Peak |
|---|---|---|---|---|---|---|
| 217 s, 12 seeks | taken, budget 80% | 6143 / 0 | 15 | 6 / 6206 | 328-331 MB | 674 MB |
| 120 s, 11 seeks | taken | 4248 / 0 | 12 | 7 / 4275 | 282 MB | 600 MB |
| pause + seek while paused | taken | 2005 / 0 | 1 | 1 / 1949 | 330 MB | 352 MB |

Apple TV results: pending, nothing measured on device yet.

Tests: DualLayerRouteDecisionTests (one per exit), VideoRoutingPolicyTests,
SoftwareDecoderSelectionTests, InBandParameterSetRebuildTests,
DualLayerEdgeCaseTests, DualLayerRouteAudioTests, LoadOptionsTests,
DocumentedConstantsTests. Not in this PR: the pulse probe and the aetherctl
tooling.
---
 CHANGELOG.md                                  |   7 +
 README.md                                     |   6 +-
 .../AetherEngine/AetherEngine+Loading.swift   |  10 +-
 .../AetherEngine+ReloadWithOptions.swift      |  55 +-
 Sources/AetherEngine/AetherEngine.swift       | 100 ++-
 .../Decoder/DualLayerRouteDecision.swift      | 199 ++++++
 .../Decoder/VideoRoutingPolicy.swift          |  39 +-
 .../AetherEngine/Diagnostics/EngineLog.swift  |  12 +-
 .../Native/SoftwarePlaybackHost.swift         | 151 +++-
 .../Native/SoftwareReadAdmission.swift        |   5 +
 Sources/AetherEngine/PlayerState.swift        |  40 +-
 .../AetherEngine/Video/CodecRoutePolicy.swift |   6 +-
 .../Video/DolbyVisionRecordAudit.swift        |  39 ++
 .../HLSVideoEngine+SegmentPlanning.swift      |  50 +-
 .../Video/VTCapabilityProbe.swift             |   7 +
 .../Video/VideoConfigRecord+InBand.swift      | 140 ++++
 .../DocumentedConstantsTests.swift            |  64 ++
 .../DualLayerEdgeCaseTests.swift              | 633 +++++++++++++++++
 .../DualLayerRouteAudioTests.swift            |  56 ++
 .../DualLayerRouteDecisionTests.swift         | 213 ++++++
 .../InBandParameterSetRebuildTests.swift      |  56 ++
 .../AetherEngineTests/LoadOptionsTests.swift  |   2 +
 .../SoftwareDecoderSelectionTests.swift       | 172 +++++
 .../VideoRoutingPolicyTests.swift             | 248 +++++++
 docs/api.md                                   |   4 +-
 docs/dolby-vision-fel.md                      | 658 ++++++++++++++++++
 docs/formats.md                               |   6 +-
 27 files changed, 2907 insertions(+), 71 deletions(-)
 create mode 100644 Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
 create mode 100644 Sources/AetherEngine/Video/VideoConfigRecord+InBand.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerRouteAudioTests.swift
 create mode 100644 Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift
 create mode 100644 Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift
 create mode 100644 docs/dolby-vision-fel.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 37b879c40..269c12da4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,9 +12,16 @@ the public-API contract.
 
 ### Added
 
+- **Dolby Vision Profile 7 FEL plays as Dolby Vision on the software path.** Opt-in: with `LoadOptions.preferDualLayerDolbyVision` set to `true` (default `false`) and `dolbyVisionHandling` `.automatic`, `SoftwarePlaybackHost` routes a Profile 7 file whose enhancement layer is FEL through `DualLayerVideoDecoder`: the base layer and the enhancement layer (typically 4K and 1080p) decode on VideoToolbox, `DoviFelComposer` rebuilds the 12-bit picture on Metal, and each frame carries its RPU converted to Profile 8.1 (`DolbyVisionRPUData`, `DolbyCompatibilityID`, the latter a `CFString` `"1"`: tvOS parses it with `CFStringGetIntValue` and a `CFNumber` aborts the render server). A MEL enhancement layer keeps the native route. An `hev1` source whose `hvcC` carries no VPS / SPS / PPS (the usual Dolby Vision MP4 recipes) is classified from the parameter sets at the head of the stream, the rebuild the native path already does for its init.mp4 (#19). What the route gives up against the native one (system Picture in Picture, the I-frame playlist's scrub thumbnails, WebVTT renditions, AirPlay picture) is listed in the document. Details in [docs/dolby-vision-fel.md](docs/dolby-vision-fel.md).
+- **The Profile 7 dual-layer route is FEL only and capability gated, and says why.** `DualLayerRouteDecision` adds a real-time budget to the route: the base and enhancement layers together may need at most UHD 3840x2160 at 30 fps plus a 1920x1080 enhancement layer at 30 fps (a 24p UHD master uses 80%), otherwise the file keeps the native route, as MEL does and as does a box without hardware HEVC decode (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not). Every Profile 7 load logs one `DV P7 dual-layer route: taken (...)` or `not taken (<reason>)` line; the line is new, and with the preference off it is the only change.
 - **`AETHER_FEL_MEASURE` reports the signed FEL-minus-MEL mean per plane and luma band.** The diagnostic composes every Nth frame a second time with the residual off and compares the two; the signed mean says whether the residual brightens or darkens, which the absolute difference could not. It runs one sample at a time and skips a frame that arrives while one is in flight. Off by default; it is an environment-variable diagnostic, not API.
 - **The dual-layer decoder pairs the two layers by picture order.** `DualLayerPictureAlignment` derives each layer's display slot from its POC (`HEVCPictureOrderCount`, no decoding) and stamps each enhancement-layer packet with the time of the base-layer picture in the same slot, so a stream whose enhancement layer is coded with B-frames over a base layer without them pairs the right pictures. A stream whose layers share one GOP keeps every packet's own time. After a seek a layer pairs by access unit until its next sequence-opening IRAP.
 
+### Changed
+
+- **`.verbose` engine log lines cost nothing unless the category's debug level is enabled.** `EngineLog` redacted and handed every `.verbose` line to OSLog even when nobody was reading debug output; it now checks `OSLog.isEnabled(type: .debug)` for the category first and returns early. `.info` lines and the host `handler` are unchanged (verbose lines never reached the handler).
+- **`reloadAtCurrentPosition(applying:)` refuses a `preferDualLayerDolbyVision` change, or a `dolbyVisionHandling` change while the preference is on, on a custom `IOReader` source playing Profile 7**, with the new public case `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, before any teardown. A host that switches over `SessionReloadRefusal` exhaustively has to handle the new case. The in-place rebuild of a custom source keeps the route the session was loaded with, so the change would have been logged as applied and ignored; `load()` again with the new option. URL sources re-run `load()` and are unaffected.
+
 ### Fixed
 
 - **A live GOP longer than the sealed target duration no longer breaks the playlist.** RFC 8216 keeps
diff --git a/README.md b/README.md
index 148284e12..89249b306 100644
--- a/README.md
+++ b/README.md
@@ -65,9 +65,9 @@ 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 Vivid (played on its HLG / PQ base, CUVA metadata reported by `probe`) |
+| HDR | HDR10, HDR10+ (per-frame ST 2094-40), Dolby Vision (P5, P7 on the native route as single-layer 8.1 (HDR10 base layer on a display without Dolby Vision), or composed dual-layer on Metal with per-frame DV metadata for FEL when `preferDualLayerDolbyVision` is set and VideoToolbox decodes HEVC in hardware, 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. TrueHD Atmos keeps its heights too, opt-in through `LoadOptions.objectAudioRendering`: the engine decodes the Atmos objects, renders them into a speaker bed and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio ([details](docs/formats.md#truehd-atmos-with-heights)). DTS:X takes the same route, its heights and objects unfolded from the compatible 7.1 ([details](docs/formats.md#dtsx-with-heights)) |
+| Dolby Atmos | EAC3+JOC stream-copied on every route (HDMI MAT 2.0, AirPods spatial, BT downmix) except the opt-in Profile 7 FEL dual-layer route (`preferDualLayerDolbyVision`), which runs on the software host and plays an E-AC-3 JOC track as its 5.1 / 7.1 bed without the objects. 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. TrueHD Atmos keeps its heights too, opt-in through `LoadOptions.objectAudioRendering`: the engine decodes the Atmos objects, renders them into a speaker bed and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio ([details](docs/formats.md#truehd-atmos-with-heights)). DTS:X takes the same route, its heights and objects unfolded from the compatible 7.1 ([details](docs/formats.md#dtsx-with-heights)) |
 | Surround | 5.1 / 7.1 with correct `AudioChannelLayout` |
 | Audio-only | `LoadOptions.audioOnly`: lean pipeline, no video machinery, system Now-Playing on tvOS / iOS |
 | Background audio | Audio keeps playing when the app backgrounds on iOS: native AVPlayer stays alive, the software path drops video and keeps decoding audio (`backgroundPlaybackEnabled` / `pictureInPictureActive`); a paused session survives quick app switches for a grace window (`backgroundTeardownGraceSeconds`, default 15 s) before the wedge-safe teardown runs. tvOS tears down immediately (wedge-safe) unless a PiP window is active, which keeps the pipeline and loopback server alive; with PiP the software path keeps decoding video too (the window needs frames). Hosts gate corrective actions on the published `isSessionReady` |
@@ -93,7 +93,7 @@ On Apple platforms the real choice is between AVPlayer, with deep OS integration
 | **Approach** | Embeddable engine, Apple-only | Full player with bundled UI, FFmpeg + AVPlayer, Apple-only | Apple's built-in player | libVLC wrapped for Apple | libmpv, cross-platform |
 | **Container & codec breadth** | Wide, FFmpeg demux | Wide, FFmpeg demux | Narrow, Apple's set | Wide | Wide |
 | **Hardware decode** | VideoToolbox, dav1d SW fallback | VideoToolbox, FFmpeg SW fallback | VideoToolbox | VideoToolbox plus software | VideoToolbox plus software |
-| **Dolby Vision** | P5, P7 as 8.1, P8.1, P8.4, AV1 P10.x, real display switch | P5, P8 via AVPlayer; their matrix lists P5 HDR display without overheating as paid LGPL | P5 and P8.1 only | Tone-maps, no DV display | Tone-maps, no DV display |
+| **Dolby Vision** | P5, P7 as 8.1 (or opt-in FEL dual-layer), P8.1, P8.4, AV1 P10.x, real display switch | P5, P8 via AVPlayer; their matrix lists P5 HDR display without overheating as paid LGPL | P5 and P8.1 only | Tone-maps, no DV display | Tone-maps, no DV display |
 | **Dolby Atmos** | EAC3+JOC stream-copied (HDMI MAT, spatial); TrueHD Atmos and DTS:X rendered to APAC, heights kept | EAC3+JOC via AVPlayer | EAC3+JOC passthrough | Decodes to PCM, no object passthrough | No Atmos passthrough on Apple |
 | **HDR on tvOS** | Native Match Content switch | Native Match Content on AVPlayer path, else Metal tone-map | Native Match Content | Software tone-mapping | Software tone-mapping |
 | **Rendering & UI** | OS-native, you ship SwiftUI | Own Metal renderer, bundled controls | OS-native, you ship UI | Own renderer, bundled controls | Own renderer, bundled OSC |
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 077b2ced6..8ba0e2882 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1935,7 +1935,8 @@ extension AetherEngine {
         isLive: Bool = false,
         dvrWindowSeconds: Double? = nil,
         preopenedDemuxer: Demuxer?,
-        generation: UInt64
+        generation: UInt64,
+        elType: String? = nil
     ) async throws {
         let deinterlaceMode = loadedOptions.deinterlaceMode
         let waitStarted = DispatchTime.now()
@@ -1967,6 +1968,10 @@ extension AetherEngine {
         // on every build. Without it a software host came up aspect-fit whatever the app had set,
         // and only a second write mid-session took effect.
         let host = SoftwarePlaybackHost(videoGravity: _videoGravity)
+        host.configuredDVProfile = sourceDVProfile
+        host.dolbyVisionHandling = loadedOptions.dolbyVisionHandling
+        host.preferDualLayerDolbyVision = loadedOptions.preferDualLayerDolbyVision
+        host.elType = elType ?? sourceElType
         host.setAudioDelay(loadedOptions.audioDelaySeconds)   // AE#464: before the decoder opens
         host.deinterlaceConfig = DeinterlaceConfig(
             mode: loadedOptions.deinterlaceMode,
@@ -2556,7 +2561,8 @@ extension AetherEngine {
                     isLive: loadedOptions.isLive,
                     dvrWindowSeconds: loadedOptions.dvrWindowSeconds,
                     preopenedDemuxer: customPreopened,
-                    generation: gen
+                    generation: gen,
+                    elType: sourceElType
                 )
                 EngineLog.emit("[AetherEngine] reload: loadSoftware done (\(elapsedMs(since: loadStart))ms)", category: .engine)
                 playbackBackend = .software
diff --git a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
index fe22ed3bf..2a6b213c9 100644
--- a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
+++ b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
@@ -115,6 +115,26 @@ extension AetherEngine {
             throw AetherEngineError.sessionNotReloadable(refusal)
         }
 
+        // The dual-layer route is chosen by `load`'s probe (el_type, geometry, budget, handling) and a custom
+        // source's rebuild never re-runs it: it keeps the backend and the el_type the session came
+        // up with. Decided here for the same reason as the decode-path escape above, before any
+        // teardown, so the flip is refused instead of being logged as applied and ignored.
+        if let refusal = SessionOptionCorrection.dualLayerRouteRefusal(
+            isCustomSource: isCustomSource,
+            current: loadedOptions,
+            proposed: proposed,
+            dvProfile: DolbyVisionRecordAudit.correctedProfile(
+                record: sourceDVProfile, rpu: sourceDolbyVisionRPUProfile) ?? sourceDVProfile
+        ) {
+            EngineLog.emit(
+                "[AetherEngine] DV P7 dual-layer: preferDualLayerDolbyVision / dolbyVisionHandling correction refused, "
+                + "\(refusal.rawValue): a custom source keeps the route it was loaded with; load() it "
+                + "again with the new option",
+                category: .engine
+            )
+            throw AetherEngineError.sessionNotReloadable(refusal)
+        }
+
         // Stating the no-op matters for the same reason #364's teletext switch states it: a host
         // that corrected an option and saw a plain reload cannot otherwise tell "the correction was
         // already in force" from "the correction did not arrive".
@@ -246,6 +266,11 @@ public enum SessionReloadRefusal: String, Sendable, Equatable, CustomStringConve
     /// side-audio merge lives in the native path's segment producer, so the session would play
     /// silent. Same reachability as `softwarePathCannotRepresentSource`.
     case demuxedAudioLiveIsNativeOnly
+    /// A correction of `preferDualLayerDolbyVision`, or of `dolbyVisionHandling` while the preference is on, on a Profile 7 session that plays from a custom
+    /// `IOReader` source. The route is decided by `load()`'s probe, which a custom source's in-place
+    /// rebuild does not re-run, so the change could not take effect. Call `load()` again with the
+    /// new option. URL sources are not affected: their correction re-runs `load()`.
+    case dualLayerRouteNeedsFreshLoad
 
     public var description: String {
         switch self {
@@ -255,6 +280,8 @@ public enum SessionReloadRefusal: String, Sendable, Equatable, CustomStringConve
             return "the software path cannot represent this source's Dolby Vision signal"
         case .demuxedAudioLiveIsNativeOnly:
             return "this live source's audio is delivered separately and merged on the native path only"
+        case .dualLayerRouteNeedsFreshLoad:
+            return "the dual-layer Dolby Vision route of a custom source is decided by load(), not by a rebuild"
         }
     }
 }
@@ -360,6 +387,32 @@ enum SessionOptionCorrection {
         return nil
     }
 
+    /// Why a `preferDualLayerDolbyVision` or `dolbyVisionHandling` correction cannot be honoured, or nil
+    /// when it can.
+    ///
+    /// A URL source re-runs `load()` on a correction, which re-probes and re-decides the route. A
+    /// custom `IOReader` source rebuilds through `reloadWithAudioOverride`, which keeps the backend
+    /// and the el_type the session was loaded with, so the change would be logged as applied and move
+    /// nothing. The route needs the preference on and `dolbyVisionHandling` `.automatic`
+    /// (`DualLayerRouteDecision`), so a change of the preference always refuses, and a change of the
+    /// handling refuses when the preference is on, where it can turn the route on or off. With the
+    /// preference off the handling cannot move the route. Only a Profile 7 source can route
+    /// differently, so any other source is not refused: the change there moves nothing, which is also
+    /// what the rebuild does.
+    static func dualLayerRouteRefusal(
+        isCustomSource: Bool,
+        current: LoadOptions,
+        proposed: LoadOptions,
+        dvProfile: Int?
+    ) -> SessionReloadRefusal? {
+        guard isCustomSource, dvProfile == 7 else { return nil }
+        let preferenceChanged = proposed.preferDualLayerDolbyVision != current.preferDualLayerDolbyVision
+        let handlingMovesRoute = proposed.dolbyVisionHandling != current.dolbyVisionHandling
+            && proposed.preferDualLayerDolbyVision
+        guard preferenceChanged || handlingMovesRoute else { return nil }
+        return .dualLayerRouteNeedsFreshLoad
+    }
+
     /// Every field the proposal changed, for the log line. Reflection is right here and wrong
     /// above: a diagnostic that names a new field the day it is added is worth more than one that
     /// cannot be wrong, and being wrong here costs a log line.
@@ -390,7 +443,7 @@ enum SessionOptionCorrection {
     /// deliberately. Update this list and, if the field names the session, `loadIdentityFields`.
     static let knownFields: [String] = [
         "omitCriteriaColorExtensions", "suppressDisplayCriteria", "httpHeaders", "nativeVideoFrameDiagnostics", "nativeVideoFrameRecovery", "hostRetriesExhaustedLiveReplay",
-        "keepDvh1TagWithoutDV", "forceDolbyVisionOnNonDVDisplay", "dolbyVisionHandling", "matchContentEnabled",
+        "keepDvh1TagWithoutDV", "forceDolbyVisionOnNonDVDisplay", "dolbyVisionHandling", "preferDualLayerDolbyVision", "matchContentEnabled",
         "panelIsInHDRMode", "attemptsHDRMasterOnUnprovenPanel", "panelPresentsDolbyVision",
         "audioBridgeMode", "objectAudioRendering", "isLive", "audioOnly",
         "dvrWindowSeconds",
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5a5629242..770cd160e 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -614,6 +614,9 @@ public final class AetherEngine: ObservableObject {
     /// Deriving it keeps the load's answer and the rebuild's the same value rather than two.
     var sessionDisplayEligibleForHDR: Bool { sessionObservedDisplayCaps?.supportsHDR ?? false }
 
+    /// Enhancement layer type for Profile 7 streams ("FEL" or "MEL") extracted from the first RPU.
+    var sourceElType: String? = nil
+
     /// Whether the loaded source's Dolby Vision has a base layer `LoadOptions.dolbyVisionHandling =
     /// .baseLayerOnly` can present (`VideoRoutingPolicy.dolbyVisionBaseLayerIsPresentable`), decided
     /// on the probe stream for the same reason as `sourceDVBLCompatID`: a correction that turns the
@@ -4271,6 +4274,7 @@ public final class AetherEngine: ObservableObject {
         sourceDVProfile = nil
         dolbyVisionConversion = nil
         sourceCarriesHDR10PlusMetadata = false
+        sourceElType = nil
         sourceDVBLCompatID = nil
         sourceDolbyVisionBaseLayerPresentable = false
         sourceDolbyVisionRPUProfile = nil
@@ -5019,12 +5023,102 @@ public final class AetherEngine: ObservableObject {
                 category: .engine
             )
         }
+        // A Profile 7 source with in-band parameter sets (`hev1` with an empty hvcC) is unclassifiable
+        // to the strict verdict below and would stay native for that reason alone. When the dual-layer
+        // route is wanted, complete the probe's record from the head of the stream first; the session
+        // reuses this demuxer, so the software host and its decoders see the completed record too.
+        if probeOpened, probe.videoStreamIndex >= 0, !options.isLive, probe.isSourceSeekable,
+           VideoRoutingPolicy.dualLayerRouteIsWanted(
+               codecID: detectedCodecID,
+               dvProfile: detectedDVProfileNum,
+               dolbyVisionHandling: options.dolbyVisionHandling,
+               preferDualLayerDolbyVision: options.preferDualLayerDolbyVision,
+               canHardwareDecode: nil) {
+            let vIdx = probe.videoStreamIndex
+            await BlockingWork.detached(priority: .userInitiated) { [probe] in
+                VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: probe, streamIndex: vIdx)
+            }.value
+            if loadGeneration != gen {
+                probe.markClosed()
+                BlockingWork.detached { [probe] in probe.close() }
+                try checkLoadCurrent(gen)
+            }
+        }
+        // Strict verdict: SoftwarePlaybackHost only opens HardwareVideoDecoder for a proven hardware
+        // session. An unclassifiable config record stays native, because the host would hand it to
+        // libavcodec, which cannot compose the dual layers. Shared by the el_type probe's gate and the
+        // routing decision below, so the two cannot disagree.
+        let opensHardwareHEVC: () -> Bool = {
+            if let vStream = probe.stream(at: probe.videoStreamIndex),
+               let cp = vStream.pointee.codecpar {
+                return VTCapabilityProbe.opensHardwareDecoder(codecpar: cp)
+            }
+            return false
+        }
+        // Dual-layer decision for a Profile 7 source: FEL only, behind a capability gate (hardware HEVC
+        // decode, and a pixel rate the box can decode twice in real time), logged once. The el_type
+        // probe reads up to 256 packets and seeks back, so it runs only when nothing in
+        // `blockingReasonBeforeProbe` (preference, handling, live/seekable, hardware) rules the route
+        // out. The geometry and the budget are NOT in that list: they run after the probe, in
+        // `decide`, because a MEL or unclassified el_type outranks them in the log line, so a stream
+        // that its size alone would refuse still pays the probe.
+        var elType: String? = nil
+        var dualLayerGeometry = DualLayerRouteDecision.Geometry(width: 0, height: 0, frameRate: nil)
+        if probeOpened, let vStream = probe.stream(at: probe.videoStreamIndex),
+           let cp = vStream.pointee.codecpar {
+            dualLayerGeometry = DualLayerRouteDecision.Geometry(
+                width: Int(cp.pointee.width), height: Int(cp.pointee.height),
+                frameRate: Self.detectFrameRate(stream: vStream))
+        }
+        let dualLayerSeekable = probeOpened && probe.videoStreamIndex >= 0 && probe.isSourceSeekable
+        if DualLayerRouteDecision.blockingReasonBeforeProbe(
+            codecID: detectedCodecID,
+            dvProfile: detectedDVProfileNum,
+            dolbyVisionHandling: options.dolbyVisionHandling,
+            preferDualLayerDolbyVision: options.preferDualLayerDolbyVision,
+            isLive: options.isLive,
+            isSourceSeekable: dualLayerSeekable,
+            canHardwareDecode: opensHardwareHEVC) == nil {
+            let vIdx = probe.videoStreamIndex
+            elType = await BlockingWork.detached(priority: .userInitiated) { [probe] in
+                let result = DolbyVisionRecordAudit.probeEnhancementLayerType(demuxer: probe, streamIndex: vIdx)
+                probe.seek(to: 0)
+                return result
+            }.value
+            if loadGeneration != gen {
+                probe.markClosed()
+                BlockingWork.detached { [probe] in probe.close() }
+                try checkLoadCurrent(gen)
+            }
+        }
+        let dualLayerDecision = DualLayerRouteDecision.decide(
+            codecID: detectedCodecID,
+            dvProfile: detectedDVProfileNum,
+            dolbyVisionHandling: options.dolbyVisionHandling,
+            preferDualLayerDolbyVision: options.preferDualLayerDolbyVision,
+            isLive: options.isLive,
+            isSourceSeekable: dualLayerSeekable,
+            canHardwareDecode: opensHardwareHEVC,
+            elType: elType,
+            geometry: dualLayerGeometry)
+        if let line = dualLayerDecision.logLine {
+            EngineLog.emit(line, category: .engine)
+        }
+        // A route that was not taken leaves no el_type behind, so neither the routing below nor a
+        // software host the session reaches for another reason composes the dual layers.
+        if !dualLayerDecision.isTaken { elType = nil }
+        sourceElType = elType
         var useSoftwarePath = VideoRoutingPolicy.requiresSoftwarePath(
             codecID: detectedCodecID,
             fieldOrder: detectedFieldOrder,
             av1Available: VTCapabilityProbe.av1Available,
             spsIndicatesInterlaced: spsIndicatesInterlaced,
-            stereo3DType: containerStereoType
+            stereo3DType: containerStereoType,
+            dvProfile: detectedDVProfileNum,
+            dolbyVisionHandling: options.dolbyVisionHandling,
+            preferDualLayerDolbyVision: options.preferDualLayerDolbyVision,
+            canHardwareDecode: opensHardwareHEVC,
+            elType: elType
         )
         // #232: a declared interlaced field order is not evidence that any frame IS interlaced.
         // European 25 fps Blu-ray masters ship as 1080i25 (there is no 1080p25): interlaced carriage,
@@ -5247,7 +5341,8 @@ public final class AetherEngine: ObservableObject {
                     isLive: options.isLive,
                     dvrWindowSeconds: options.dvrWindowSeconds,
                     preopenedDemuxer: probeOpened ? probe : nil,
-                    generation: gen
+                    generation: gen,
+                    elType: elType
                 )
                 playbackBackend = .software
                 // AE#550: the one thing a viewer on a receiver needs said out loud. This backend's
@@ -6473,6 +6568,7 @@ public final class AetherEngine: ObservableObject {
         sourceDVProfile = nil
         dolbyVisionConversion = nil
         sourceCarriesHDR10PlusMetadata = false
+        sourceElType = nil
         sourceDVBLCompatID = nil
         sourceDolbyVisionBaseLayerPresentable = false
         sourceDolbyVisionRPUProfile = nil
diff --git a/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift b/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
new file mode 100644
index 000000000..406ff8d2a
--- /dev/null
+++ b/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
@@ -0,0 +1,199 @@
+import AetherLibavcodec
+
+/// Whether a Profile 7 load takes the dual-layer route (`SoftwarePlaybackHost` + `DualLayerVideoDecoder`)
+/// or keeps the native route (single-layer 8.1 where the display takes Dolby Vision), and if not, why. Pure so every exit is unit-testable; the load asks it
+/// once per P7 source and logs `logLine`, so the diagnostic and the routing cannot disagree.
+///
+/// The route is FEL only and capability gated: MEL, an unclassifiable enhancement layer, a box without a
+/// hardware HEVC decoder, and a stream the box could not decode twice in real time all fall back to the
+/// native route, which is the 8.1 conversion where the display takes Dolby Vision and the HDR10 base
+/// layer where it does not. (The conversion loses nothing for MEL; for FEL it drops the residual.)
+enum DualLayerRouteDecision: Equatable {
+
+    case taken(elType: String, geometry: Geometry, budgetFraction: Double)
+    case notTaken(Reason)
+
+    /// Every reason the route is not taken, in the order the checks run.
+    enum Reason: Equatable {
+        /// Not HEVC Dolby Vision Profile 7: nothing to decide, and nothing is logged.
+        case notProfile7
+        case preferenceOff
+        case baseLayerOnlyHandling
+        case liveOrNotSeekable
+        case noHardwareHEVC
+        case melEnhancementLayer
+        case enhancementLayerTypeUnknown
+        /// The base layer's width or height is not positive (the probe found none): the budget cannot be
+        /// computed, and a zero requirement must not read as "fits".
+        case geometryUnknown
+        case overBudget(requiredPixelsPerSecond: Double, geometry: Geometry)
+    }
+
+    /// Base-layer picture geometry the budget is computed from. `frameRate` is nil when the container
+    /// declares none; the budget then assumes `assumedFrameRate`.
+    struct Geometry: Equatable {
+        var width: Int
+        var height: Int
+        var frameRate: Double?
+
+        var effectiveFrameRate: Double {
+            guard let frameRate, frameRate.isFinite, frameRate > 0 else { return DualLayerRouteDecision.assumedFrameRate }
+            return frameRate
+        }
+
+        var text: String {
+            let rate = frameRate.map { rateText($0) } ?? "\(rateText(DualLayerRouteDecision.assumedFrameRate)) (assumed)"
+            return "\(width)x\(height)@\(rate)"
+        }
+
+        private func rateText(_ value: Double) -> String {
+            value.rounded() == value ? String(Int(value)) : String(format: "%.3f", value)
+        }
+    }
+
+    /// The most pixels per second, base layer plus enhancement layer, the route is willing to decode in
+    /// real time: UHD 3840x2160 at 30 fps (248.8 Mpx/s) plus a 1920x1080 enhancement layer at 30 fps
+    /// (62.2 Mpx/s), 311.04 Mpx/s in all. The anchor is a 24p UHD FEL master, the shape UHD Blu-ray
+    /// remuxes have in practice (248.8 Mpx/s with its enhancement layer, 80% of this). Measured: the Mac
+    /// soak runs of this stack, and the composer's GPU time on an Apple TV 4K 2nd generation in earlier
+    /// development builds (12.9-14.3 ms per 23.976 fps frame, docs/dolby-vision-fel.md §4.2). The budget
+    /// itself, and 30 fps as a ceiling above 24p, are an assumption until the Apple TV run of this
+    /// stack. Anything heavier (UHD at 60 fps, 8K) keeps the native route instead of
+    /// risking dropped frames.
+    static let maximumPixelsPerSecond: Double =
+        (3840.0 * 2160.0 + 1920.0 * 1080.0) * 30.0
+
+    /// Frame rate the budget assumes when the container declares none. 24, because FEL masters are 24p.
+    static let assumedFrameRate: Double = 24
+
+    /// The enhancement layer's share of the base layer's area when the stream's own enhancement-layer
+    /// dimensions are not known: a quarter, which is what a 4K FEL disc ships (1080p over UHD).
+    static let assumedEnhancementLayerAreaFraction: Double = 0.25
+
+    /// Pixels per second both layers need: the base layer's, plus the enhancement layer's, taken from
+    /// `enhancementLayerSize` when the stream states it and as a quarter of the base layer's area otherwise.
+    /// The load passes no `enhancementLayerSize`: it budgets a quarter-area enhancement layer (every retail
+    /// FEL title's layout), and a 1:1 enhancement layer is not detected at load.
+    static func requiredPixelsPerSecond(
+        geometry: Geometry, enhancementLayerSize: (width: Int, height: Int)? = nil
+    ) -> Double {
+        let base = Double(geometry.width) * Double(geometry.height)
+        let enhancement = enhancementLayerSize.map { Double($0.width) * Double($0.height) }
+            ?? base * assumedEnhancementLayerAreaFraction
+        return (base + enhancement) * geometry.effectiveFrameRate
+    }
+
+    /// The reason the route cannot be taken whatever the enhancement layer is, or nil when only the
+    /// `el_type` (and the budget) remain to decide. The load runs this first so the `el_type` probe, a
+    /// packet scan and a seek, only happens when its answer can change the route. A nil
+    /// `canHardwareDecode` assumes hardware decode.
+    static func blockingReasonBeforeProbe(
+        codecID: AVCodecID,
+        dvProfile: Int?,
+        dolbyVisionHandling: DolbyVisionHandling,
+        preferDualLayerDolbyVision: Bool,
+        isLive: Bool,
+        isSourceSeekable: Bool,
+        canHardwareDecode: (() -> Bool)?
+    ) -> Reason? {
+        guard codecID == AV_CODEC_ID_HEVC, dvProfile == 7 else { return .notProfile7 }
+        guard preferDualLayerDolbyVision else { return .preferenceOff }
+        guard dolbyVisionHandling == .automatic else { return .baseLayerOnlyHandling }
+        guard !isLive, isSourceSeekable else { return .liveOrNotSeekable }
+        guard canHardwareDecode?() ?? true else { return .noHardwareHEVC }
+        return nil
+    }
+
+    /// The full decision. `elType` is the probe's answer ("FEL", "MEL", or nil when it found none).
+    static func decide(
+        codecID: AVCodecID,
+        dvProfile: Int?,
+        dolbyVisionHandling: DolbyVisionHandling,
+        preferDualLayerDolbyVision: Bool,
+        isLive: Bool,
+        isSourceSeekable: Bool,
+        canHardwareDecode: (() -> Bool)?,
+        elType: String?,
+        geometry: Geometry,
+        enhancementLayerSize: (width: Int, height: Int)? = nil
+    ) -> DualLayerRouteDecision {
+        if let reason = blockingReasonBeforeProbe(
+            codecID: codecID, dvProfile: dvProfile, dolbyVisionHandling: dolbyVisionHandling,
+            preferDualLayerDolbyVision: preferDualLayerDolbyVision, isLive: isLive,
+            isSourceSeekable: isSourceSeekable, canHardwareDecode: canHardwareDecode) {
+            return .notTaken(reason)
+        }
+        switch elType {
+        case "FEL":
+            guard geometry.width > 0, geometry.height > 0 else { return .notTaken(.geometryUnknown) }
+            let required = requiredPixelsPerSecond(geometry: geometry, enhancementLayerSize: enhancementLayerSize)
+            guard required <= maximumPixelsPerSecond else {
+                return .notTaken(.overBudget(requiredPixelsPerSecond: required, geometry: geometry))
+            }
+            return .taken(elType: "FEL", geometry: geometry, budgetFraction: required / maximumPixelsPerSecond)
+        case "MEL":
+            return .notTaken(.melEnhancementLayer)
+        default:
+            return .notTaken(.enhancementLayerTypeUnknown)
+        }
+    }
+
+    var isTaken: Bool {
+        if case .taken = self { return true }
+        return false
+    }
+
+    /// The one diagnostic line for a Profile 7 load, or nil for a source this decision does not concern.
+    var logLine: String? {
+        switch self {
+        case .notTaken(.notProfile7):
+            return nil
+        case let .taken(elType, geometry, fraction):
+            return "[AetherEngine] DV P7 dual-layer route: taken (el_type=\(elType), \(geometry.text), "
+                + "budget \(Int((fraction * 100).rounded()))%)"
+        case let .notTaken(reason):
+            return "[AetherEngine] DV P7 dual-layer route: not taken (\(reason.text)), \(reason.fallbackText)"
+        }
+    }
+}
+
+extension DualLayerRouteDecision.Reason {
+
+    var text: String {
+        switch self {
+        case .notProfile7:
+            return "not Dolby Vision Profile 7"
+        case .preferenceOff:
+            return "preferDualLayerDolbyVision is off"
+        case .baseLayerOnlyHandling:
+            return "dolbyVisionHandling is baseLayerOnly"
+        case .liveOrNotSeekable:
+            return "live or non-seekable source"
+        case .noHardwareHEVC:
+            return "no hardware HEVC decoder for this stream"
+        case .melEnhancementLayer:
+            return "el_type=MEL, nothing to compose"
+        case .enhancementLayerTypeUnknown:
+            return "el_type unknown, no enhancement layer classified in the first RPU"
+        case .geometryUnknown:
+            return "base-layer size unknown"
+        case let .overBudget(required, geometry):
+            let percent = Int((required / DualLayerRouteDecision.maximumPixelsPerSecond * 100).rounded())
+            return "over the real-time budget, \(geometry.text) needs \(percent)% of it"
+        }
+    }
+
+    /// What the not-taken line says plays instead. Deliberately about the ROUTE, not the picture: the
+    /// native route presents 8.1 only where the display takes Dolby Vision, and the HDR10 base layer
+    /// where it does not (`CodecRoutePolicy` strips the Dolby Vision) or `preferredDecodePath` is
+    /// `.software`. Pinned by `DualLayerRouteDecisionTests`.
+    static let nativeRouteFallback = "keeps the native route (8.1 where the display takes Dolby Vision)"
+
+    /// What plays instead.
+    var fallbackText: String {
+        switch self {
+        case .baseLayerOnlyHandling: return "playing the HDR10 base layer"
+        default: return Self.nativeRouteFallback
+        }
+    }
+}
diff --git a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
index e8b9b9b0a..e75673ba3 100644
--- a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
+++ b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
@@ -12,6 +12,22 @@ enum VideoRoutingPolicy {
         AV_FIELD_TT, AV_FIELD_BB, AV_FIELD_TB, AV_FIELD_BT
     ]
 
+    /// Whether the Profile 7 dual-layer route is both requested and possible, which is everything that
+    /// decides it except the stream's `el_type`. `requiresSoftwarePath` adds the FEL condition; the load
+    /// asks this one first, so the `el_type` probe (a packet scan and a seek) only runs when its answer
+    /// can change the route. A nil `canHardwareDecode` assumes hardware decode.
+    static func dualLayerRouteIsWanted(
+        codecID: AVCodecID,
+        dvProfile: Int?,
+        dolbyVisionHandling: DolbyVisionHandling,
+        preferDualLayerDolbyVision: Bool,
+        canHardwareDecode: (() -> Bool)?
+    ) -> Bool {
+        guard codecID == AV_CODEC_ID_HEVC, dvProfile == 7,
+              preferDualLayerDolbyVision, dolbyVisionHandling == .automatic else { return false }
+        return canHardwareDecode?() ?? true
+    }
+
     /// 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.
@@ -33,8 +49,29 @@ enum VideoRoutingPolicy {
         fieldOrder: AVFieldOrder,
         av1Available: @autoclosure () -> Bool,
         spsIndicatesInterlaced: Bool = false,
-        stereo3DType: AVStereo3DType? = nil
+        stereo3DType: AVStereo3DType? = nil,
+        dvProfile: Int? = nil,
+        dolbyVisionHandling: DolbyVisionHandling = .automatic,
+        preferDualLayerDolbyVision: Bool = false,
+        canHardwareDecode: (() -> Bool)? = nil,
+        elType: String? = nil
     ) -> Bool {
+        // Profile 7 FEL dual-layer Metal reconstruction routes to the software host pipeline
+        // when preferDualLayerDolbyVision is enabled, dolbyVisionHandling is .automatic, and hardware decode is confirmed (or assumed true if closure
+        // not provided).
+        // Only elType == "FEL" routes to software; MEL, nil, or unknown stay native
+        // (the 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where it does
+        // not; the conversion is lossless only for MEL).
+        // If dolbyVisionHandling is .baseLayerOnly, it also stays native (HDR10 base layer).
+        if codecID == AV_CODEC_ID_HEVC, dvProfile == 7 {
+            return elType == "FEL" && dualLayerRouteIsWanted(
+                codecID: codecID,
+                dvProfile: dvProfile,
+                dolbyVisionHandling: dolbyVisionHandling,
+                preferDualLayerDolbyVision: preferDualLayerDolbyVision,
+                canHardwareDecode: canHardwareDecode
+            )
+        }
         switch codecID {
         case AV_CODEC_ID_NONE, AV_CODEC_ID_HEVC:
             return false
diff --git a/Sources/AetherEngine/Diagnostics/EngineLog.swift b/Sources/AetherEngine/Diagnostics/EngineLog.swift
index 9f24628af..b0f91355b 100644
--- a/Sources/AetherEngine/Diagnostics/EngineLog.swift
+++ b/Sources/AetherEngine/Diagnostics/EngineLog.swift
@@ -63,6 +63,14 @@ public enum EngineLog {
         return map
     }()
 
+    private static let osLogs: [Category: OSLog] = {
+        var map: [Category: OSLog] = [:]
+        for cat in Category.allCases {
+            map[cat] = OSLog(subsystem: subsystem, category: cat.rawValue)
+        }
+        return map
+    }()
+
     public enum Level: Sendable {
         /// Default: OSLog default level + host handler (in-app overlay, aetherctl stdout).
         case info
@@ -91,12 +99,14 @@ public enum EngineLog {
     /// `.public` privacy means a Console.app capture or a sysdiagnose would otherwise carry the token
     /// in clear text even for a host that scrubs its own log.
     private static func deliver(_ line: String, category: Category, level: Level) {
-        let line = LogRedaction.redact(line)
         switch level {
         case .info:
+            let line = LogRedaction.redact(line)
             loggers[category]?.log("\(line, privacy: .public)")
             handler?(line)
         case .verbose:
+            guard let osLog = osLogs[category], osLog.isEnabled(type: .debug) else { return }
+            let line = LogRedaction.redact(line)
             loggers[category]?.debug("\(line, privacy: .public)")
         }
     }
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 9817a8f6e..f8800a22d 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -72,6 +72,18 @@ final class SoftwarePlaybackHost {
     @Published private(set) var failure: PlaybackErrorInfo?
     @Published private(set) var didReachEnd: Bool = false
 
+    /// Enhancement layer type for Profile 7 streams (FEL or MEL), used for decoder selection
+    var elType: String? = nil
+
+    /// Which layer of a Dolby Vision source to present (.automatic or .baseLayerOnly).
+    var dolbyVisionHandling: DolbyVisionHandling = .automatic
+
+    /// Opt-in to full dual-layer Dolby Vision (Profile 7 FEL) decoding and Metal GPU composition over single-layer fallback.
+    var preferDualLayerDolbyVision: Bool = false
+
+    /// Forwarded Dolby Vision profile number (e.g. 7, 8) if detected from bitstream or container
+    var configuredDVProfile: Int?
+
     /// #315: `AVSampleBufferDisplayLayer.isReadyForDisplay` for the renderer's layer, this path's
     /// answer to "there is a picture". Frames enqueued is not that answer: it counts what the
     /// decoder handed over, and #298 is the report where every one of them went into a layer no
@@ -857,6 +869,51 @@ final class SoftwarePlaybackHost {
         return min(max(untilGateOpens, floor), ceiling)
     }
 
+    /// Pure decoder selection predicate for Profile 7 / HEVC streams on the software host.
+    /// DualLayerVideoDecoder is selected ONLY when dvProfile == 7 && elType == "FEL" && preferDualLayerDolbyVision
+    /// && dolbyVisionHandling == .automatic.
+    /// All other combinations (e.g. MEL, baseLayerOnly, preferDualLayerDolbyVision == false) pick HardwareVideoDecoder.
+    nonisolated static func shouldUseDualLayerDecoder(
+        dvProfile: Int?,
+        elType: String?,
+        preferDualLayerDolbyVision: Bool,
+        dolbyVisionHandling: DolbyVisionHandling
+    ) -> Bool {
+        dvProfile == 7
+            && elType == "FEL"
+            && preferDualLayerDolbyVision
+            && dolbyVisionHandling == .automatic
+    }
+
+    /// Selects and instantiates the appropriate VideoDecodingPipeline based on stream and host options.
+    func selectVideoDecoder(
+        codecID: AVCodecID,
+        canHardwareDecode: Bool,
+        dvProfile: Int?
+    ) -> any VideoDecodingPipeline {
+        if codecID == AV_CODEC_ID_HEVC && canHardwareDecode {
+            if Self.shouldUseDualLayerDecoder(
+                dvProfile: dvProfile,
+                elType: elType,
+                preferDualLayerDolbyVision: preferDualLayerDolbyVision,
+                dolbyVisionHandling: dolbyVisionHandling
+            ) {
+                // No Metal device: the composer cannot be built, so decode the base layer alone (the
+                // decoder the software host uses for any other Profile 7 stream) instead of opening a
+                // decoder whose `open()` can only throw. A shader that fails to compile is caught later,
+                // once: every frame then goes out as its base layer.
+                if let composer = DoviFelComposer() {
+                    return DualLayerVideoDecoder(composer: composer)
+                }
+                return HardwareVideoDecoder()
+            } else {
+                return HardwareVideoDecoder()
+            }
+        } else {
+            return SoftwareVideoDecoder()
+        }
+    }
+
     // MARK: - Load
 
     func load(
@@ -915,6 +972,23 @@ final class SoftwarePlaybackHost {
             category: .swPlayback
         )
 
+        // A Profile 7 FEL session on a freshly opened demuxer (the load's probe completes its own) still
+        // has the empty hvcC of an in-band-parameter-set source: complete it, or the verdict below sends
+        // the stream to libavcodec and the enhancement layer is never composed. No-op otherwise.
+        if !isLive,
+           Self.shouldUseDualLayerDecoder(
+               dvProfile: configuredDVProfile ?? AetherEngine.dvProfile(stream: vStream),
+               elType: elType,
+               preferDualLayerDolbyVision: preferDualLayerDolbyVision,
+               dolbyVisionHandling: dolbyVisionHandling) {
+            let vIdx = dem.videoStreamIndex
+            await BlockingWork.detached(priority: .userInitiated) {
+                VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: dem, streamIndex: vIdx)
+            }.value
+            // A stop() can land on this suspension as on the start-position seek below.
+            guard !stopRequested else { return }
+        }
+
         // HEVC -> VTDecompressionSession (HW) when VideoToolbox PROVABLY HW-decodes this exact format;
         // everything else -> libavcodec. Replace wholesale to prevent state bleed. #2: HardwareVideoDecoder
         // requires a HW decoder and has no software fallback, so an HEVC Rext stream on hardware without a
@@ -925,11 +999,40 @@ final class SoftwarePlaybackHost {
            codecpar.pointee.codec_id == AV_CODEC_ID_HEVC,
            VTCapabilityProbe.hardwareDecodeVerdict(codecpar: codecpar).opensHardwareDecoder {
             videoDecoder.close()
-            videoDecoder = HardwareVideoDecoder()
-            EngineLog.emit(
-                "[SWHost] selected HardwareVideoDecoder (VT HEVC) for codec_id=\(codecpar.pointee.codec_id.rawValue)",
-                category: .swPlayback
+            let dvProfile = configuredDVProfile ?? AetherEngine.dvProfile(stream: vStream)
+            let chosen = selectVideoDecoder(
+                codecID: codecpar.pointee.codec_id,
+                canHardwareDecode: true,
+                dvProfile: dvProfile
             )
+            videoDecoder = chosen
+            if let dual = chosen as? DualLayerVideoDecoder {
+                // An in-band primary open failure (no hvcC to open from) leaves nothing to show. Surface it
+                // through the same `failure` the read loops use for a decode error. It belongs to the
+                // decoder session, not to a seek: the decoder reports it once and a seek does not reopen the
+                // primary decoder, so gating it by seek generation would lose it for good when a seek lands
+                // between the report and the main-actor hop (black video, no error). Only a stopped host
+                // drops it.
+                dual.onFatalDecodeError = { [weak self] error in
+                    Task { @MainActor [weak self] in
+                        guard let self, SoftwareReadAdmission.admitsSessionFailure(stopRequested: self.stopRequested) else { return }
+                        self.failure = PlaybackErrorInfo(
+                            kind: .softwarePipelineFailed,
+                            message: "Playback error: \(error.localizedDescription)")
+                    }
+                }
+            }
+            if chosen is DualLayerVideoDecoder {
+                EngineLog.emit(
+                    "[SWHost] selected DualLayerVideoDecoder (Metal P7 FEL) for codec_id=\(codecpar.pointee.codec_id.rawValue)",
+                    category: .swPlayback
+                )
+            } else {
+                EngineLog.emit(
+                    "[SWHost] selected HardwareVideoDecoder (VT HEVC) for codec_id=\(codecpar.pointee.codec_id.rawValue)",
+                    category: .swPlayback
+                )
+            }
         } else if !(videoDecoder is SoftwareVideoDecoder) {
             videoDecoder.close()
             videoDecoder = SoftwareVideoDecoder()
@@ -940,8 +1043,15 @@ final class SoftwarePlaybackHost {
             )
         }
 
-        // Audit PERF-104: only the VideoToolbox decoder emits out of presentation order.
-        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: videoDecoder is HardwareVideoDecoder))
+        // Audit PERF-104: only the VideoToolbox decoders emit out of presentation order. That includes the
+        // DualLayerVideoDecoder: OrderedDelivery keeps its frames in the order the base layer came out of
+        // VideoToolbox, which is decode order (measured on the real fixtures, `DoviFelRealFileTests`), so it
+        // needs the same reorder depth as the single-layer hardware decoder.
+        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(
+            forHardwareDecoder: videoDecoder is HardwareVideoDecoder || videoDecoder is DualLayerVideoDecoder))
+        renderer.setFELLookahead(
+            enabled: videoDecoder is DualLayerVideoDecoder,
+            frameRate: AetherEngine.detectFrameRate(stream: vStream))
 
         // 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 {
@@ -1081,8 +1191,8 @@ final class SoftwarePlaybackHost {
             // #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: sourceStart, timeout: Self.seekBudgetSeconds, on: seekQueue)
-            // This is load()'s only suspension point, so it is also the only place a stop() can land
-            // mid-load. Arming the clock and publishing isReady on a session already torn down would
+            // Besides the in-band record completion above, this is load()'s only suspension point, so it
+            // is the other place a stop() can land mid-load. Arming the clock and publishing isReady on a session already torn down would
             // hand the engine a host it has stopped.
             guard !stopRequested else { return }
             // Mirror seek() skip-PTS + clock alignment so demux drops pre-keyframe frames and synchronizer starts at the resume offset.
@@ -2548,7 +2658,12 @@ final class SoftwarePlaybackHost {
                 // Back-pressure against renderer queue; also bail on pause without consuming.
                 // The wait can outlast the audio lead, so keep pumping audio while parked.
                 var waitTicks = 0
-                while !renderer.isReadyForMoreMediaData && !stopRequested() && isPlaying()
+                // The FEL look-ahead gate (`mayEnqueueVideoFrame`) holds a packet until its timestamp is
+                // inside the clock's window; a seek, including a backward DVR seek, moves the cursor and
+                // releases it here rather than waiting for its old timestamp to come round.
+                while !renderer.mayEnqueueVideoFrame(
+                    ptsSeconds: pkt.pts, clockSeconds: audioOutput?.currentTimeSeconds ?? .nan,
+                    clockArmed: clockArmed()) && !stopRequested() && isPlaying()
                     && seekGeneration() == generation && readCursor() == cursor
                     && cursor >= ring.seqBounds.first {
                     autoreleasepool {
@@ -2767,10 +2882,19 @@ final class SoftwarePlaybackHost {
         // takes it, holds it, stops reporting `isReadyForMoreMediaData`, and the loop parks on that
         // signal until its FIFO caps out. Measured here as three to four seconds of `enq=+0` with the
         // audio lead decaying under it, on a session that reports playing and never rebuffers.
+        func mayDecodeVideoPacket(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
+            let pts = packet.pointee.pts
+            let seconds = pts != Int64.min && videoTimeBaseSeconds > 0
+                ? Double(pts) * videoTimeBaseSeconds : Double.nan
+            return renderer.mayEnqueueVideoFrame(
+                ptsSeconds: seconds, clockSeconds: audioOutput?.currentTimeSeconds ?? .nan,
+                clockArmed: clockArmed())
+        }
+
         func drainParkedVideoNonblocking() {
             if seekGeneration() != parkedSeekGeneration { return }
             let epoch = videoDecoder.feedEpoch
-            while !parkedVideo.isEmpty, renderer.isReadyForMoreMediaData,
+            while let head = parkedVideo.first, mayDecodeVideoPacket(head),
                   !stopRequested(), !backgroundAudioOnly() {
                 // Leave the rest standing: the next iteration of the loop frees the FIFO as a batch
                 // once it has read the new generation.
@@ -3165,7 +3289,12 @@ final class SoftwarePlaybackHost {
                     return true
                 }
                 // Back-pressure via SampleBufferRenderer.isReadyForMoreMediaData (not the deprecated layer property). Park on condition while paused to avoid 200 Hz CPU spin.
-                while !renderer.isReadyForMoreMediaData && !stopRequested() && !backgroundAudioOnly() {
+                // Queue readiness plus the FEL-only look-ahead cap. Hold the compressed packet here,
+                // rather than letting an asynchronous decode allocate another composed buffer.
+                while !mayDecodeVideoPacket(packet) && !stopRequested() && !backgroundAudioOnly() {
+                    // A seek can move the clock backwards while this compressed FEL packet is
+                    // held. Leave the wait so the generation check below discards it immediately.
+                    if videoDecoder is DualLayerVideoDecoder, seekGeneration() != genBeforeRead { break }
                     autoreleasepool {
                         if !isPlaying() {
                             condition.lock()
diff --git a/Sources/AetherEngine/Native/SoftwareReadAdmission.swift b/Sources/AetherEngine/Native/SoftwareReadAdmission.swift
index 6ed97862f..2215a2efa 100644
--- a/Sources/AetherEngine/Native/SoftwareReadAdmission.swift
+++ b/Sources/AetherEngine/Native/SoftwareReadAdmission.swift
@@ -9,6 +9,11 @@ enum SoftwareReadAdmission {
         !stopRequested && readGeneration == requestedGeneration
             && requestedGeneration == settledGeneration
     }
+
+    /// A failure that belongs to the session rather than to one seek (the dual-layer decoder's primary
+    /// open, reported once and not retried by a seek). A seek in flight must not drop it, because
+    /// nothing reports it a second time; only a stopped host does.
+    static func admitsSessionFailure(stopRequested: Bool) -> Bool { !stopRequested }
 }
 
 /// The combined VOD loop stays alive after one EOF/error publication. MainActor may reject that
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 68892ce54..26759351e 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -388,8 +388,14 @@ public enum DecodePath: String, Sendable, Equatable, CaseIterable {
 }
 
 /// Which layer of a Dolby Vision source a session presents. See `LoadOptions.dolbyVisionHandling`.
+/// For Profile 7, FEL (Full Enhancement Layer, `el_type == 'FEL'`) is reconstructed from both layers
+/// on the software host with `DualLayerVideoDecoder` only when `LoadOptions.preferDualLayerDolbyVision`
+/// is true (default false) and the capability gate passes. Otherwise a Profile 7 source goes native:
+/// the single-layer 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where
+/// it does not. MEL (Minimal Enhancement Layer, `el_type == 'MEL'`) always goes native, because it has
+/// no residual to compose, whatever the preference.
 public enum DolbyVisionHandling: String, Sendable, Equatable, CaseIterable {
-    /// Dolby Vision wherever the profile and the display allow it. The default.
+    /// Dolby Vision wherever the profile and the display allow it. A Profile 7 source takes the native route (converted to single-layer 8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not); its FEL is reconstructed (dual-layer Metal) instead only when `LoadOptions.preferDualLayerDolbyVision` is true, which defaults to false. The default.
     case automatic
     /// Present the HDR10 / HLG base layer and leave the Dolby Vision out of the container: `hvc1` /
     /// `av01` sample entry, `dvcC` stripped, no `SUPPLEMENTAL-CODECS`, HDR10 / HLG display criteria.
@@ -465,6 +471,33 @@ public struct LoadOptions: Sendable, Equatable {
     /// contradicts.
     public var dolbyVisionHandling: DolbyVisionHandling
 
+    /// Opt in to full dual-layer Dolby Vision decoding of Profile 7 FEL streams, composed on the GPU, instead of
+    /// the native route (the single-layer Profile 8.1 conversion, or the HDR10 base layer). When true, `dolbyVisionHandling` is `.automatic`, the stream's
+    /// enhancement layer is FEL, VideoToolbox decodes HEVC in hardware and the stream fits the real-time
+    /// budget (`DualLayerRouteDecision.maximumPixelsPerSecond`: UHD at 30 fps plus a 1080p enhancement
+    /// layer), the stream routes through the dual-layer pipeline (SoftwarePlaybackHost +
+    /// DualLayerVideoDecoder). A Profile 7 MEL stream, and anything the device cannot decode twice in real
+    /// time, keeps the native route either way (8.1 where the display takes Dolby Vision, the HDR10 base
+    /// layer where it does not); the load logs one line saying which route it took and why. The source
+    /// must be a seekable VOD: live and non-seekable sources keep the native route. Default false.
+    ///
+    /// The route does not consult the display. With this on and a display that does not take Dolby
+    /// Vision, the route is still taken: the composed full-FEL picture is presented with its attached
+    /// metadata, and how tvOS presents it is up to the platform. The audio trade-off below applies there
+    /// too.
+    ///
+    /// A tuning field: `reloadAtCurrentPosition(applying:)` carries a change on a URL source (which
+    /// re-runs `load()`). On a custom `IOReader` source a Profile 7 session refuses it with
+    /// `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, because the in-place rebuild keeps the route
+    /// the session was loaded with; call `load()` again instead.
+    ///
+    /// Known trade-off, audio: the route runs on the software host, whose audio is decoded by FFmpeg and
+    /// played through the sample-buffer audio renderer, and on tvOS only AVPlayer emits Dolby Atmos objects.
+    /// An E-AC-3 (JOC) track therefore plays as its channel-bed core (5.1 or 7.1), without the Atmos objects,
+    /// where the native route would hand it to AVPlayer unchanged. TrueHD behaves as on the native route,
+    /// which also decodes it and loses the objects. Not engineered around.
+    public var preferDualLayerDolbyVision: Bool = false
+
     /// Mirror of `AVDisplayManager.isDisplayCriteriaMatchingEnabled`. Default `true`. When `false`, engine routes HDR sources through the media playlist (auto-tonemap path) because AVKit cannot switch the panel.
     public var matchContentEnabled: Bool
 
@@ -947,6 +980,7 @@ public struct LoadOptions: Sendable, Equatable {
         keepDvh1TagWithoutDV: Bool = false,
         forceDolbyVisionOnNonDVDisplay: Bool = false,
         dolbyVisionHandling: DolbyVisionHandling = .automatic,
+        preferDualLayerDolbyVision: Bool = false,
         matchContentEnabled: Bool = true,
         panelIsInHDRMode: Bool = false,
         attemptsHDRMasterOnUnprovenPanel: Bool = true,
@@ -1000,6 +1034,7 @@ public struct LoadOptions: Sendable, Equatable {
         self.keepDvh1TagWithoutDV = keepDvh1TagWithoutDV
         self.forceDolbyVisionOnNonDVDisplay = forceDolbyVisionOnNonDVDisplay
         self.dolbyVisionHandling = dolbyVisionHandling
+        self.preferDualLayerDolbyVision = preferDualLayerDolbyVision
         self.matchContentEnabled = matchContentEnabled
         self.panelIsInHDRMode = panelIsInHDRMode
         self.attemptsHDRMasterOnUnprovenPanel = attemptsHDRMasterOnUnprovenPanel
@@ -1062,7 +1097,8 @@ public enum VideoFormat: Sendable, Equatable {
 public enum DolbyVisionConversion: Sendable, Equatable {
     /// Dual-layer Profile 7 rewritten per packet to single-layer Profile 8.1, on every display (a display
     /// without Dolby Vision gets the RPU-driven tone map a Profile 8.1 gets). The enhancement layer is
-    /// discarded: a MEL carries next to nothing, a FEL loses its refinement.
+    /// discarded: a MEL carries next to nothing, and a FEL played on this route loses its refinement (a FEL
+    /// on the software dual-layer route keeps it).
     case profile7ToProfile81
 }
 
diff --git a/Sources/AetherEngine/Video/CodecRoutePolicy.swift b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
index e7b890bf0..8dc051511 100644
--- a/Sources/AetherEngine/Video/CodecRoutePolicy.swift
+++ b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
@@ -651,7 +651,11 @@ extension HLSVideoEngine {
                 dvVariant: dvVariant
             )
         case .profile7:
-            // P7 dual-layer (UHD-BD): convert the RPU P7 -> P8.1 per packet (DoviRpuConverter, libdovi
+            // P7 dual-layer (UHD-BD). With preferDualLayerDolbyVision on and the box able to afford it,
+            // VideoRoutingPolicy sends a FEL to the software dual-layer route instead (SoftwarePlaybackHost +
+            // DualLayerVideoDecoder), which keeps the enhancement layer; every other P7 load lands here.
+            //
+            // Native route: convert the RPU P7 -> P8.1 per packet (DoviRpuConverter, libdovi
             // mode 2), drop the EL, rewrite the container dvcC to P8.1, and from there on serve exactly
             // what a P8.1 source is served, on every display. The way mpv treats Profile 7 without an EL
             // decoder: base layer plus RPU, never the bare base layer.
diff --git a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
index 386de2e58..d6dcc6b9f 100644
--- a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
+++ b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
@@ -232,6 +232,45 @@ public enum DolbyVisionRecordAudit {
         return nil
     }
 
+    /// Walks the first video packets of an open demuxer for the first RPU of a Profile 7 source and reads
+    /// its enhancement-layer type ("FEL" or "MEL"). nil when no packet in the budget carries one.
+    ///
+    /// Takes the session's own probe demuxer, so the packets read here are packets the caller must not
+    /// need afterwards: the caller seeks it back or opens another. The same packet and byte ceilings as
+    /// `rpuProfile(walking:)` apply, for the same reason (audit BIT-2, BIT-103).
+    static func probeEnhancementLayerType(
+        demuxer: Demuxer, streamIndex: Int32, packetBudget: Int = auditPacketBudget,
+        byteBudget: Int64 = Int64(walkByteBudget)
+    ) -> String? {
+        guard let stream = demuxer.stream(at: streamIndex) else { return nil }
+        let codecpar = stream.pointee.codecpar
+        let framing = A53SEIParser.nalFraming(
+            codec: .hevc, extradata: codecpar?.pointee.extradata,
+            size: Int(codecpar?.pointee.extradata_size ?? 0))
+
+        demuxer.beginInputByteBudget(byteBudget)
+        defer { demuxer.endInputByteBudget() }
+
+        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 == streamIndex else { continue }
+            walked += 1
+            if let type = DoviRpuConverter.enhancementLayerType(packet, framing: framing) { return type }
+        }
+        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
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
index 1218db350..34d0d0327 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
@@ -487,9 +487,7 @@ extension HLSVideoEngine {
         guard Self.configRecordNeedsInBandRebuild(extradata, size: extradataSize) else { return nil }
         let naluLengthSize = 4   // the predicate above already required it
 
-        var vps: [UInt8]?
-        var sps: [UInt8]?
-        var pps: [UInt8]?
+        var sets = VideoConfigRecord.HEVCParameterSets()
         // Counted in VIDEO packets: a film interleaves audio and dozens of subtitle tracks, which
         // would otherwise exhaust the budget before the first video packet.
         let packetBudget = 16
@@ -501,55 +499,19 @@ extension HLSVideoEngine {
             if pkt.pointee.stream_index != videoStreamIndex { return false }
             packetsScanned += 1
             guard let pktData = pkt.pointee.data else { return packetsScanned >= packetBudget }
-            let pktSize = Int(pkt.pointee.size)
-
-            var offset = 0
-            while offset + naluLengthSize <= pktSize {
-                var nalLen = 0
-                for i in 0..<naluLengthSize {
-                    nalLen = (nalLen << 8) | Int(pktData[offset + i])
-                }
-                offset += naluLengthSize
-                if nalLen == 0 || offset + nalLen > pktSize { break }
-                let nalType = (Int(pktData[offset]) >> 1) & 0x3F  // HEVC NAL type: bits 1..6 of byte 0
-                let nalBytes = Array(UnsafeBufferPointer(start: pktData + offset, count: nalLen))
-                switch nalType {
-                case 32: if vps == nil { vps = nalBytes }
-                case 33: if sps == nil { sps = nalBytes }
-                case 34: if pps == nil { pps = nalBytes }
-                default: break
-                }
-                offset += nalLen
-            }
-
-            return (vps != nil && sps != nil && pps != nil) || packetsScanned >= packetBudget
+            sets.collect(from: pktData, size: Int(pkt.pointee.size), naluLengthSize: naluLengthSize)
+            return sets.isComplete || packetsScanned >= packetBudget
         }
 
-        guard let vps, let sps, let pps else {
+        guard let vps = sets.vps, let sps = sets.sps, let pps = sets.pps else {
             EngineLog.emit(
                 "[HLSVideoEngine] in-band parameter-set scan found none: "
-                + "packets=\(packetsScanned) vps=\(vps != nil) sps=\(sps != nil) pps=\(pps != nil)",
+                + "packets=\(packetsScanned) vps=\(sets.vps != nil) sps=\(sets.sps != nil) pps=\(sets.pps != nil)",
                 category: .session
             )
             return nil
         }
-
-        // Assemble hvcC: keep source 22-byte header, set numOfArrays=3, append VPS/SPS/PPS arrays (1-byte type, 2-byte numNalus=1, 2-byte nalUnitLength, NAL bytes).
-        var hvcC: [UInt8] = []
-        hvcC.reserveCapacity(22 + 1 + 5 * 3 + vps.count + sps.count + pps.count)
-        for i in 0..<22 { hvcC.append(extradata[i]) }
-        hvcC.append(3)
-        func appendArray(nalUnitType: UInt8, nal: [UInt8]) {
-            hvcC.append(0x80 | (nalUnitType & 0x3F))
-            hvcC.append(0); hvcC.append(1)
-            let nl = UInt16(nal.count)
-            hvcC.append(UInt8(nl >> 8)); hvcC.append(UInt8(nl & 0xFF))
-            hvcC.append(contentsOf: nal)
-        }
-        appendArray(nalUnitType: 32, nal: vps)
-        appendArray(nalUnitType: 33, nal: sps)
-        appendArray(nalUnitType: 34, nal: pps)
-        return hvcC
+        return VideoConfigRecord.hevcRecord(header: extradata, vps: vps, sps: sps, pps: pps)
     }
 
     /// Shows the packets at the head of the source to `inspect`, which returns true once it has seen
diff --git a/Sources/AetherEngine/Video/VTCapabilityProbe.swift b/Sources/AetherEngine/Video/VTCapabilityProbe.swift
index 5187c9c1f..b91f208e6 100644
--- a/Sources/AetherEngine/Video/VTCapabilityProbe.swift
+++ b/Sources/AetherEngine/Video/VTCapabilityProbe.swift
@@ -68,6 +68,13 @@ enum VTCapabilityProbe {
         return hardwareDecodeVerdict(codecpar: codecpar).keepsNativeRoute
     }
 
+    /// Strict form of the gate for routes that need a PROVEN hardware session, such as the dual-layer path:
+    /// `.unclassifiable` is false here, unlike `canHardwareDecode`, because `SoftwarePlaybackHost` would
+    /// hand an unclassifiable stream to libavcodec.
+    static func opensHardwareDecoder(codecpar: UnsafePointer<AVCodecParameters>) -> Bool {
+        hardwareDecodeVerdict(codecpar: codecpar).opensHardwareDecoder
+    }
+
     /// The throwaway session is invalidated immediately; the whole probe costs well under a millisecond and
     /// runs once per consult.
     static func hardwareDecodeVerdict(codecpar: UnsafePointer<AVCodecParameters>) -> HardwareDecodeVerdict {
diff --git a/Sources/AetherEngine/Video/VideoConfigRecord+InBand.swift b/Sources/AetherEngine/Video/VideoConfigRecord+InBand.swift
new file mode 100644
index 000000000..c18526e4b
--- /dev/null
+++ b/Sources/AetherEngine/Video/VideoConfigRecord+InBand.swift
@@ -0,0 +1,140 @@
+import Foundation
+import AetherLibavcodec
+import AetherLibavformat
+import AetherLibavutil
+
+/// HEVC sources whose parameter sets live in-band (`hev1` written with `xps_inband`, the common
+/// Dolby Vision MP4 recipes) ship an hvcC with `numOfArrays = 0`. AVPlayer reads the parameter sets
+/// out of the samples, but every consumer that builds a format description from the record alone
+/// cannot: the hardware-decode probe, `HardwareVideoDecoder`, and the dual-layer decoder's
+/// picture-order seed. The native path rebuilds the record for its init.mp4 (#19); these helpers are
+/// that rebuild, shared, plus an in-place completion of the demuxer's own record for the
+/// software route.
+extension VideoConfigRecord {
+
+    /// The VPS / SPS / PPS an in-band scan collects, first of each.
+    struct HEVCParameterSets {
+        var vps: [UInt8]?
+        var sps: [UInt8]?
+        var pps: [UInt8]?
+
+        var isComplete: Bool { vps != nil && sps != nil && pps != nil }
+
+        /// Walk one length-prefixed packet and keep the first VPS / SPS / PPS seen. Only top-level
+        /// NAL units count: a Profile 7 enhancement layer's parameter sets travel inside `unspec63`
+        /// (type 63) wrappers and are never mistaken for the base layer's.
+        mutating func collect(from data: UnsafePointer<UInt8>, size: Int, naluLengthSize: Int = 4) {
+            var offset = 0
+            while offset + naluLengthSize <= size {
+                var nalLen = 0
+                for i in 0..<naluLengthSize {
+                    nalLen = (nalLen << 8) | Int(data[offset + i])
+                }
+                offset += naluLengthSize
+                if nalLen == 0 || offset + nalLen > size { break }
+                let nalType = (Int(data[offset]) >> 1) & 0x3F  // HEVC NAL type: bits 1..6 of byte 0
+                switch nalType {
+                case 32 where vps == nil: vps = Array(UnsafeBufferPointer(start: data + offset, count: nalLen))
+                case 33 where sps == nil: sps = Array(UnsafeBufferPointer(start: data + offset, count: nalLen))
+                case 34 where pps == nil: pps = Array(UnsafeBufferPointer(start: data + offset, count: nalLen))
+                default: break
+                }
+                offset += nalLen
+            }
+        }
+    }
+
+    /// The source record's 22-byte header with `numOfArrays = 3` and one array each for the VPS,
+    /// SPS and PPS (1-byte type, 2-byte numNalus = 1, 2-byte nalUnitLength, NAL bytes).
+    static func hevcRecord(header: UnsafePointer<UInt8>, vps: [UInt8], sps: [UInt8], pps: [UInt8]) -> [UInt8] {
+        var hvcC: [UInt8] = []
+        hvcC.reserveCapacity(22 + 1 + 5 * 3 + vps.count + sps.count + pps.count)
+        for i in 0..<22 { hvcC.append(header[i]) }
+        hvcC.append(3)
+        func appendArray(nalUnitType: UInt8, nal: [UInt8]) {
+            hvcC.append(0x80 | (nalUnitType & 0x3F))
+            hvcC.append(0); hvcC.append(1)
+            let nl = UInt16(nal.count)
+            hvcC.append(UInt8(nl >> 8)); hvcC.append(UInt8(nl & 0xFF))
+            hvcC.append(contentsOf: nal)
+        }
+        appendArray(nalUnitType: 32, nal: vps)
+        appendArray(nalUnitType: 33, nal: sps)
+        appendArray(nalUnitType: 34, nal: pps)
+        return hvcC
+    }
+
+    /// Replace a video stream's empty hvcC with one rebuilt from the parameter sets at the head of the
+    /// source, so the hardware-decode verdict and `HardwareVideoDecoder` see the record AVPlayer would
+    /// have reconstructed for itself. Returns true when the record was replaced.
+    ///
+    /// Seekable sources only: the scan reads from the head and seeks back to 0, which is where every
+    /// caller starts playback from anyway (the start position is applied later). A forward-only
+    /// source is left alone, and keeps today's route. Runs off the main actor; it reads packets.
+    @discardableResult
+    static func completeHEVCRecordFromInBandParameterSets(demuxer: Demuxer, streamIndex: Int32) -> Bool {
+        // Stream access goes through `withStream`, never a pointer held across the packet reads: a
+        // stop() closes the demuxer from another thread and frees its streams.
+        let needsRebuild = demuxer.withStream(at: streamIndex) { stream -> Bool in
+            guard let par = stream.pointee.codecpar,
+                  par.pointee.codec_id == AV_CODEC_ID_HEVC,
+                  let extradata = par.pointee.extradata else { return false }
+            return HLSVideoEngine.configRecordNeedsInBandRebuild(extradata, size: Int(par.pointee.extradata_size))
+        } ?? false
+        guard needsRebuild, demuxer.isSourceSeekable else { return false }
+
+        // Same budgets as the native rebuild: parameter sets are guaranteed at the first IRAP.
+        let packetBudget = 16
+        let readBudget = 512
+        var sets = HEVCParameterSets()
+        var videoPackets = 0
+        var packetsRead = 0
+        demuxer.seek(to: 0)
+        while packetsRead < readBudget, videoPackets < packetBudget, !sets.isComplete {
+            guard let pkt = try? demuxer.readPacket() else { break }
+            var toFree: UnsafeMutablePointer<AVPacket>? = pkt
+            defer { trackedPacketFree(&toFree) }
+            packetsRead += 1
+            guard pkt.pointee.stream_index == streamIndex else { continue }
+            videoPackets += 1
+            if let data = pkt.pointee.data {
+                sets.collect(from: data, size: Int(pkt.pointee.size))
+            }
+        }
+        demuxer.seek(to: 0)
+
+        guard let vps = sets.vps, let sps = sets.sps, let pps = sets.pps else {
+            EngineLog.emit(
+                "[VideoConfigRecord] in-band parameter-set scan found none: packets=\(videoPackets) "
+                + "vps=\(sets.vps != nil) sps=\(sets.sps != nil) pps=\(sets.pps != nil)",
+                category: .engine
+            )
+            return false
+        }
+        let installed = demuxer.withStream(at: streamIndex) { stream -> (Int32, Int)? in
+            guard let par = stream.pointee.codecpar,
+                  let extradata = par.pointee.extradata,
+                  HLSVideoEngine.configRecordNeedsInBandRebuild(extradata, size: Int(par.pointee.extradata_size))
+            else { return nil }
+            let record = hevcRecord(header: extradata, vps: vps, sps: sps, pps: pps)
+            let pad = Int(AV_INPUT_BUFFER_PADDING_SIZE)
+            guard let buf = av_malloc(record.count + pad) else { return nil }
+            let typed = buf.assumingMemoryBound(to: UInt8.self)
+            record.withUnsafeBufferPointer { src in
+                if let base = src.baseAddress { memcpy(typed, base, record.count) }
+            }
+            memset(typed + record.count, 0, pad)
+            let oldSize = par.pointee.extradata_size
+            av_freep(&par.pointee.extradata)
+            par.pointee.extradata = typed
+            par.pointee.extradata_size = Int32(record.count)
+            return (oldSize, record.count)
+        } ?? nil
+        guard let (oldSize, newSize) = installed else { return false }
+        EngineLog.emit(
+            "[VideoConfigRecord] completed hvcC from in-band parameter sets: \(oldSize) B → \(newSize) B",
+            category: .engine
+        )
+        return true
+    }
+}
diff --git a/Tests/AetherEngineTests/DocumentedConstantsTests.swift b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
index 2746947a4..866572d99 100644
--- a/Tests/AetherEngineTests/DocumentedConstantsTests.swift
+++ b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
@@ -45,6 +45,63 @@ final class DocumentedConstantsTests: XCTestCase {
         assertDocumented("within **64 pictures**", docs)
     }
 
+    func testDualLayerRouteBudgetMatchesDocumentation() throws {
+        let fel = try felDocument()
+        XCTAssertEqual(DualLayerRouteDecision.maximumPixelsPerSecond, 311_040_000)
+        XCTAssertEqual(DualLayerRouteDecision.assumedFrameRate, 24)
+        XCTAssertEqual(DualLayerRouteDecision.assumedEnhancementLayerAreaFraction, 0.25)
+        assertDocumented("311.04 Mpx/s", fel)
+        assertDocumented("UHD\n3840x2160 at 30 fps plus a 1920x1080 enhancement layer at 30 fps", fel)
+        assertDocumented("an unknown frame rate is budgeted as 24", fel)
+        assertDocumented("A 24p UHD FEL master needs 80% of the budget", fel)
+    }
+
+    func testDualLayerPipelineBoundsMatchDocumentation() throws {
+        let docs = try documentation()
+        let fel = try felDocument()
+        XCTAssertEqual(DualLayerVideoDecoder.maxLayerSkewFrames, 3)
+        XCTAssertEqual(DualLayerVideoDecoder.maxEnhancementLayerQueueFrames, 10)
+        XCTAssertEqual(FrameSideDataRing.capacity, 32)
+        XCTAssertEqual(FrameSideDataRing.jitterToleranceTicks, 300)
+        XCTAssertEqual(DoviFelComposer.maxFramesInFlight, 3)
+        XCTAssertEqual(SampleBufferRenderer.felVideoLookaheadFrames, 9)
+        XCTAssertEqual(DoviFelComposer.outputPoolAllocationThreshold, 15)
+        XCTAssertEqual(DoviFelComposer.outputPoolReserve, 3)
+        XCTAssertEqual(DualLayerVideoDecoder.maxBorrowedParamsRun, 3)
+        XCTAssertEqual(SampleBufferRenderer.hardwareDecoderReorderDepth, 4)
+        XCTAssertEqual(DualLayerVideoDecoder.settledKeyMemory, 64)
+        XCTAssertEqual(DualLayerVideoDecoder.summaryIntervalSeconds, 1.0)
+        // About 36 ms: ten attempts with a sleep between each pair.
+        XCTAssertEqual(Double(DoviFelComposer.outputPoolAttempts - 1) * DoviFelComposer.outputPoolRetryInterval,
+                       0.036, accuracy: 1e-9)
+
+        assertDocumented("once K = 3 newer base-layer", fel)
+        assertDocumented("is the maximum layer skew, 3;", fel)
+        assertDocumented("waiting enhancement frames capped at 10", fel)
+        assertDocumented("At most 10 enhancement frames wait", fel)
+        assertDocumented("fixed capacity 32", fel)
+        assertDocumented("within ±300 ticks", fel)
+        assertDocumented("wait for one of 3 in-flight slots", fel)
+        assertDocumented("look-ahead (9)", fel)
+        assertDocumented("the in-flight slots (3) + 1, so 15", fel)
+        assertDocumented("a reserve of 3 more", fel)
+        assertDocumented("allocation threshold 15 + reserve 3", fel)
+        assertDocumented("`maxBorrowedParamsRun` (3)", fel)
+        assertDocumented("the renderer's 4-frame reorder buffer", fel)
+        assertDocumented("last 64\n  settled base-layer keys", fel)
+        assertDocumented("for at most about 36 ms", fel)
+        assertDocumented("Counters feed a 1 Hz summary", fel)
+        _ = docs
+    }
+
+    private func felDocument() throws -> String {
+        let url = Self.repoRoot.appendingPathComponent("docs/dolby-vision-fel.md")
+        guard let text = try? String(contentsOf: url, encoding: .utf8) else {
+            throw XCTSkip("running outside a source checkout; no docs to check against")
+        }
+        return text
+    }
+
     // MARK: - Documentation corpus
 
     private static var repoRoot: URL {
@@ -345,4 +402,11 @@ final class DocumentedConstantsTests: XCTestCase {
         else { throw XCTSkip("running outside a source checkout; no sources to check against") }
         return text
     }
+
+    // MARK: - Picture-order pairing (docs/dolby-vision-fel.md §5.3)
+
+    func testPictureOrderPairingBoundMatchesDocumentation() throws {
+        XCTAssertEqual(DualLayerPictureAlignment.maxSlotDistance, 16)
+        assertDocumented("more than 16 slots off its unit", try felDocument())
+    }
 }
diff --git a/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift b/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift
new file mode 100644
index 000000000..233cbb465
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift
@@ -0,0 +1,633 @@
+import Testing
+import CoreMedia
+import CoreVideo
+import Foundation
+import AetherLibavformat
+@_spi(Diagnostics) @testable import AetherEngine
+
+/// Edge cases of the Profile 7 FEL dual-layer route that the other `DualLayer*` suites do not pin:
+/// a residual that switches off and on mid-title, unclassifiable first RPUs, damaged or late enhancement
+/// layers, the pixel-rate budget at its boundary, 1001-based timebases, and seeks that land on 0, on a
+/// replayed range, or in a burst. Everything is synthetic: tagged pixel buffers into the frame handlers,
+/// a recording composer, no media and no GPU.
+@Suite(.serialized, .timeLimit(.minutes(1)))
+struct DualLayerEdgeCaseTests {
+
+    // MARK: - Fixtures
+
+    private static func buffer(width: Int, height: Int) -> CVPixelBuffer? {
+        var out: CVPixelBuffer?
+        let status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
+                                         kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                                         [kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary] as CFDictionary,
+                                         &out)
+        return status == kCVReturnSuccess ? out : nil
+    }
+
+    private static func baseLayer() throws -> CVPixelBuffer { try #require(buffer(width: 64, height: 64)) }
+    private static func enhancementLayer() throws -> CVPixelBuffer { try #require(buffer(width: 32, height: 32)) }
+
+    private static func params() -> DoviMetalParams {
+        var p = DoviMetalParams()
+        p.blWidth = 64; p.blHeight = 64; p.elWidth = 32; p.elHeight = 32
+        return p
+    }
+
+    /// 23.976 fps exactly: frame n at n * 1001 / 24000 s.
+    private static func pts2397(_ frame: Int64) -> CMTime { CMTime(value: frame * 1001, timescale: 24000) }
+    /// 24 fps at 90 kHz.
+    private static func pts(_ frame: Int64) -> CMTime { CMTime(value: frame * 3750, timescale: 90000) }
+
+    private struct Pair { let base: CVPixelBuffer; let enhancement: CVPixelBuffer; let flags: DoviComposerFlags }
+
+    /// Completes every composition at once with the base buffer and records what it was asked to compose.
+    private final class RecordingComposer: FelComposing, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _pairs: [Pair] = []
+        private var _flushes = 0
+        var pairs: [Pair] { lock.lock(); defer { lock.unlock() }; return _pairs }
+        var flushCount: Int { lock.lock(); defer { lock.unlock() }; return _flushes }
+        func acquireSlot() {}
+        func releaseSlot() {}
+        func flush() { lock.lock(); _flushes += 1; lock.unlock() }
+        func composeAsync(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer, params: DoviMetalParams,
+                          frameIndex: UInt32, completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            composeAsyncWithAcquiredSlot(baseBuffer: baseBuffer, enhancementBuffer: enhancementBuffer,
+                                         params: params, frameIndex: frameIndex, completion: completion)
+        }
+        func composeAsyncWithAcquiredSlot(baseBuffer: CVPixelBuffer, enhancementBuffer: CVPixelBuffer,
+                                          params: DoviMetalParams, frameIndex: UInt32,
+                                          completion: @escaping @Sendable (CVPixelBuffer?) -> Void) {
+            lock.lock()
+            _pairs.append(Pair(base: baseBuffer, enhancement: enhancementBuffer, flags: params.flags))
+            lock.unlock()
+            completion(baseBuffer)
+        }
+    }
+
+    /// A VideoToolbox session stand-in that only counts flushes.
+    private final class FakeSession: SingleLayerVideoDecoder, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _flushes = 0
+        var flushCount: Int { lock.lock(); defer { lock.unlock() }; return _flushes }
+        var onFrame: DecodedFrameHandler?
+        var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+        var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+        var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+        var skipUntilPTS: CMTime?
+        var feedEpoch: UInt64 = 0
+        func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {}
+        func open(parameterSets: [[UInt8]], timeBase: AVRational,
+                  onFrame: @escaping DecodedFrameHandler) throws {}
+        func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?) {}
+        func flush() { lock.lock(); _flushes += 1; lock.unlock() }
+        func close() {}
+    }
+
+    private final class Deliveries: @unchecked Sendable {
+        struct Frame { let buffer: CVPixelBuffer; let pts: CMTime; let afterMarker: Bool }
+        private let lock = NSLock()
+        private var frames: [Frame] = []
+        private var marker = false
+        func record(_ buffer: CVPixelBuffer, _ pts: CMTime) {
+            lock.lock(); frames.append(Frame(buffer: buffer, pts: pts, afterMarker: marker)); lock.unlock()
+        }
+        func setMarker() { lock.lock(); marker = true; lock.unlock() }
+        var all: [Frame] { lock.lock(); defer { lock.unlock() }; return frames }
+        var afterMarker: [Frame] { all.filter(\.afterMarker) }
+        var count: Int { lock.lock(); defer { lock.unlock() }; return frames.count }
+    }
+
+    private struct Rig {
+        let decoder: DualLayerVideoDecoder
+        let composer: RecordingComposer
+        let primary: FakeSession
+        let enhancement: FakeSession
+        let deliveries: Deliveries
+    }
+
+    private static func rig() -> Rig {
+        let composer = RecordingComposer()
+        let primary = FakeSession(), enhancement = FakeSession()
+        let deliveries = Deliveries()
+        let decoder = DualLayerVideoDecoder(composer: composer, primaryDecoder: primary,
+                                            enhancementDecoder: enhancement)
+        decoder.onFrame = { buffer, pts, _ in deliveries.record(buffer, pts) }
+        decoder.primeForTesting(enhancementLayer: true)
+        return Rig(decoder: decoder, composer: composer, primary: primary, enhancement: enhancement,
+                   deliveries: deliveries)
+    }
+
+    private static func settle() async throws {
+        try await waitFor(upTo: .milliseconds(300)) { false }
+    }
+
+    private static func isStrictlyIncreasing(_ frames: [Deliveries.Frame]) -> Bool {
+        zip(frames, frames.dropFirst()).allSatisfy { CMTimeCompare($0.pts, $1.pts) < 0 }
+    }
+
+    // MARK: - 1. Residual switches off and on mid-title
+
+    @Test("an RPU that disables the residual mid-title composes base-only for those frames, FEL resumes after, nothing fails")
+    func residualDisabledMidTitleThenResumes() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        var noResidual = Self.params(); noResidual.flags.insert(.disableResidual)
+        // Frames 3...5 carry an RPU with no NLQ (what a FEL to P8-shaped switch looks like to the kernel).
+        let count = 9
+        var bases: [CVPixelBuffer] = []
+        for i in 0..<count {
+            let residualOff = (3...5).contains(i)
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)),
+                                        params: residualOff ? noResidual : Self.params(),
+                                        displayMetadataNAL: nil)
+            let bl = try Self.baseLayer(), el = try Self.enhancementLayer()
+            bases.append(bl)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { r.deliveries.count == count }
+
+        let pairs = r.composer.pairs
+        #expect(pairs.count == count, "every frame still goes through the composer, which does the base-only mapping")
+        for (i, base) in bases.enumerated() {
+            let flags = pairs.first { $0.base === base }?.flags
+            #expect(flags?.contains(.disableResidual) == (3...5).contains(i), "frame \(i)")
+        }
+        #expect(r.composer.pairs.allSatisfy { CVPixelBufferGetWidth($0.enhancement) == 32 }, "the EL is paired, the kernel flag decides")
+        #expect(r.decoder.composedFrameCount == count, "no composition failed")
+        #expect(r.decoder.streamClassificationForTesting == .fel, "no route change")
+        #expect(r.decoder.engagesEnhancementLayerForTesting())
+        let state = r.decoder.stateSnapshotForTesting
+        #expect(state.enhancementEngaged && state.blQueueCount == 0 && state.elQueueCount == 0)
+        #expect(Self.isStrictlyIncreasing(r.deliveries.all))
+    }
+
+    // MARK: - 2. MEL, and a title whose first RPUs say nothing
+
+    @Test("MEL and an unclassified el_type each log one line naming the reason and the native-route fallback")
+    func melAndUnknownLogLines() {
+        func decide(elType: String?, geometry: DualLayerRouteDecision.Geometry? = nil) -> DualLayerRouteDecision {
+            DualLayerRouteDecision.decide(
+                codecID: AV_CODEC_ID_HEVC, dvProfile: 7, dolbyVisionHandling: .automatic,
+                preferDualLayerDolbyVision: true, isLive: false, isSourceSeekable: true,
+                canHardwareDecode: { true }, elType: elType,
+                geometry: geometry ?? .init(width: 3840, height: 2160, frameRate: 24000.0 / 1001.0))
+        }
+        #expect(decide(elType: "MEL").logLine
+                == "[AetherEngine] DV P7 dual-layer route: not taken (el_type=MEL, nothing to compose), keeps the native route (8.1 where the display takes Dolby Vision)")
+        #expect(decide(elType: nil).logLine
+                == "[AetherEngine] DV P7 dual-layer route: not taken (el_type unknown, no enhancement layer classified in the first RPU), keeps the native route (8.1 where the display takes Dolby Vision)")
+        // The el_type is judged before the budget, so a MEL or unclassified 4K60 still says MEL / unknown:
+        // the budget only ever speaks about FEL.
+        let uhd60 = DualLayerRouteDecision.Geometry(width: 3840, height: 2160, frameRate: 60)
+        #expect(decide(elType: "MEL", geometry: uhd60) == .notTaken(.melEnhancementLayer))
+        #expect(decide(elType: nil, geometry: uhd60) == .notTaken(.enhancementLayerTypeUnknown))
+    }
+
+    @Test("first RPUs that cannot be classified leave the stream undetermined and the base layer playing; the first definitive RPU then decides")
+    func unclassifiableFirstRPUsThenFEL() async throws {
+        let decoder = DualLayerVideoDecoder(composer: RecordingComposer())
+        let deliveries = Deliveries()
+        decoder.onFrame = { buffer, pts, _ in deliveries.record(buffer, pts) }
+        defer { decoder.close() }
+        let undetermined = DoviRpuConverter.DualLayerPacketResult(
+            elPacket: nil, rpuData: nil, rpuParams: nil, isFEL: false, isMEL: false, success: false)
+        for _ in 0..<5 { decoder.classifyPacketResultForTesting(undetermined) }
+        #expect(decoder.streamClassificationForTesting == .undetermined)
+        #expect(!decoder.engagesEnhancementLayerForTesting())
+
+        // Undetermined means no enhancement decoder: frames are delivered as their base layer.
+        let bl = try Self.baseLayer()
+        decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(0), hdr10Data: nil)
+        try await waitFor { deliveries.count == 1 }
+        #expect(deliveries.all.first?.buffer === bl)
+
+        let fel = DoviRpuConverter.DualLayerPacketResult(
+            elPacket: nil, rpuData: nil, rpuParams: nil, isFEL: true, isMEL: false, success: true)
+        decoder.classifyPacketResultForTesting(fel)
+        #expect(decoder.streamClassificationForTesting == .fel)
+        #expect(decoder.engagesEnhancementLayerForTesting())
+    }
+
+    // MARK: - 3. Damaged, missing and late enhancement layers
+
+    @Test("an enhancement layer missing for some base-layer frames costs those frames their residual, in order, with bounded waiting; pairing recovers")
+    func missingEnhancementLayersMidStream() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        let missing: Set<Int> = [3, 7, 8]
+        let count = 12
+        var bases: [CVPixelBuffer] = [], enhancements: [Int: CVPixelBuffer] = [:]
+        for i in 0..<count {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            let bl = try Self.baseLayer()
+            bases.append(bl)
+            if !missing.contains(i) {
+                let el = try Self.enhancementLayer()
+                enhancements[i] = el
+                r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            }
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+            let s = r.decoder.stateSnapshotForTesting
+            #expect(s.blQueueCount <= DualLayerVideoDecoder.maxLayerSkewFrames, "the wait for a missing EL is bounded")
+        }
+        try await waitFor { r.deliveries.count == count }
+        let delivered = r.deliveries.all
+        #expect(Self.isStrictlyIncreasing(delivered), "no frame lost, none out of order")
+        let pairs = r.composer.pairs
+        #expect(pairs.count == count - missing.count)
+        for pair in pairs {
+            let i = try #require(bases.firstIndex { $0 === pair.base })
+            #expect(pair.enhancement === enhancements[i], "frame \(i) paired with its own picture's EL")
+        }
+        for i in missing { #expect(!pairs.contains { $0.base === bases[i] }, "frame \(i) goes out as its base layer") }
+        #expect(r.decoder.stateSnapshotForTesting.blQueueCount == 0)
+    }
+
+    @Test("a long run of undecodable enhancement-layer frames (longer than the skew bound) neither deadlocks nor poisons the frames after it")
+    func longEnhancementLayerOutage() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        let outage = 2..<10
+        let count = 14
+        var bases: [CVPixelBuffer] = [], enhancements: [Int: CVPixelBuffer] = [:]
+        for i in 0..<count {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            let bl = try Self.baseLayer()
+            bases.append(bl)
+            if !outage.contains(i) {
+                let el = try Self.enhancementLayer()
+                enhancements[i] = el
+                r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+            }
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { r.deliveries.count == count }
+        #expect(Self.isStrictlyIncreasing(r.deliveries.all))
+        let pairs = r.composer.pairs
+        #expect(pairs.count == count - outage.count)
+        for pair in pairs {
+            let i = try #require(bases.firstIndex { $0 === pair.base })
+            #expect(pair.enhancement === enhancements[i])
+        }
+        let s = r.decoder.stateSnapshotForTesting
+        #expect(s.blQueueCount == 0 && s.elQueueCount == 0)
+    }
+
+    @Test("an enhancement layer that arrives within the skew bound after its base layer still pairs; frames keep their order")
+    func lateEnhancementLayerWithinBound() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        let k = DualLayerVideoDecoder.maxLayerSkewFrames
+        var bases: [CVPixelBuffer] = [], enhancements: [CVPixelBuffer] = []
+        for i in 0..<k {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            let bl = try Self.baseLayer()
+            bases.append(bl)
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        #expect(r.decoder.stateSnapshotForTesting.blQueueCount == k, "k-1 newer frames have arrived: nothing is released early")
+        for i in 0..<k {
+            let el = try Self.enhancementLayer()
+            enhancements.append(el)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+        }
+        try await waitFor { r.deliveries.count == k }
+        let pairs = r.composer.pairs
+        #expect(pairs.count == k)
+        #expect(zip(pairs, zip(bases, enhancements)).allSatisfy { $0.base === $1.0 && $0.enhancement === $1.1 })
+        #expect(Self.isStrictlyIncreasing(r.deliveries.all))
+    }
+
+    @Test("an enhancement layer that arrives after its base layer was released is dropped, not queued, and the next frames pair normally")
+    func enhancementLayerLaterThanBoundIsDropped() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        let k = DualLayerVideoDecoder.maxLayerSkewFrames
+        var bases: [CVPixelBuffer] = []
+        // Frames 0...k arrive with no EL: frame 0 is released as its base layer on frame k's arrival.
+        for i in 0...k {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            let bl = try Self.baseLayer()
+            bases.append(bl)
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { r.deliveries.count == 1 }
+        #expect(r.deliveries.all.first?.buffer === bases[0])
+
+        let lateEL = try Self.enhancementLayer()
+        r.decoder.handleEnhancementLayerFrame(elBuffer: lateEL, pts: Self.pts(0))
+        #expect(r.decoder.stateSnapshotForTesting.elQueueCount == 0, "a stale EL is not held")
+
+        var enhancements: [CVPixelBuffer] = []
+        for i in 1...k {
+            let el = try Self.enhancementLayer()
+            enhancements.append(el)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(i)))
+        }
+        try await waitFor { r.deliveries.count == k + 1 }
+        let pairs = r.composer.pairs
+        #expect(pairs.count == k)
+        #expect(pairs.allSatisfy { $0.enhancement !== lateEL })
+        #expect(zip(pairs, zip(bases.dropFirst(), enhancements)).allSatisfy { $0.base === $1.0 && $0.enhancement === $1.1 })
+        #expect(Self.isStrictlyIncreasing(r.deliveries.all))
+
+        // And the pipeline keeps going.
+        let bl = try Self.baseLayer(), el = try Self.enhancementLayer()
+        r.decoder.seedRPUForTesting(pts: Self.pts(Int64(k + 1)), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(k + 1)), hdr10Data: nil)
+        r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(Int64(k + 1)))
+        try await waitFor { r.deliveries.count == k + 2 }
+        #expect(r.composer.pairs.last?.base === bl && r.composer.pairs.last?.enhancement === el)
+    }
+
+    // MARK: - 4. The real-time budget
+
+    private typealias Geometry = DualLayerRouteDecision.Geometry
+
+    private func decide(_ geometry: Geometry, elSize: (width: Int, height: Int)? = nil) -> DualLayerRouteDecision {
+        DualLayerRouteDecision.decide(
+            codecID: AV_CODEC_ID_HEVC, dvProfile: 7, dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true, isLive: false, isSourceSeekable: true,
+            canHardwareDecode: { true }, elType: "FEL", geometry: geometry, enhancementLayerSize: elSize)
+    }
+
+    @Test("4K at 23.976, 24, 25, 29.97 and 30 is accepted", arguments: [24000.0 / 1001.0, 24.0, 25.0, 30000.0 / 1001.0, 30.0])
+    func uhdAcceptedRates(rate: Double) {
+        let decision = decide(Geometry(width: 3840, height: 2160, frameRate: rate))
+        guard case let .taken(_, _, fraction) = decision else {
+            Issue.record("UHD at \(rate) fps should be inside the budget: \(decision)"); return
+        }
+        #expect(fraction <= 1.0)
+    }
+
+    @Test("4K at 50, 59.94 and 60 is refused cleanly, with the fallback named in the line",
+          arguments: [50.0, 60000.0 / 1001.0, 60.0])
+    func uhdRefusedRates(rate: Double) throws {
+        let decision = decide(Geometry(width: 3840, height: 2160, frameRate: rate))
+        guard case let .notTaken(.overBudget(required, _)) = decision else {
+            Issue.record("UHD at \(rate) fps should be over budget: \(decision)"); return
+        }
+        #expect(required > DualLayerRouteDecision.maximumPixelsPerSecond)
+        let line = try #require(decision.logLine)
+        #expect(line.hasPrefix("[AetherEngine] DV P7 dual-layer route: not taken (over the real-time budget"))
+        #expect(line.hasSuffix("keeps the native route (8.1 where the display takes Dolby Vision)"))
+        #expect(!decision.isTaken)
+    }
+
+    @Test("an unknown base-layer size is refused with its own reason, after MEL and unknown el_type")
+    func unknownGeometryFailsClosed() {
+        for geometry in [Geometry(width: 0, height: 0, frameRate: nil), Geometry(width: 3840, height: 0, frameRate: 24),
+                         Geometry(width: -1, height: 2160, frameRate: 24)] {
+            let decision = decide(geometry)
+            #expect(decision == .notTaken(.geometryUnknown))
+            #expect(decision.logLine == "[AetherEngine] DV P7 dual-layer route: not taken (base-layer size unknown), keeps the native route (8.1 where the display takes Dolby Vision)")
+            for elType in ["MEL", nil] as [String?] {
+                let other = DualLayerRouteDecision.decide(
+                    codecID: AV_CODEC_ID_HEVC, dvProfile: 7, dolbyVisionHandling: .automatic,
+                    preferDualLayerDolbyVision: true, isLive: false, isSourceSeekable: true,
+                    canHardwareDecode: { true }, elType: elType, geometry: geometry)
+                #expect(other == .notTaken(elType == nil ? .enhancementLayerTypeUnknown : .melEnhancementLayer))
+            }
+        }
+    }
+
+    @Test("the budget is a closed bound: exactly 311.04 Mpx/s is in, the next representable rate above it is out")
+    func exactBudgetBoundary() {
+        // 1080p with the assumed quarter-area EL needs 2073600 * 1.25 * fps: exactly the budget at 120 fps.
+        let atLimit = Geometry(width: 1920, height: 1080, frameRate: 120)
+        #expect(DualLayerRouteDecision.requiredPixelsPerSecond(geometry: atLimit) == DualLayerRouteDecision.maximumPixelsPerSecond)
+        #expect(decide(atLimit).isTaken)
+        #expect(decide(Geometry(width: 1920, height: 1080, frameRate: 120.0.nextUp)) == .notTaken(.overBudget(
+            requiredPixelsPerSecond: DualLayerRouteDecision.requiredPixelsPerSecond(
+                geometry: Geometry(width: 1920, height: 1080, frameRate: 120.0.nextUp)),
+            geometry: Geometry(width: 1920, height: 1080, frameRate: 120.0.nextUp))))
+        // The same bound reached with the EL stated 1:1 (two full 1080p layers) at 75 fps.
+        let fullEL = (width: 1920, height: 1080)
+        let at75 = Geometry(width: 1920, height: 1080, frameRate: 75)
+        #expect(DualLayerRouteDecision.requiredPixelsPerSecond(geometry: at75, enhancementLayerSize: fullEL)
+                == DualLayerRouteDecision.maximumPixelsPerSecond)
+        #expect(decide(at75, elSize: fullEL).isTaken)
+        #expect(!decide(Geometry(width: 1920, height: 1080, frameRate: 75.0.nextUp), elSize: fullEL).isTaken)
+    }
+
+    @Test("an enhancement layer at full resolution (1:1) doubles the need: UHD24 is refused, UHD at 15 fps is the 1:1 limit")
+    func fullResolutionEnhancementLayer() {
+        let uhd = Geometry(width: 3840, height: 2160, frameRate: 24)
+        #expect(decide(uhd).isTaken, "the assumed quarter-area EL fits at 24 fps")
+        #expect(!decide(uhd, elSize: (3840, 2160)).isTaken, "398 Mpx/s needed")
+        let uhd15 = Geometry(width: 3840, height: 2160, frameRate: 15)
+        #expect(decide(uhd15, elSize: (3840, 2160)).isTaken)
+        // An EL smaller than a quarter makes more room, never less.
+        #expect(DualLayerRouteDecision.requiredPixelsPerSecond(geometry: uhd, enhancementLayerSize: (960, 540))
+                < DualLayerRouteDecision.requiredPixelsPerSecond(geometry: uhd))
+    }
+
+    @Test("odd and non-UHD sizes are budgeted by their exact pixel count, not rounded to a tier")
+    func oddSizes() {
+        // One pixel more than UHD on each axis at the 30 fps ceiling tips it over.
+        #expect(decide(Geometry(width: 3840, height: 2160, frameRate: 30)).isTaken)
+        #expect(!decide(Geometry(width: 3841, height: 2161, frameRate: 30)).isTaken)
+        // DCI 4K (4096x2160): in at 24, out at 30.
+        #expect(decide(Geometry(width: 4096, height: 2160, frameRate: 24)).isTaken)
+        #expect(!decide(Geometry(width: 4096, height: 2160, frameRate: 30)).isTaken)
+        let odd = Geometry(width: 1921, height: 1081, frameRate: 24)
+        #expect(DualLayerRouteDecision.requiredPixelsPerSecond(geometry: odd) == Double(1921 * 1081) * 1.25 * 24)
+        // The enhancement layer's own odd size is taken as stated.
+        #expect(DualLayerRouteDecision.requiredPixelsPerSecond(geometry: odd, enhancementLayerSize: (961, 541))
+                == Double(1921 * 1081 + 961 * 541) * 24)
+    }
+
+    // MARK: - 5. 23.976 against 24: 1001-based timebases
+
+    @Test("canonical keys of 23.976 frames in 1/24000, 1001/24000, 1/1000 and 1/90000 timebases never get within the jitter of a neighbour, and agree across timebases")
+    func timebaseKeysAt2397() {
+        let tolerance = FrameSideDataRing.jitterToleranceTicks
+        let timebases: [(AVRational, (Int64) -> Int64)] = [
+            (AVRational(num: 1, den: 24000), { $0 * 1001 }),
+            (AVRational(num: 1001, den: 24000), { $0 }),
+            (AVRational(num: 1, den: 1000), { Int64((Double($0) * 1001.0 / 24.0).rounded()) }),
+            (AVRational(num: 1, den: 90000), { Int64((Double($0) * 3753.75).rounded()) }),
+        ]
+        let frames: Int64 = 86_400  // one hour of 23.976
+        var previous = [Int64](repeating: Int64.min, count: timebases.count)
+        for n in 0..<frames {
+            let keys = timebases.map { DualLayerVideoDecoder.canonicalKey(rawPTS: $0.1(n), timeBase: $0.0) }
+            for (i, key) in keys.enumerated() {
+                if n > 0 {
+                    let gap = key - previous[i]
+                    guard gap > 2 * tolerance else {
+                        Issue.record("timebase \(i): frames \(n - 1) and \(n) are only \(gap) ticks apart"); return
+                    }
+                }
+                previous[i] = key
+            }
+            // The same frame stamped in a coarser or finer timebase still pairs.
+            for k in keys.dropFirst() where !FrameSideDataRing.isWithinJitter(keys[0], k) {
+                Issue.record("frame \(n): keys \(keys) differ by more than the pairing jitter"); return
+            }
+        }
+        // The exact 1001 grid is 3753.75 ticks per frame: rounding gives only 3753 or 3754 spacing.
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: 1001, timeBase: AVRational(num: 1, den: 24000)) == 3754)
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: 2002, timeBase: AVRational(num: 1, den: 24000)) == 7508)
+        #expect(DualLayerVideoDecoder.canonicalKey(rawPTS: 3003, timeBase: AVRational(num: 1, den: 24000)) == 11261)
+    }
+
+    @Test("at 23.976 a seek realigns on the right picture: an early neighbour's enhancement layer is never paired with the base layer, even stamped in milliseconds")
+    func seekRealignmentAt2397() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        // Pre-seek: a later stretch, left half-paired.
+        for i in 100..<103 {
+            r.decoder.handleEnhancementLayerFrame(elBuffer: try Self.enhancementLayer(), pts: Self.pts2397(Int64(i)))
+        }
+        r.decoder.handleBaseLayerFrame(baseBuffer: try Self.baseLayer(), pts: Self.pts2397(103), hdr10Data: nil)
+        r.decoder.flush()
+        r.deliveries.setMarker()
+
+        // Seek back to frame 50. The EL decoder ran ahead: frame 51's EL (in ms, as a 1/1000 stream would
+        // stamp it) comes before frame 50's base layer.
+        func ms(_ frame: Int64) -> CMTime { CMTime(value: Int64((Double(frame) * 1001.0 / 24.0).rounded()), timescale: 1000) }
+        var bases: [CVPixelBuffer] = [], enhancements: [CVPixelBuffer] = []
+        for i in 50..<56 {
+            r.decoder.seedRPUForTesting(pts: Self.pts2397(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            bases.append(try Self.baseLayer()); enhancements.append(try Self.enhancementLayer())
+        }
+        r.decoder.handleEnhancementLayerFrame(elBuffer: enhancements[1], pts: ms(51))
+        r.decoder.handleBaseLayerFrame(baseBuffer: bases[0], pts: Self.pts2397(50), hdr10Data: nil)
+        r.decoder.handleEnhancementLayerFrame(elBuffer: enhancements[0], pts: ms(50))
+        for i in 1..<6 {
+            if i != 1 { r.decoder.handleEnhancementLayerFrame(elBuffer: enhancements[i], pts: ms(Int64(50 + i))) }
+            r.decoder.handleBaseLayerFrame(baseBuffer: bases[i], pts: Self.pts2397(Int64(50 + i)), hdr10Data: nil)
+        }
+        try await waitFor { r.deliveries.afterMarker.count == 6 }
+        let delivered = r.deliveries.afterMarker
+        #expect(CMTimeCompare(try #require(delivered.first).pts, Self.pts2397(50)) == 0, "the first picture after the seek is the target picture, not its neighbour")
+        #expect(zip(delivered, bases).allSatisfy { $0.buffer === $1 })
+        #expect(delivered.enumerated().allSatisfy { CMTimeCompare($0.element.pts, Self.pts2397(Int64(50 + $0.offset))) == 0 })
+        let pairs = r.composer.pairs
+        #expect(pairs.count == 6)
+        for pair in pairs {
+            let i = try #require(bases.firstIndex { $0 === pair.base })
+            #expect(pair.enhancement === enhancements[i], "frame \(50 + i) paired with another frame's EL (off by one)")
+        }
+    }
+
+    // MARK: - 6. Seek edge cases
+
+    @Test("a seek back to 0 replays timestamps the pre-seek run already settled, and they pair: nothing is dropped as stale")
+    func seekBackToZero() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        // Play the first frames from the start, as a fresh load does.
+        for i in 0..<4 {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: try Self.enhancementLayer(), pts: Self.pts(Int64(i)))
+            r.decoder.handleBaseLayerFrame(baseBuffer: try Self.baseLayer(), pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { r.deliveries.count == 4 }
+        // Seek away and back to the beginning (two flushes), then replay with the EL first.
+        r.decoder.flush()
+        r.decoder.flush()
+        r.deliveries.setMarker()
+        var bases: [CVPixelBuffer] = []
+        for i in 0..<4 {
+            r.decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+            let bl = try Self.baseLayer()
+            bases.append(bl)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: try Self.enhancementLayer(), pts: Self.pts(Int64(i)))
+            r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(Int64(i)), hdr10Data: nil)
+        }
+        try await waitFor { r.deliveries.afterMarker.count == 4 }
+        let after = r.deliveries.afterMarker
+        #expect(after.first?.pts == .zero, "the picture at time 0 is delivered")
+        #expect(zip(after, bases).allSatisfy { $0.buffer === $1 })
+        #expect(r.composer.pairs.count == 8, "all eight frames, both passes, were composed")
+        #expect(r.decoder.composedFrameCount == 8)
+    }
+
+    @Test("a seek next to the end of the file composes the last pair, and the end-of-stream flush leaves a clean, repeatable state")
+    func seekNearEndOfFile() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        let last: Int64 = 172_000  // ~2 h at 24 fps
+        r.decoder.flush()          // the seek
+        r.deliveries.setMarker()
+        for i in (last - 1)...last {
+            r.decoder.seedRPUForTesting(pts: Self.pts(i), params: Self.params(), displayMetadataNAL: nil)
+            r.decoder.handleBaseLayerFrame(baseBuffer: try Self.baseLayer(), pts: Self.pts(i), hdr10Data: nil)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: try Self.enhancementLayer(), pts: Self.pts(i))
+        }
+        try await waitFor { r.deliveries.afterMarker.count == 2 }
+        #expect(CMTimeCompare(try #require(r.deliveries.afterMarker.last).pts, Self.pts(last)) == 0)
+        r.decoder.flush()
+        r.decoder.flush()
+        let s = r.decoder.stateSnapshotForTesting
+        #expect(s.blQueueCount == 0 && s.elQueueCount == 0 && s.rpuCacheCount == 0 && !s.draining)
+        #expect(r.primary.flushCount == 3 && r.enhancement.flushCount == 3 && r.composer.flushCount == 3)
+    }
+
+    @Test("a scrub burst of seeks flushes both sessions and the composer every time, and only the last position's frames come out")
+    func scrubBurst() async throws {
+        let r = Self.rig()
+        defer { r.decoder.close() }
+        let seeks = 40
+        let epoch = r.decoder.feedEpoch
+        for s in 0..<seeks {
+            let base = Int64(s * 1000)
+            // Each position leaves a base layer waiting for its EL and an EL waiting for its base layer.
+            r.decoder.seedRPUForTesting(pts: Self.pts(base), params: Self.params(), displayMetadataNAL: nil)
+            r.decoder.handleBaseLayerFrame(baseBuffer: try Self.baseLayer(), pts: Self.pts(base), hdr10Data: nil)
+            r.decoder.handleEnhancementLayerFrame(elBuffer: try Self.enhancementLayer(), pts: Self.pts(base + 7))
+            r.decoder.flush()
+        }
+        r.deliveries.setMarker()
+        #expect(r.decoder.feedEpoch == epoch + UInt64(seeks))
+        #expect(r.primary.flushCount == seeks && r.enhancement.flushCount == seeks && r.composer.flushCount == seeks)
+        let drained = r.decoder.stateSnapshotForTesting
+        #expect(drained.blQueueCount == 0 && drained.elQueueCount == 0 && drained.rpuCacheCount == 0)
+
+        // The landing position: a stray EL from the previous position's key space must not pair.
+        let landing = Int64(seeks * 1000)
+        let bl = try Self.baseLayer(), el = try Self.enhancementLayer()
+        r.decoder.seedRPUForTesting(pts: Self.pts(landing), params: Self.params(), displayMetadataNAL: nil)
+        r.decoder.handleEnhancementLayerFrame(elBuffer: el, pts: Self.pts(landing))
+        r.decoder.handleBaseLayerFrame(baseBuffer: bl, pts: Self.pts(landing), hdr10Data: nil)
+        try await waitFor { r.deliveries.afterMarker.count == 1 }
+        try await Self.settle()
+        let after = r.deliveries.afterMarker
+        #expect(after.count == 1 && after.first?.buffer === bl)
+        #expect(r.composer.pairs.count == 1 && r.composer.pairs.first?.enhancement === el)
+    }
+
+    // MARK: - 7. Display without Dolby Vision
+
+    @Test("the three route gates take no display input and agree for a FEL P7 title, so a non-DV display does not change the route today")
+    func routeGatesIgnoreTheDisplay() {
+        // `DualLayerRouteDecision.decide`, `VideoRoutingPolicy.requiresSoftwarePath` and
+        // `SoftwarePlaybackHost.shouldUseDualLayerDecoder` have no `DisplayCapabilities` parameter:
+        // the load decides the route from the stream, the options and the decoder capability only.
+        let decision = decide(Geometry(width: 3840, height: 2160, frameRate: 24000.0 / 1001.0))
+        let software = VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: true,
+            dvProfile: 7, dolbyVisionHandling: .automatic, preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true }, elType: "FEL")
+        let dual = SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic)
+        #expect(decision.isTaken && software && dual)
+        // And they fall back together.
+        let melDecision = DualLayerRouteDecision.decide(
+            codecID: AV_CODEC_ID_HEVC, dvProfile: 7, dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true, isLive: false, isSourceSeekable: true,
+            canHardwareDecode: { true }, elType: "MEL",
+            geometry: Geometry(width: 3840, height: 2160, frameRate: 24))
+        #expect(!melDecision.isTaken)
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: true,
+            dvProfile: 7, dolbyVisionHandling: .automatic, preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true }, elType: "MEL"))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "MEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic))
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift b/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift
new file mode 100644
index 000000000..864da889a
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift
@@ -0,0 +1,56 @@
+import Testing
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// The documented audio trade-off of the Profile 7 FEL dual-layer route (`LoadOptions.preferDualLayerDolbyVision`):
+/// the route runs on `SoftwarePlaybackHost`, whose audio is always its own `AudioDecoder` (FFmpeg to PCM,
+/// through the sample-buffer audio renderer), never AVPlayer. An E-AC-3 track therefore plays as its channel
+/// bed, without Atmos objects; on the native route the same track is AVPlayer-decodable and would keep them.
+///
+/// There is no pure "audio route" function to test: the software host does not choose per codec, it opens
+/// `AudioDecoder` for whatever stream it resolved. So the claim is pinned in three pieces: the FEL route is the
+/// software host, the native route would hand E-AC-3 to AVPlayer, and the software host's decoder accepts E-AC-3.
+@Suite("Dual-layer route audio: E-AC-3 is decoded by the software host, not AVPlayer")
+struct DualLayerRouteAudioTests {
+
+    @Test("a Profile 7 FEL source with the preference on takes the software host; without it, it stays native")
+    func felRouteIsTheSoftwareHost() {
+        func requiresSoftware(prefer: Bool) -> Bool {
+            VideoRoutingPolicy.requiresSoftwarePath(
+                codecID: AV_CODEC_ID_HEVC, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: true,
+                dvProfile: 7, dolbyVisionHandling: .automatic,
+                preferDualLayerDolbyVision: prefer, canHardwareDecode: { true }, elType: "FEL")
+        }
+        #expect(requiresSoftware(prefer: true))
+        #expect(!requiresSoftware(prefer: false))
+    }
+
+    @Test("E-AC-3 is an AVPlayer-native codec, so only the software host's own decode path explains the core-only audio")
+    func eac3IsNativeToAVPlayer() {
+        #expect(AetherEngine.avPlayerCanDecodeAudio(AV_CODEC_ID_EAC3))
+    }
+
+    @Test("the software host's AudioDecoder opens an E-AC-3 stream and the delivery is the host's own decode")
+    func softwareHostDecodesEAC3Itself() throws {
+        let formatContext = avformat_alloc_context()
+        defer { avformat_free_context(formatContext) }
+        let stream = try #require(avformat_new_stream(formatContext, nil))
+        let codecpar = try #require(stream.pointee.codecpar)
+        codecpar.pointee.codec_type = AVMEDIA_TYPE_AUDIO
+        codecpar.pointee.codec_id = AV_CODEC_ID_EAC3
+        codecpar.pointee.sample_rate = 48_000
+        av_channel_layout_default(&codecpar.pointee.ch_layout, 6)
+        stream.pointee.time_base = AVRational(num: 1, den: 48_000)
+
+        let decoder = AudioDecoder()
+        defer { decoder.close() }
+        try decoder.open(stream: stream)
+        #expect(decoder.sampleRate == 48_000)
+        #expect(decoder.channels == 6)
+
+        #expect(SoftwarePlaybackHost.audioDelivery(
+            resolvedAudioIndex: stream.pointee.index, decoderOpened: true, sourceCarriesAudio: true) == .decoded)
+    }
+}
diff --git a/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift b/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift
new file mode 100644
index 000000000..90d81005f
--- /dev/null
+++ b/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift
@@ -0,0 +1,213 @@
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// The Profile 7 dual-layer route is FEL only and capability gated: MEL, an unclassified enhancement
+/// layer, a box without a hardware HEVC decoder and a stream too heavy to decode twice in real time all
+/// keep the native route, and the load logs one line saying which. These tests hold every exit of that decision.
+@Suite("Dual-layer route decision")
+struct DualLayerRouteDecisionTests {
+
+    private typealias Geometry = DualLayerRouteDecision.Geometry
+    private let uhd24 = Geometry(width: 3840, height: 2160, frameRate: 24000.0 / 1001.0)
+
+    private func decide(
+        codec: AVCodecID = AV_CODEC_ID_HEVC, profile: Int? = 7,
+        handling: DolbyVisionHandling = .automatic, prefer: Bool = true,
+        live: Bool = false, seekable: Bool = true, hardware: (() -> Bool)? = { true },
+        elType: String? = "FEL", geometry: Geometry? = nil
+    ) -> DualLayerRouteDecision {
+        DualLayerRouteDecision.decide(
+            codecID: codec, dvProfile: profile, dolbyVisionHandling: handling,
+            preferDualLayerDolbyVision: prefer, isLive: live, isSourceSeekable: seekable,
+            canHardwareDecode: hardware, elType: elType, geometry: geometry ?? uhd24)
+    }
+
+    @Test("a 24p UHD FEL source on a capable box takes the route and logs the budget it uses")
+    func felTakesTheRoute() {
+        let decision = decide()
+        #expect(decision.isTaken)
+        #expect(decision.logLine == "[AetherEngine] DV P7 dual-layer route: taken (el_type=FEL, 3840x2160@23.976, budget 80%)")
+    }
+
+    @Test("MEL never takes the route, with the flag on")
+    func melNeverTakesTheRoute() {
+        let decision = decide(prefer: true, elType: "MEL")
+        #expect(decision == .notTaken(.melEnhancementLayer))
+        #expect(decision.logLine?.contains("el_type=MEL") == true)
+        #expect(decision.logLine?.hasSuffix("keeps the native route (8.1 where the display takes Dolby Vision)") == true)
+    }
+
+    @Test("an enhancement layer the probe could not classify does not take the route")
+    func unknownElTypeDoesNotTakeTheRoute() {
+        #expect(decide(elType: nil) == .notTaken(.enhancementLayerTypeUnknown))
+        #expect(decide(elType: "other") == .notTaken(.enhancementLayerTypeUnknown))
+    }
+
+    @Test("every other exit names its reason")
+    func everyExitHasItsReason() {
+        #expect(decide(prefer: false) == .notTaken(.preferenceOff))
+        #expect(decide(handling: .baseLayerOnly) == .notTaken(.baseLayerOnlyHandling))
+        #expect(decide(live: true) == .notTaken(.liveOrNotSeekable))
+        #expect(decide(seekable: false) == .notTaken(.liveOrNotSeekable))
+        #expect(decide(hardware: { false }) == .notTaken(.noHardwareHEVC))
+        #expect(decide(profile: 8) == .notTaken(.notProfile7))
+        #expect(decide(profile: nil) == .notTaken(.notProfile7))
+        #expect(decide(codec: AV_CODEC_ID_H264) == .notTaken(.notProfile7))
+    }
+
+    @Test("a missing hardware verdict assumes hardware decode, as the routing policy does")
+    func nilHardwareVerdictAssumesHardware() {
+        #expect(decide(hardware: nil).isTaken)
+    }
+
+    @Test("a source that is not Profile 7 logs nothing; every Profile 7 outcome logs exactly one line")
+    func onlyProfile7LogsALine() {
+        #expect(decide(profile: 8).logLine == nil)
+        #expect(decide(codec: AV_CODEC_ID_H264, prefer: false).logLine == nil)
+        let reasons = [
+            decide(prefer: false), decide(handling: .baseLayerOnly), decide(live: true),
+            decide(hardware: { false }), decide(elType: "MEL"), decide(elType: nil),
+            decide(geometry: Geometry(width: 3840, height: 2160, frameRate: 60)),
+        ]
+        for decision in reasons {
+            guard let line = decision.logLine else {
+                Issue.record("a Profile 7 fallback must log its reason: \(decision)")
+                continue
+            }
+            #expect(line.hasPrefix("[AetherEngine] DV P7 dual-layer route: not taken ("))
+            #expect(!line.contains("\n"))
+        }
+        #expect(decide(prefer: false).logLine?.contains("preferDualLayerDolbyVision is off") == true)
+        #expect(decide(handling: .baseLayerOnly).logLine?.contains("HDR10 base layer") == true)
+    }
+
+    // MARK: - Real-time budget
+
+    @Test("the budget is UHD at 30 fps plus a 1080p enhancement layer at 30 fps")
+    func budgetConstant() {
+        #expect(DualLayerRouteDecision.maximumPixelsPerSecond == 311_040_000)
+    }
+
+    @Test("the budget boundary: UHD at 30 fps is exactly in, a hair above it is out")
+    func budgetBoundary() {
+        let atLimit = decide(geometry: Geometry(width: 3840, height: 2160, frameRate: 30))
+        #expect(atLimit.logLine?.contains("budget 100%") == true)
+        let justOver = decide(geometry: Geometry(width: 3840, height: 2160, frameRate: 30.01))
+        guard case .notTaken(.overBudget) = justOver else {
+            Issue.record("30.01 fps UHD should exceed the budget, got \(justOver)")
+            return
+        }
+        #expect(decide(geometry: Geometry(width: 3840, height: 2160, frameRate: 29.97)).isTaken)
+    }
+
+    @Test("UHD at 60 fps and 8K at 24 fps are over budget and say how far")
+    func heavyStreamsFallBack() {
+        let uhd60 = decide(geometry: Geometry(width: 3840, height: 2160, frameRate: 60))
+        #expect(uhd60.logLine == "[AetherEngine] DV P7 dual-layer route: not taken (over the real-time budget, 3840x2160@60 needs 200% of it), keeps the native route (8.1 where the display takes Dolby Vision)")
+        let uhd8k = decide(geometry: Geometry(width: 7680, height: 4320, frameRate: 24))
+        #expect(!uhd8k.isTaken)
+    }
+
+    @Test("an unknown frame rate is budgeted at 24 and the line says so")
+    func unknownFrameRateAssumes24() {
+        let decision = decide(geometry: Geometry(width: 3840, height: 2160, frameRate: nil))
+        #expect(decision.logLine == "[AetherEngine] DV P7 dual-layer route: taken (el_type=FEL, 3840x2160@24 (assumed), budget 80%)")
+        let nonsense = Geometry(width: 3840, height: 2160, frameRate: -1)
+        #expect(nonsense.effectiveFrameRate == 24)
+    }
+
+    @Test("the enhancement layer is a quarter of the base layer's area unless the stream says otherwise")
+    func enhancementLayerSize() {
+        let geometry = Geometry(width: 3840, height: 2160, frameRate: 30)
+        let assumed = DualLayerRouteDecision.requiredPixelsPerSecond(geometry: geometry)
+        #expect(assumed == DualLayerRouteDecision.maximumPixelsPerSecond)
+        let fullSize = DualLayerRouteDecision.requiredPixelsPerSecond(
+            geometry: geometry, enhancementLayerSize: (3840, 2160))
+        #expect(fullSize > DualLayerRouteDecision.maximumPixelsPerSecond)
+    }
+
+    @Test("the el_type probe is only wanted when nothing rules the route out first")
+    func probeRunsOnlyWhenItCanChangeTheRoute() {
+        func blocked(codec: AVCodecID = AV_CODEC_ID_HEVC, profile: Int? = 7,
+                     handling: DolbyVisionHandling = .automatic, prefer: Bool = true,
+                     live: Bool = false, seekable: Bool = true,
+                     hardware: (() -> Bool)? = { true }) -> DualLayerRouteDecision.Reason? {
+            DualLayerRouteDecision.blockingReasonBeforeProbe(
+                codecID: codec, dvProfile: profile, dolbyVisionHandling: handling,
+                preferDualLayerDolbyVision: prefer, isLive: live, isSourceSeekable: seekable,
+                canHardwareDecode: hardware)
+        }
+        #expect(blocked() == nil)
+        #expect(blocked(prefer: false) != nil)
+        #expect(blocked(handling: .baseLayerOnly) != nil)
+        #expect(blocked(live: true) != nil)
+        #expect(blocked(seekable: false) != nil)
+        #expect(blocked(hardware: { false }) != nil)
+        #expect(blocked(profile: 8) != nil)
+    }
+
+    // MARK: - Reload of a custom source
+
+    /// A custom source's rebuild keeps the backend and el_type the session was loaded with, so a flip
+    /// of the flag on a Profile 7 session would be logged as applied and change nothing. It is refused
+    /// instead, before any teardown; URL sources re-run `load()` and are not.
+    @Test("flipping preferDualLayerDolbyVision on a custom Profile 7 session is refused, nothing else is")
+    func customSourceFlagFlipIsRefused() {
+        var off = LoadOptions()
+        off.preferDualLayerDolbyVision = false
+        var on = off
+        on.preferDualLayerDolbyVision = true
+        func refusal(custom: Bool, from: LoadOptions, to: LoadOptions, profile: Int?) -> SessionReloadRefusal? {
+            SessionOptionCorrection.dualLayerRouteRefusal(
+                isCustomSource: custom, current: from, proposed: to, dvProfile: profile)
+        }
+        #expect(refusal(custom: true, from: off, to: on, profile: 7) == .dualLayerRouteNeedsFreshLoad)
+        #expect(refusal(custom: true, from: on, to: off, profile: 7) == .dualLayerRouteNeedsFreshLoad)
+        // A URL source re-runs load(), a non-P7 source routes the same either way, an unchanged flag moves nothing.
+        #expect(refusal(custom: false, from: off, to: on, profile: 7) == nil)
+        #expect(refusal(custom: true, from: off, to: on, profile: 8) == nil)
+        #expect(refusal(custom: true, from: off, to: on, profile: nil) == nil)
+        #expect(refusal(custom: true, from: on, to: on, profile: 7) == nil)
+        #expect(!SessionReloadRefusal.dualLayerRouteNeedsFreshLoad.description.isEmpty)
+    }
+
+    /// The route needs `dolbyVisionHandling` `.automatic`, so on a custom Profile 7 session a handling
+    /// change that can turn the route on or off is refused like a flag flip. With the preference off the
+    /// handling cannot move the route and is not refused.
+    @Test("a dolbyVisionHandling change that can move the route on a custom Profile 7 session is refused")
+    func customSourceHandlingChangeIsRefused() {
+        var automatic = LoadOptions()
+        automatic.preferDualLayerDolbyVision = true
+        automatic.dolbyVisionHandling = .automatic
+        var baseOnly = automatic
+        baseOnly.dolbyVisionHandling = .baseLayerOnly
+        var offAutomatic = automatic
+        offAutomatic.preferDualLayerDolbyVision = false
+        var offBaseOnly = offAutomatic
+        offBaseOnly.dolbyVisionHandling = .baseLayerOnly
+        func refusal(custom: Bool = true, from: LoadOptions, to: LoadOptions, profile: Int? = 7) -> SessionReloadRefusal? {
+            SessionOptionCorrection.dualLayerRouteRefusal(
+                isCustomSource: custom, current: from, proposed: to, dvProfile: profile)
+        }
+        #expect(refusal(from: automatic, to: baseOnly) == .dualLayerRouteNeedsFreshLoad)
+        #expect(refusal(from: baseOnly, to: automatic) == .dualLayerRouteNeedsFreshLoad)
+        // The preference is off on both sides: the route is not taken either way.
+        #expect(refusal(from: offAutomatic, to: offBaseOnly) == nil)
+        // URL sources re-run load(), other profiles route the same, an unchanged handling moves nothing.
+        #expect(refusal(custom: false, from: automatic, to: baseOnly) == nil)
+        #expect(refusal(from: automatic, to: baseOnly, profile: 8) == nil)
+        #expect(refusal(from: automatic, to: automatic) == nil)
+    }
+
+    /// A fatal decode error is the decoder session's, reported once; only a stopped host drops it, a
+    /// seek in flight does not.
+    @Test("a session failure is admitted across a seek and dropped only by a stop")
+    func sessionFailureIgnoresSeekGeneration() {
+        #expect(SoftwareReadAdmission.admitsSessionFailure(stopRequested: false))
+        #expect(!SoftwareReadAdmission.admitsSessionFailure(stopRequested: true))
+        // The per-seek admission it replaces rejects the same event once a seek has opened.
+        #expect(!SoftwareReadAdmission.admits(readGeneration: 3, requestedGeneration: 4,
+                                              settledGeneration: 3, stopRequested: false))
+    }
+}
diff --git a/Tests/AetherEngineTests/InBandParameterSetRebuildTests.swift b/Tests/AetherEngineTests/InBandParameterSetRebuildTests.swift
index 14a6c7b1b..713d871bb 100644
--- a/Tests/AetherEngineTests/InBandParameterSetRebuildTests.swift
+++ b/Tests/AetherEngineTests/InBandParameterSetRebuildTests.swift
@@ -60,4 +60,60 @@ struct InBandParameterSetRebuildTests {
         #expect(record.count > 23)
         #expect(record[22] == 3, "numOfArrays must cover VPS, SPS and PPS")
     }
+
+    /// The Profile 7 FEL route needs a proven hardware session, which the strict verdict cannot give
+    /// an empty hvcC; the load completes the demuxer's own record so the route and the decoders see
+    /// what AVPlayer would have rebuilt.
+    @Test("Completing the record in place makes the strict verdict classifiable and rewinds",
+          .enabled(if: fixtureExists("hev1-inband-xps.mp4"),
+                   "run Scripts/fetch-fixtures.sh to generate the in-band xPS clip"),
+          .timeLimit(.minutes(1)))
+    func completionInPlace() throws {
+        let demuxer = Demuxer()
+        try demuxer.open(url: fixtureURL("hev1-inband-xps.mp4"), profile: .playback)
+        defer { demuxer.close() }
+        let videoIdx = demuxer.videoStreamIndex
+        let codecpar = try #require(demuxer.stream(at: videoIdx)?.pointee.codecpar)
+        #expect(VTCapabilityProbe.hardwareDecodeVerdict(codecpar: codecpar)
+                == .unclassifiable(reason: "in-band parameter sets"))
+
+        #expect(VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: demuxer, streamIndex: videoIdx))
+        #expect(codecpar.pointee.extradata_size > 23)
+        #expect(codecpar.pointee.extradata?[22] == 3)
+        #expect(VTCapabilityProbe.hardwareDecodeVerdict(codecpar: codecpar) != .unclassifiable(reason: "in-band parameter sets"))
+
+        // Back at the head: the next video packet is the opening keyframe.
+        var first: (key: Bool, pts: Int64)?
+        while first == nil, let pkt = try demuxer.readPacket() {
+            var toFree: UnsafeMutablePointer<AVPacket>? = pkt
+            defer { trackedPacketFree(&toFree) }
+            if pkt.pointee.stream_index == videoIdx {
+                first = ((pkt.pointee.flags & AV_PKT_FLAG_KEY) != 0, pkt.pointee.pts)
+            }
+        }
+        #expect(first?.key == true)
+        #expect(first?.pts == 0)
+
+        // A complete record is left alone.
+        #expect(!VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: demuxer, streamIndex: videoIdx))
+    }
+
+    /// A Profile 7 enhancement layer carries its own VPS / SPS / PPS inside `unspec63` NAL units;
+    /// only the base layer's top-level parameter sets may seed the base layer's record.
+    @Test("The collector keeps top-level parameter sets and skips enhancement-layer ones")
+    func collectorSkipsWrappedEnhancementLayerSets() {
+        func nal(_ bytes: [UInt8]) -> [UInt8] {
+            let n = bytes.count
+            return [UInt8(n >> 24), UInt8((n >> 16) & 0xFF), UInt8((n >> 8) & 0xFF), UInt8(n & 0xFF)] + bytes
+        }
+        // unspec63 header (0x7E 0x01) wrapping an EL SPS (0x42 0x01), then the BL's VPS, SPS, PPS.
+        let packet = nal([0x7E, 0x01, 0x42, 0x01, 0xEE])
+            + nal([0x40, 0x01, 0xA1]) + nal([0x42, 0x01, 0xB2]) + nal([0x44, 0x01, 0xC3])
+        var sets = VideoConfigRecord.HEVCParameterSets()
+        packet.withUnsafeBufferPointer { sets.collect(from: $0.baseAddress!, size: $0.count) }
+        #expect(sets.isComplete)
+        #expect(sets.vps == [0x40, 0x01, 0xA1])
+        #expect(sets.sps == [0x42, 0x01, 0xB2])
+        #expect(sets.pps == [0x44, 0x01, 0xC3])
+    }
 }
diff --git a/Tests/AetherEngineTests/LoadOptionsTests.swift b/Tests/AetherEngineTests/LoadOptionsTests.swift
index 6aa3e6590..19c353112 100644
--- a/Tests/AetherEngineTests/LoadOptionsTests.swift
+++ b/Tests/AetherEngineTests/LoadOptionsTests.swift
@@ -20,6 +20,8 @@ struct LoadOptionsTests {
         #expect(opts.audioBridgeMode == .surroundCompat)
         #expect(opts.isLive == false)
         #expect(opts.audioOnly == false)
+        // Dual-layer FEL composition is opt-in.
+        #expect(opts.preferDualLayerDolbyVision == false)
         // #68: probe-budget overrides default to nil so the engine keeps the
         // built-in .playback budget (50 MB / 60 s) unless a caller opts in.
         #expect(opts.probesize == nil)
diff --git a/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift b/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift
new file mode 100644
index 000000000..faa314d6e
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift
@@ -0,0 +1,172 @@
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+@Suite("SoftwarePlaybackHost decoder selection")
+struct SoftwareDecoderSelectionTests {
+
+    @MainActor
+    @Test("P7 FEL with default options keeps the base layer on HardwareVideoDecoder: dual-layer is opt-in")
+    func felDefaultIsOptIn() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+        #expect(host.dolbyVisionHandling == .automatic)
+        #expect(host.preferDualLayerDolbyVision == false)
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 7
+        )
+        #expect(decoder is HardwareVideoDecoder)
+    }
+
+    @MainActor
+    @Test("P7 FEL opted in selects DualLayerVideoDecoder")
+    func felOptedInSelectsDualLayer() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+        host.preferDualLayerDolbyVision = true
+        #expect(host.dolbyVisionHandling == .automatic)
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 7
+        )
+        #expect(decoder is DualLayerVideoDecoder)
+    }
+
+    @MainActor
+    @Test("P7 MEL selects HardwareVideoDecoder across all option combinations")
+    func melSelectsHardwareDecoder() {
+        let handlings: [DolbyVisionHandling] = [.automatic, .baseLayerOnly]
+        for handling in handlings {
+            for prefer in [true, false] {
+                let host = SoftwarePlaybackHost()
+                host.elType = "MEL"
+                host.dolbyVisionHandling = handling
+                host.preferDualLayerDolbyVision = prefer
+
+                let decoder = host.selectVideoDecoder(
+                    codecID: AV_CODEC_ID_HEVC,
+                    canHardwareDecode: true,
+                    dvProfile: 7
+                )
+                #expect(
+                    decoder is HardwareVideoDecoder,
+                    "MEL with handling=\(handling) prefer=\(prefer) must pick HardwareVideoDecoder"
+                )
+            }
+        }
+    }
+
+    @MainActor
+    @Test("P7 FEL with baseLayerOnly selects HardwareVideoDecoder")
+    func felBaseLayerOnlySelectsHardwareDecoder() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+        host.dolbyVisionHandling = .baseLayerOnly
+        host.preferDualLayerDolbyVision = true
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 7
+        )
+        #expect(decoder is HardwareVideoDecoder)
+    }
+
+    @MainActor
+    @Test("P7 FEL with preferDualLayerDolbyVision=false selects HardwareVideoDecoder")
+    func felPreferFalseSelectsHardwareDecoder() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+        host.dolbyVisionHandling = .automatic
+        host.preferDualLayerDolbyVision = false
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 7
+        )
+        #expect(decoder is HardwareVideoDecoder)
+    }
+
+    @MainActor
+    @Test("P7 without elType (nil) selects HardwareVideoDecoder")
+    func nilElTypeSelectsHardwareDecoder() {
+        let host = SoftwarePlaybackHost()
+        #expect(host.elType == nil)
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 7
+        )
+        #expect(decoder is HardwareVideoDecoder)
+    }
+
+    @MainActor
+    @Test("P8 or other DV profiles select HardwareVideoDecoder regardless of FEL settings")
+    func p8SelectsHardwareDecoder() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+        host.preferDualLayerDolbyVision = true
+        host.dolbyVisionHandling = .automatic
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 8
+        )
+        #expect(decoder is HardwareVideoDecoder)
+    }
+
+    @MainActor
+    @Test("Non-HEVC or unsupported hardware decode falls back to SoftwareVideoDecoder")
+    func nonHardwareFallback() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+
+        let av1Decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_AV1,
+            canHardwareDecode: true,
+            dvProfile: nil
+        )
+        #expect(av1Decoder is SoftwareVideoDecoder)
+
+        let noHwDecoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: false,
+            dvProfile: 7
+        )
+        #expect(noHwDecoder is SoftwareVideoDecoder)
+    }
+
+    @Test("SoftwarePlaybackHost.shouldUseDualLayerDecoder static predicate matches table")
+    func shouldUseDualLayerDecoderPredicate() {
+        // Section 5.2 table: only dvProfile == 7 && elType == "FEL" && preferDualLayerDolbyVision && .automatic
+        #expect(SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
+        ))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .baseLayerOnly
+        ))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: false, dolbyVisionHandling: .automatic
+        ))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "MEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
+        ))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: nil, preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
+        ))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 8, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
+        ))
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: nil, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
+        ))
+    }
+}
diff --git a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
index 770f28135..53220c78f 100644
--- a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
+++ b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
@@ -284,4 +284,252 @@ struct VideoRoutingPolicyTests {
                 codecID: codec, dvProfile: 10, dvBlCompatID: 0))
         }
     }
+
+    // MARK: - Profile 7 dual-layer routing & hardware capability gate
+
+    @Test("HEVC DV P7 routes to software for dual-layer Metal reconstruction when HW decode confirmed")
+    func dvProfile7RoutesToSoftwareWithHardwareDecode() {
+        #expect(VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true },
+            elType: "FEL"
+        ))
+    }
+
+    @Test("the el_type probe is only wanted when its answer can change the route")
+    func enhancementLayerProbeIsGated() {
+        func wanted(codec: AVCodecID = AV_CODEC_ID_HEVC, profile: Int? = 7,
+                    handling: DolbyVisionHandling = .automatic, prefer: Bool = true,
+                    hardware: (() -> Bool)? = { true }) -> Bool {
+            VideoRoutingPolicy.dualLayerRouteIsWanted(
+                codecID: codec, dvProfile: profile, dolbyVisionHandling: handling,
+                preferDualLayerDolbyVision: prefer, canHardwareDecode: hardware)
+        }
+        #expect(wanted())
+        #expect(!wanted(prefer: false), "not opted in: no probe")
+        #expect(!wanted(handling: .baseLayerOnly))
+        #expect(!wanted(hardware: { false }), "no proven hardware session: the host would not compose")
+        #expect(!wanted(profile: 8))
+        #expect(!wanted(profile: nil))
+        #expect(!wanted(codec: AV_CODEC_ID_H264))
+        // The probe's gate and the routing decision share one predicate: FEL routes exactly when it holds.
+        for prefer in [true, false] {
+            let routes = VideoRoutingPolicy.requiresSoftwarePath(
+                codecID: AV_CODEC_ID_HEVC, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: true,
+                dvProfile: 7, preferDualLayerDolbyVision: prefer, canHardwareDecode: { true }, elType: "FEL")
+            #expect(routes == wanted(prefer: prefer))
+        }
+    }
+
+    @Test("HEVC DV P7 FEL stays native when the caller does not opt in")
+    func dvProfile7FelStaysNativeByDefault() {
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            canHardwareDecode: { true },
+            elType: "FEL"
+        ))
+    }
+
+    @Test("HEVC DV P7 stays native when preferDualLayerDolbyVision is disabled")
+    func dvProfile7StaysNativeWhenPreferDualLayerDisabled() {
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: false,
+            canHardwareDecode: { true },
+            elType: "FEL"
+        ))
+    }
+
+    @Test("HEVC DV P7 stays native when hardware decode is unsupported")
+    func dvProfile7StaysNativeWhenHardwareUnsupported() {
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { false },
+            elType: "FEL"
+        ))
+    }
+
+    @Test("HEVC DV P7 FEL stays native when the hardware probe is unclassifiable")
+    func dvProfile7StaysNativeWhenProbeUnclassifiable() throws {
+        // No extradata: the probe has nothing to judge, so the verdict is .unclassifiable. The
+        // permissive gate keeps native for that; the strict one the FEL route uses must say no,
+        // because SoftwarePlaybackHost would give such a stream to libavcodec.
+        let par = try #require(avcodec_parameters_alloc())
+        defer { var p: UnsafeMutablePointer<AVCodecParameters>? = par; avcodec_parameters_free(&p) }
+        par.pointee.codec_id = AV_CODEC_ID_HEVC
+        par.pointee.width = 3840
+        par.pointee.height = 2160
+        guard case .unclassifiable = VTCapabilityProbe.hardwareDecodeVerdict(codecpar: par) else {
+            Issue.record("expected an unclassifiable verdict for a config record without extradata")
+            return
+        }
+        #expect(VTCapabilityProbe.canHardwareDecode(codecpar: par))
+        #expect(!VTCapabilityProbe.opensHardwareDecoder(codecpar: par))
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { VTCapabilityProbe.opensHardwareDecoder(codecpar: par) },
+            elType: "FEL"
+        ))
+    }
+
+    @Test("HEVC DV P7 stays native when dolbyVisionHandling is baseLayerOnly")
+    func dvProfile7StaysNativeWhenBaseLayerOnly() {
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .baseLayerOnly,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true },
+            elType: "FEL"
+        ))
+    }
+
+    // MARK: - Profile 7 FEL vs MEL routing
+
+    @Test("Profile 7 FEL / MEL table-driven routing matrix (dolby-vision-fel.md §5.2)")
+    func profile7RoutingMatrix() {
+        struct TestCase {
+            let elType: String?
+            let handling: DolbyVisionHandling
+            let preferDualLayer: Bool
+            let canHardwareDecode: Bool
+            let expectedSoftware: Bool
+        }
+
+        let elTypes: [String?] = ["FEL", "MEL", nil]
+        let handlings: [DolbyVisionHandling] = [.automatic, .baseLayerOnly]
+        let preferOptions = [true, false]
+        let hwOptions = [true, false]
+
+        var cases: [TestCase] = []
+        for el in elTypes {
+            for handling in handlings {
+                for prefer in preferOptions {
+                    for hw in hwOptions {
+                        // Section 5.2 table:
+                        // P7 FEL + .automatic + preferDualLayerDolbyVision (true) + HW decode -> software host
+                        // All other combinations -> native (false)
+                        let expected = (el == "FEL")
+                            && handling == .automatic
+                            && prefer
+                            && hw
+                        cases.append(TestCase(
+                            elType: el,
+                            handling: handling,
+                            preferDualLayer: prefer,
+                            canHardwareDecode: hw,
+                            expectedSoftware: expected
+                        ))
+                    }
+                }
+            }
+        }
+
+        #expect(cases.count == 24)
+
+        for c in cases {
+            let actual = VideoRoutingPolicy.requiresSoftwarePath(
+                codecID: AV_CODEC_ID_HEVC,
+                fieldOrder: AV_FIELD_PROGRESSIVE,
+                av1Available: true,
+                dvProfile: 7,
+                dolbyVisionHandling: c.handling,
+                preferDualLayerDolbyVision: c.preferDualLayer,
+                canHardwareDecode: { c.canHardwareDecode },
+                elType: c.elType
+            )
+            #expect(
+                actual == c.expectedSoftware,
+                "Failed for elType=\(String(describing: c.elType)), handling=\(c.handling), prefer=\(c.preferDualLayer), hw=\(c.canHardwareDecode): expected \(c.expectedSoftware), got \(actual)"
+            )
+        }
+    }
+
+    @Test("Profile 7 FEL routes to software when HW decode and dual-layer preferred")
+    func felRoutesToSoftware() {
+        #expect(VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true },
+            elType: "FEL"
+        ))
+    }
+
+    @Test("Profile 7 MEL stays native regardless of preferences")
+    func melStaysNativeAlways() {
+        // All combinations: each dolbyVisionHandling, preferDualLayerDolbyVision, hardware avail
+        for handling in [DolbyVisionHandling.automatic, .baseLayerOnly] {
+            for prefer in [true, false] {
+                for hardware in [true, false] {
+                    #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+                        codecID: AV_CODEC_ID_HEVC,
+                        fieldOrder: AV_FIELD_PROGRESSIVE,
+                        av1Available: true,
+                        dvProfile: 7,
+                        dolbyVisionHandling: handling,
+                        preferDualLayerDolbyVision: prefer,
+                        canHardwareDecode: { hardware },
+                        elType: "MEL"
+                    ),
+                    "MEL should stay native with handling=\(handling), prefer=\(prefer), hw=\(hardware)")
+                }
+            }
+        }
+    }
+
+    @Test("Profile 7 MEL ignores dolbyVisionHandling and prefer settings")
+    func melIgnoresOptions() {
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true },
+            elType: "MEL"
+        ))
+    }
+
+    @Test("Profile 7 no el_type stays native (docs §5.2: only explicit FEL routes software)")
+    func noElTypeStaysNative() {
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_HEVC,
+            fieldOrder: AV_FIELD_PROGRESSIVE,
+            av1Available: true,
+            dvProfile: 7,
+            dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true,
+            canHardwareDecode: { true },
+            elType: nil
+        ))
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index ceadecb95..a779d6d5e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -245,8 +245,9 @@ Two refusals, both raised BEFORE any teardown, so a refused correction leaves th
 | Thrown | When |
 | --- | --- |
 | `AetherEngineError.loadIdentityNotCorrectable(fields:)` | the closure changed `isLive`, `audioOnly`, `nativeRemoteHLS` or `sequentialOrigin`. These name the session rather than tune it (each opens the source on a different pipeline, and the engine writes the last two itself), so changing one is a different item, not a correction of this one. Load the source again. |
-| `AetherEngineError.sessionNotReloadable(_:)` | there is no session, or the source is a custom `IOReader` that reported itself non-seekable and cannot be reopened at the current position. It carries a `SessionReloadRefusal` (`.noActiveSession` / `.customSourceNotSeekable`) saying which. |
+| `AetherEngineError.sessionNotReloadable(_:)` | there is no session, or the source is a custom `IOReader` that reported itself non-seekable and cannot be reopened at the current position. It carries a `SessionReloadRefusal` (`.noActiveSession` / `.customSourceNotSeekable`, and from a correction also the refusals named under `reloadAtCurrentPosition(applying:)`) saying which. |
 | `AetherEngineError.sessionNotReloadable(.softwarePathCannotRepresentSource)` | the correction moves a native session onto the software path, and this source's only signal is IPT-PQ-c2 (Dolby Vision HEVC Profile 5, AV1 Profile 10.0). The software decoders hand that on as YCbCr, so the picture would render green/purple. |
+| `AetherEngineError.sessionNotReloadable(.dualLayerRouteNeedsFreshLoad)` | the correction changes `preferDualLayerDolbyVision` (or `dolbyVisionHandling` while the preference is on) on a custom `IOReader` Profile 7 session. The in-place rebuild keeps the route the session was loaded with, so the change could not take effect; call `load()` again with the new option. `SessionReloadRefusal` is a public enum: this is a new case, so a host that switches over it exhaustively must handle it (a `default:` or a new `case`). |
 | `AetherEngineError.sessionNotReloadable(.demuxedAudioLiveIsNativeOnly)` | the correction moves a demuxed-audio live session onto the software path, where the side-audio merge does not exist, so it would play silent. |
 
 Both are all-or-nothing: a correction refused for one field installs none of it.
@@ -1207,6 +1208,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). |
+| `preferDualLayerDolbyVision` | false | Opt in to composing Profile 7 FEL sources on the GPU instead of taking the native route (the single-layer 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where it does not). When true, `dolbyVisionHandling` is `.automatic`, the source is a seekable VOD, the first RPU says `el_type` FEL, VideoToolbox decodes HEVC in hardware and the stream fits the real-time budget (UHD at 30 fps for the base layer plus a 1080p enhancement layer; a 24p UHD master uses 80% of it), Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`: both layers decode in VideoToolbox, `DoviFelComposer` reconstructs the picture in Metal and delivers 10-bit P010, and every frame carries its RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, which tvOS applies as Dolby Vision display management. A Profile 7 MEL source, and anything the device cannot decode twice in real time, keeps the native route (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not; the conversion is lossless only for MEL); the load logs one `DV P7 dual-layer route: taken` / `not taken (<reason>)` line either way. What the route gives up against the native one (Picture in Picture, scrub thumbnails, subtitles, AirPlay) is listed in [dolby-vision-fel.md](dolby-vision-fel.md#523-what-the-route-gives-up-against-the-native-route). Known trade-off, audio: the route runs on the software host, whose audio is decoded by FFmpeg and played through the sample-buffer audio renderer, and on tvOS only AVPlayer emits Atmos objects, so an E-AC-3 (JOC) track plays as its channel-bed core (5.1 or 7.1) without the objects; TrueHD behaves as on the native route. The route does not consult the display: with the flag on and a display that does not take Dolby Vision, the route is still taken, the composed full-FEL picture is presented with its attached metadata, and how tvOS presents it is up to the platform (the native route would have played the HDR10 base layer there). The E-AC-3 Atmos trade-off above applies there too. A tuning field, correctable through `reloadAtCurrentPosition(applying:)` on a URL source (which re-runs `load()` and re-decides the route); on a custom `IOReader` source a Profile 7 session refuses a change of this option, or a change of `dolbyVisionHandling` while this option is on, with `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, because the in-place rebuild keeps the route the session was loaded with: call `load()` again with the new option. See [dolby-vision-fel.md](dolby-vision-fel.md). |
 | `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). |
 | `hostRetriesExhaustedLiveReplay` | `false` | The host owns the retry after a verified live replay exhausts the in-engine reopen: the engine publishes `liveSourceReplayExhausted` and holds production until `retryLiveSourceRecovery()`. `false` publishes `liveSourceReset` for the same exhaustion. |
 | `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. |
diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
new file mode 100644
index 000000000..c17f6a2a1
--- /dev/null
+++ b/docs/dolby-vision-fel.md
@@ -0,0 +1,658 @@
+# Dolby Vision Profile 7 FEL on Apple TV
+
+How AetherEngine plays a Profile 7 dual-layer source (base layer + enhancement layer + RPU) as real
+Dolby Vision on an Apple TV 4K, what has been proven on device, and the design that does it with
+bounded CPU, GPU and memory while staying correct.
+
+This is the design document for the feature. User-facing behaviour lives in [formats.md](formats.md#dolby-vision-signaling), options in
+[api.md](api.md), tools in [cli.md](cli.md).
+
+Reference device for every measurement below: Apple TV 4K (2nd generation, A12, 3 GB RAM), tvOS 27.0,
+HDMI to an LG OLED, 23.976 fps UHD Blu-ray remuxes.
+
+- [1. What is being played](#1-what-is-being-played)
+- [2. Output contract](#2-output-contract)
+- [3. Current implementation](#3-current-implementation)
+- [4. Evidence](#4-evidence)
+- [5. Design](#5-design)
+- [6. Verification](#6-verification)
+- [7. Document map](#7-document-map)
+
+---
+
+## 1. What is being played
+
+A Profile 7 access unit carries three things:
+
+| Part | Carriage | Content |
+|---|---|---|
+| Base layer (BL) | ordinary HEVC NAL units | 3840×2160 HEVC Main 10, BT.2020 PQ, a complete HDR10 picture on its own |
+| Enhancement layer (EL) | `unspec63` NAL units (`0x7E 0x01` + an embedded HEVC NAL) | 1920×1080 HEVC Main 10, its own VPS / SPS / PPS |
+| RPU | one `unspec62` NAL unit (`0x7C 0x01`) | per-component reshaping curves (polynomial or MMR pieces), NLQ parameters for the residual, and display-management metadata (L1, L2, L5, L8, L9, L11) |
+
+The RPU header says what the EL is for. **MEL** (minimal enhancement layer, `el_type == "MEL"`)
+carries no residual: the picture is the reshaped base layer. **FEL** (full enhancement layer) adds a
+residual that restores detail and precision the 10-bit base encode lost. `disable_residual_flag` can
+switch the residual off for an individual RPU.
+
+Apple platforms decode Profile 5, 8.1 and 8.4 natively and have no Profile 7 dual-layer decoder. That
+leaves two ways to play Profile 7:
+
+1. **Convert to single-layer 8.1** on the native path: rewrite each RPU with libdovi mode 2, drop the
+   EL. The conversion is lossless for MEL and loses the residual for FEL. Where the display takes
+   Dolby Vision that is what plays; where it does not, the native route plays the HDR10 base layer. See `DoviRpuConverter.convertPacketToProfile81`.
+2. **Compose BL + EL + RPU ourselves** and present the result with its Dolby Vision metadata. That is
+   the subject of this document.
+
+## 2. Output contract
+
+What a composed frame handed to the display layer must be:
+
+- **Pixels.** `kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange` (P010), BT.2020 primaries, PQ
+  transfer, colour attachments copied from the base layer. Reconstruction runs at 12-bit precision
+  (reshaped base plus inverse-NLQ residual); an ordered 8×8 Bayer dither, inverted on odd frames and
+  phase-offset between Cb and Cr, takes it to 10 bits. Luma is clamped to 64–940, chroma to 64–960.
+- **Metadata, on every frame.**
+
+  | Attachment | Value |
+  |---|---|
+  | `DolbyVisionRPUData` | the RPU converted to Profile 8.1 (`dovi_convert_rpu_with_mode(rpu, 2)`), as the `unspec62` NAL **without** its 2-byte header, emulation-prevention bytes kept; a `CFData` |
+  | `DolbyCompatibilityID` | the **`CFString` `"1"`**, never a number |
+
+  A frame with no RPU has both attachments removed, because output buffers are recycled from pools
+  and would otherwise carry a previous frame's trims.
+- **Why Profile 8.1 metadata.** The composed picture is YCbCr PQ over an HDR10-compatible signal, which
+  is exactly what a Profile 8.1 RPU describes. Mode 2 keeps L1 / L2 / L5 / L8 / L9 / L11 intact and makes
+  the reshaping identity, which is correct because the composer has already applied the real curves.
+  Profile 5 (IPT-PQ-c2) would require re-deriving the reshaping for a different colour space.
+- **Who consumes it.** `HDRProcessing.framework` inside **backboardd**, on CoreAnimation's external
+  display thread, on every vsync (§4.1). Nothing in the app's own process reads it, so no in-process
+  instrument can observe consumption.
+
+## 3. Current implementation
+
+```mermaid
+flowchart LR
+  D["Demux thread<br/>DoviRpuConverter.separateDualLayers"] -->|BL packet| VB["VTDecompressionSession<br/>BL 4K"]
+  D -->|EL packet| VE["VTDecompressionSession<br/>EL (typically 1080p)"]
+  D -->|params + 8.1 RPU| C[("rpuCache / dmRpuCache")]
+  VB --> P{"DualLayerVideoDecoder<br/>pairing"}
+  VE --> P
+  C --> P
+  P -->|compose| G["DoviFelComposer<br/>composeAsync (Metal)"]
+  P -->|bypass| O
+  G --> O["OrderedDelivery<br/>fulfil → emit → DoviDisplayMetadata.attach"]
+  O --> R["SampleBufferRenderer<br/>AVSampleBufferDisplayLayer"]
+```
+
+| Stage | Code | Thread | What happens per frame |
+|---|---|---|---|
+| Routing | `VideoRoutingPolicy.requiresSoftwarePath`, `SoftwarePlaybackHost` decoder selection | load | Profile 7 + `preferDualLayerDolbyVision` + `dolbyVisionHandling` `.automatic` + VOD seekable source + hardware HEVC decode + `el_type` FEL + inside the real-time budget (§5.2) → software host, which picks `DualLayerVideoDecoder` (§5.2) |
+| Split | `DoviRpuConverter.separateDualLayers` | demux | RPU parsed into composer parameters and converted to an 8.1 NAL; EL NAL units copied into a new `AVPacket`; the BL packet goes to VideoToolbox untouched (it skips the `unspec` NAL units itself) |
+| Align | `DualLayerPictureAlignment.enhancementPTS` | demux, under the decoder's lock | each layer's display slot from its POC (`HEVCPictureOrderCount`); the EL packet takes the PTS of the BL picture in the same slot, so pairing by time pairs by picture order when the layers' GOPs differ. A layer whose sequence cannot be trusted (leading pictures of the opener, or more than 16 slots off its unit, or a seek before its next IRAP) keeps its access unit's PTS |
+| Decode | two `HardwareVideoDecoder`s | VideoToolbox output threads | asynchronous decode with temporal processing, P010 IOSurface buffers in decode order (the renderer's 4-frame reorder buffer restores display order, as for any VideoToolbox HEVC stream) |
+| Pair | `DualLayerVideoDecoder.handleBaseLayerFrame` / `handleEnhancementLayerFrame` | VideoToolbox output threads, under the decoder's recursive lock | match the other layer by 90 kHz canonical PTS within ±300 ticks; a base-layer frame takes its ticket at arrival and is bypassed under it once K = 3 newer base-layer frames have arrived; waiting enhancement frames capped at 10; side data in a 32-entry ring; `hdr10Data` and the display-metadata NAL are resolved once here and travel with the ticket |
+| Compose | `DoviFelComposer.composeAsync` | caller, then Metal | wait for one of 3 in-flight slots, rent a P010 buffer (§5.6), copy colour attachments from the base layer, bind 6 texture-cache textures, serialize the parameter block, encode luma and chroma kernels in one concurrent encoder, commit |
+| Deliver | Metal completion handler → composer's `deliveryQueue` (composed frames) or the pairing call directly (a bypass) → `OrderedDelivery.fulfil` → `emit` | Metal's completion queue hands off immediately to the composer's own `.userInteractive` queue (§4.3's firewall, not an ordering mechanism), or the pairing thread for a bypass, then `OrderedDelivery`'s own `.userInteractive` queue — never the decoder lock | release the GPU slot inline, nothing else, on Metal's queue; everything else (error logging, GPU-time accounting, `completion`) hops off it first. Either path hands the frame to `OrderedDelivery` (§5.7): one serial queue orders composed and bypassed frames alike regardless of which queue called `fulfil`, drops anything tagged with an epoch a flush/close has since retired, and calls `onFrame` (renderer enqueue) with no decoder lock held |
+
+A frame bypasses composition, and goes out as its base layer with its own DV metadata, when the
+stream is not FEL, when MEL was detected, when no RPU parameters exist for its PTS, or when
+composition fails.
+
+**Kernels** (`DoviShaderSource.swift`). Luma: base code → piece selection → polynomial (evaluated in
+normalized float) or MMR when the luma curve uses MMR → plus the inverse-NLQ residual of the
+enhancement-layer luma, upsampled with one hardware-bilinear fetch →
+12-bit clamp → dither → 10-bit. Chroma: base chroma plus the average of the two vertically adjacent
+luma samples (chroma siting) → MMR → plus the residual from the upsampled enhancement chroma → dither.
+
+**Parameter ABI.** `DoviShaderSource.sharedStructs` on the GPU side, `DoviMetalParams.serialize` on
+the Swift side. `DoviLayoutProbeTests` has the GPU read every sub-block back at the offset Swift wrote
+it to; `DoviShaderSyncTests` pins the serialized size and that every kernel is present.
+
+### 3.1 Audio
+
+Known trade-off of the route, following the maintainer's request to document it rather than work around it.
+The dual-layer route runs on `SoftwarePlaybackHost`, so its audio is the host's own `AudioDecoder` (FFmpeg
+decode to PCM, played through the sample-buffer audio renderer) and never AVPlayer. On tvOS only AVPlayer
+emits Dolby Atmos objects, and the platform does not pass a bitstream through. An E-AC-3 (JOC) track
+therefore plays as its channel-bed core (5.1 or 7.1), without the Atmos objects; on the native route the
+same track is handed to AVPlayer unchanged. TrueHD behaves as on the native route, which decodes it too and
+loses the objects either way. Hosts that want E-AC-3 Atmos on a Profile 7 FEL title leave
+`preferDualLayerDolbyVision` off for it. `DualLayerRouteAudioTests` pins the routing half of this.
+
+## 4. Evidence
+
+### 4.1 tvOS consumes the attachment, in backboardd
+
+Two device runs were killed with `SIGKILL` about eleven composed frames in. The app log showed nothing
+wrong except `Connection interrupted` and `invalid destination port` from CoreAnimation, which means
+the render server died first. The paired Apple TV's own crash reports held two `backboardd-*.ips`
+files timed to the runs, and no `JetsamEvent`, which rules out memory pressure. Both had this stack:
+
+```
+Exception: EXC_CRASH (SIGABRT), -[__NSCFNumber length]: unrecognized selector
+Thread:    com.apple.coreanimation.display.external-0
+  CFStringGetIntValue
+  -[HDRProcessor applyDoVi81PolicyWithInput:WithRPU:]
+  -[HDRProcessor processFrameInternalWithLayer0:layer1:outout:metadata:commandbuffer:…]
+  CA::HDRProcessorInternal::tonemap_surface_internal(__IOSurface*, …, __CFData const*, …)
+  CA::HDRProcessorInternal::create_surface_with_forward_dm
+  CA::Render::ImageQueue::forward_dm
+  CA::WindowServer::IOMFBServer::vsync_callback
+```
+
+That is the proof of consumption: on the vsync callback, CoreAnimation pulls display management off
+our IOSurface and applies Dolby Vision 8.1 policy with our RPU. It is also the bug: the policy parses
+`DolbyCompatibilityID` with `CFStringGetIntValue`, and we had attached a `CFNumber`. Decoding a
+Profile 8.1 asset through `AVAssetReader` and printing the CF type of VideoToolbox's own attachments
+confirmed the fix:
+
+| Attachment | Class | CF type | Value |
+|---|---|---|---|
+| `DolbyCompatibilityID` | `NSTaggedPointerString` | `CFString` | `"1"` |
+| `DolbyVisionRPUData` | `__NSCFData` | `CFData` | 188 / 189 bytes |
+
+The payload form was established the same way: VideoToolbox's `DolbyVisionRPUData` matches the
+bitstream's `unspec62` NAL byte for byte once the 2-byte header is removed and the emulation-prevention
+bytes are left in; the EPB-stripped RBSP is 176 bytes and does not match.
+
+Two consequences carry forward. A malformed attachment crashes the render server and looks, from
+inside the app, like an unexplained kill; suspect the attachment before memory. And the device crash
+reporter (`devicectl … --domain-type systemCrashLogs`) is the instrument for anything that happens
+out of process.
+
+### 4.2 Throughput: the composer must not block decode
+
+Playback first ran with `compose` ending in `waitUntilCompleted()` under the decoder lock. The deficit
+was steady, not a hitch:
+
+| | Blocking compose | `composeAsync` + one encoder |
+|---|---|---|
+| Delivered rate | 21.4–22.0 fps | real time, ~26.6 fps while catching up after a seek |
+| Video lead | slipping 0.09 s per second | flat at about +0.5 s |
+| Display drops | +3…+7 every second | flat after seek settling |
+| GPU time per frame | 28 ms end to end, serialized | 14.3 → 12.9 ms, off-thread |
+
+Most of the original 28 ms was the wait and the CPU-side setup, not GPU work: the A12 has about 3×
+headroom against the 41.7 ms budget at 23.976 fps. The two serial compute encoders were merged into
+one concurrent encoder because the luma and chroma kernels never read each other's output; the
+bit-exactness suites passing unchanged is what proves that moved no pixels.
+
+### 4.3 The completion-handler deadlock
+
+Metal runs every `addCompletedHandler` block for a command queue on one serial queue. The first async
+version delivered from inside that handler, which took the decoder lock, while the caller held the
+same lock waiting in `inFlight.wait()` for the signal that only a later handler could send. Playback
+stopped after about ten seconds with the session still reporting healthy. The fix, and a rule for any
+future change: **release the slot inline in Metal's handler and do nothing there that can block; hop
+to another queue for everything else.** `DoviComposeAsyncTests.doesNotDeadlockAgainstTheCallersLock`
+reproduces the exact lock shape; against the old handler it hung past a 300 s timeout.
+
+### 4.4 Earlier fixes worth remembering
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Metal validation abort binding textures | integer kernel access on a Unorm texture | bind BL and output planes as `r16Uint` / `rg16Uint`, EL planes as `r16Unorm` / `rg16Unorm` so they can be filtered |
+| Black picture with `COMPOSE SUCCESS` on every frame | 10-bit prediction treated as 12-bit | keep the whole reconstruction in one declared precision |
+| Green / purple picture | chroma curves with fewer than 2 pivots returned 0 | an absent curve is identity, not zero |
+| GPU reading freed memory | `CVMetalTexture` wrappers released before completion | keep textures *and* their source buffers alive until the command buffer retires (`ComposedFrame`) |
+| Layers never pairing | container vs decoder timestamp scales | canonicalize to 90 kHz and match within ±300 ticks |
+| EL decoder never opening | EL VPS / SPS / PPS split across packets | accumulate parameter sets across packets |
+| Profile 7 plays as plain HDR10 | the container carries no `dvcC` record, so the load never sees a Profile 7 (routing and the `el_type` probe both start from the record) | none: the file plays as its HEVC base layer, the `unspec62` / `unspec63` NAL units ignored. `DolbyVisionRecordAudit.addRecordIfProfile5` repairs a recordless Profile 5 only; for Profile 7 the fix is a remux that writes the record |
+
+### 4.5 Consumption test assets
+
+`aetherctl dvsurvey` (in the tooling PR that follows this one) ranks frames by L1 distance from the title's median so that the pin test can
+pin a frame whose metadata is a large lie. On the three local test clips: a CMv4.0 4000-nit clip pins
+frame 247 (`max_pq` 4095 against a median of 2081, distance 3876, the best asset); a scene clip gives
+distance 1391, usable; a credits clip has static L1 (distance 0) and is correctly rejected as `WEAK`.
+
+The consumption question, whether the panel uses the RPU the engine attaches rather than only
+switching into a Dolby Vision mode, is answered by a pulse test that anyone with an Apple TV, a
+television and a phone can repeat: clips whose pixels are constant while only the RPU (or the
+enhancement-layer residual) switches, played through AVPlayer, VideoToolbox and the FEL route, and
+filmed. Clip generator, device host, harness scripts and analysis are in
+[`Probes/DolbyVisionPulse`](../Probes/DolbyVisionPulse/README.md), which arrives with the pulse-probe PR
+that follows this one; the link resolves once it has landed.
+
+### 4.6 Caveat on the numbers
+
+Every device figure above came from DEBUG builds: `-Onone`, with the HDMI probe retrying and the
+memory watermark sampling on every emitted frame. They show the direction and the GPU cost; CPU and
+memory should be re-measured on a release build. Footprint went from a flat ~390 MB to a plateau of
+~705 MB with the async pipeline; §5.10 accounts for the pipeline's own share.
+
+---
+
+## 5. Design
+
+VideoToolbox decodes both layers, one concurrent Metal encoder composes them, each frame carries the
+Profile 8.1 attachment, delivery is ordered by ticket, and the GPU slot is released inline. The
+sections below are the rules that keep per-frame work and shared mutable state to a minimum.
+
+### 5.1 Principles
+
+1. **Decide once per stream, not per frame.** FEL vs MEL is a property of the encode; routing and
+   decoder setup decide it, and no callback changes it.
+2. **Touch each byte once.** One libdovi parse per RPU, no copy of the base-layer access unit.
+3. **Nothing blocks while holding a lock, and every piece of state has one owner.**
+4. **Every frame has a bounded lifetime.** Bounded wait for its partner, bounded queues, bounded GPU
+   work in flight, and nothing from before a flush survives it.
+5. **Per-frame work writes no log lines.** Counters feed a 1 Hz summary.
+
+### 5.2 Routing
+
+The load probes the first RPU's `el_type` (`DolbyVisionRecordAudit.probeEnhancementLayerType`) and
+passes it into `VideoRoutingPolicy`:
+
+| Source | `dolbyVisionHandling` | `preferDualLayerDolbyVision` | Device | Route |
+|---|---|---|---|---|
+| P7, `el_type` FEL | `.automatic` | true (opt-in; the default is false) | VideoToolbox HEVC hardware + Metal | software host, `DualLayerVideoDecoder` |
+| P7, `el_type` FEL | `.automatic` | false (the default), or no VideoToolbox HEVC hardware decode | — | native (8.1 conversion where the display takes Dolby Vision, otherwise the HDR10 base layer) |
+| P7, `el_type` MEL | `.automatic` | any | — | native (as above; the conversion loses nothing for MEL) |
+| P7, any | `.baseLayerOnly` | any | — | HDR10 base layer |
+
+The software host then instantiates `DualLayerVideoDecoder` only for the first row; a Profile 7 forced
+onto the software path by any other combination gets a plain `HardwareVideoDecoder` for the base layer.
+
+### 5.2.1 The capability gate and its diagnostic line
+
+The route is FEL only and capability gated (`DualLayerRouteDecision`, pure and unit-tested). Everything
+else keeps the native route, which plays single-layer 8.1 where the display takes Dolby Vision and the
+HDR10 base layer where it does not: the preference is off, `dolbyVisionHandling` is not `.automatic`, a
+live or non-seekable source, a box with no hardware HEVC decoder for the stream, a MEL source (nothing
+to compose), an enhancement layer the probe could not classify, a base layer of unknown size, and a
+stream the box could not decode twice in real time. The checks run in that order (the code's order:
+preference, handling, live/seekable, hardware, `el_type`, geometry, budget). The `el_type` probe (a packet
+scan and a seek) runs once nothing up to and including the hardware check has ruled the route out, so it
+also runs for a stream that the geometry or the budget then refuses: the MEL / unknown answer outranks
+the size reasons in the log line, and that precedence needs the probe's answer.
+
+The real-time budget is a pixel rate, base layer plus enhancement layer, from the stream's width, height
+and frame rate: `DualLayerRouteDecision.maximumPixelsPerSecond`, 311.04 Mpx/s, which is UHD
+3840x2160 at 30 fps plus a 1920x1080 enhancement layer at 30 fps. The enhancement layer is taken as a
+quarter of the base layer's area (what a 4K FEL disc ships), and an unknown frame rate is budgeted as 24
+(the line says "assumed"). The load passes no enhancement-layer size, so it always budgets the quarter-area
+layer (every retail FEL title's layout); a 1:1 enhancement layer is not detected at load. A base layer whose
+width or height is unknown (not positive) is refused rather than budgeted at zero. A 24p UHD FEL master needs 80% of the budget. What is measured: the Mac soak runs in the PR
+description (M2 Pro, debug `aetherctl`), and, from earlier development builds on an Apple TV 4K 2nd
+generation, the composer's GPU time of 12.9-14.3 ms per frame against a 41.7 ms frame at 23.976 fps
+(§4.2, a debug build and a previous iteration of the pipeline, not this stack). The 311 Mpx/s ceiling,
+and 30 fps as a margin above 24p, are an assumption until the Apple TV run of this stack. UHD at 60 fps
+(200%) and 8K fall back.
+
+A Profile 7 load logs exactly one line, whichever way it goes (other sources log nothing here):
+
+```
+[AetherEngine] DV P7 dual-layer route: taken (el_type=FEL, 3840x2160@23.976, budget 80%)
+[AetherEngine] DV P7 dual-layer route: not taken (el_type=MEL, nothing to compose), keeps the native route (8.1 where the display takes Dolby Vision)
+[AetherEngine] DV P7 dual-layer route: not taken (preferDualLayerDolbyVision is off), keeps the native route (8.1 where the display takes Dolby Vision)
+[AetherEngine] DV P7 dual-layer route: not taken (over the real-time budget, 3840x2160@60 needs 200% of it), keeps the native route (8.1 where the display takes Dolby Vision)
+[AetherEngine] DV P7 dual-layer route: not taken (base-layer size unknown), keeps the native route (8.1 where the display takes Dolby Vision)
+```
+
+A missing Metal device does not fall back to the native route: the routing decision above has
+already been made, so the software host keeps the base layer alone on a `HardwareVideoDecoder` (HDR10,
+no composition). The same is true after the fact: if the compute shaders fail to compile, the decoder
+stays but every frame goes out as its base layer.
+
+### 5.2.2 The display is not consulted
+
+The route decision does not look at the display. With `preferDualLayerDolbyVision` on and a display
+that does not take Dolby Vision (an SDR or HDR10-only panel or mode), the route is still taken when
+the gate above passes: the software host composes the full FEL picture and presents it with the
+Profile 8.1 metadata attached (§2), and how tvOS presents that on such a display is up to the platform.
+The native route, by contrast, strips the Dolby Vision for such a display (`CodecRoutePolicy`) and plays
+the HDR10 base layer. A host that wants the base layer on a non-Dolby-Vision display leaves the flag off,
+or sets it from what it knows of the display. The audio trade-off of §3.1 (an E-AC-3 Atmos track plays as
+its channel-bed core, without the objects) applies on this route whatever the display. This is the current
+behaviour, documented rather than designed; it is not changed here.
+
+### 5.2.3 What the route gives up against the native route
+
+The dual-layer route runs on the software host: there is no `AVPlayer` and no `AVPlayerItem`, and the
+picture is drawn into an `AVSampleBufferDisplayLayer`. Everything that AVKit or the loopback HLS
+server provides to the native route through the item is therefore either replaced by an engine
+equivalent or absent. With `preferDualLayerDolbyVision` off none of this changes. The comparison,
+checked against the code:
+
+| Feature | Native route | Dual-layer route |
+|---|---|---|
+| Picture in Picture | `AVPlayer`-based: the stock `AVPlayerViewController` and a host-built `AVPictureInPictureController` both work. | No `AVPlayer`, so no stock player PiP. The engine publishes `SoftwarePiPSource` (the layer plus the transport answers for a sample-buffer PiP content source) and the host builds the `AVPictureInPictureController` around it; while PiP is active, subtitle cues are drawn into the frames by `SubtitleFrameCompositor`, which carries the pixel-buffer attachments through. Whether the PiP window presents the composed picture as Dolby Vision is not measured. |
+| Scrub thumbnails | With `serveIFramePlaylist`, an `EXT-X-I-FRAME-STREAM-INF` rendition next to the master, so a stock `AVPlayerViewController` draws its own thumbnails and scans on I-frames, plus `scrubThumbnail(atSeconds:)`. | No I-frame playlist, so a stock player shows no thumbnails of its own. `scrubThumbnail(atSeconds:)` answers from the software host's retained packet cache (`servesPacketCacheStills`) and only when that cache exists: a local file is read directly and has none, so there the call returns nil. The still is the base layer decoded by libavcodec, not the composed picture. |
+| Subtitles | Text tracks can be declared in the init segment and served as WebVTT renditions (`prepareNativeSubtitles`), so `AVMediaSelection`, PiP and external screens render them. | No renditions and no `AVMediaSelection`. The engine decodes the cues and publishes them; the host draws its own overlay in the app. They appear in a PiP window only through the frame compositor above, and the system caption styling does not apply. |
+| AirPlay | `AVPlayer` hands the receiver the stream (the engine serves the loopback over the LAN address for it). | The layer draws on the device and only the audio renderer follows the route, so a wireless receiver plays sound only. The engine publishes `airPlayPictureStaysLocal` (iOS) so a host can say so. Not applicable where the device is itself the receiver. |
+
+A host that needs any of these for a Profile 7 title leaves the flag off for it, as for the Atmos
+trade-off of §3.1.
+
+### 5.3 Packet split
+
+One walk over the access unit's NAL units, on the demux thread:
+
+- **RPU:** `dovi_parse_unspec62_nalu` once. From that handle read the header (`disable_residual_flag`),
+  the data mapping (into `DoviMetalParams`), then convert with mode 2 and write the 8.1 NAL. Strip its
+  header once into the attachment `Data`.
+- **EL:** copy the embedded NAL units into the EL packet (one 1080p copy, unavoidable because
+  VideoToolbox needs a standalone access unit).
+- **BL:** hand the packet to VideoToolbox **untouched**. The format description is built from the base
+  layer's parameter sets with no `dvcC`, so `unspec62` and `unspec63` are unknown NAL types it skips.
+  The rebuild stays only in `convertPacketToProfile81`, where the container does declare Dolby Vision.
+
+Side data goes into a **`FrameSideDataRing`** keyed by canonical PTS: `{ params, dvPayload, flags }`,
+fixed capacity 32 (reorder depth plus maximum layer skew with margin). Insert overwrites the oldest,
+lookup scans at most 32 entries for the nearest key within ±300 ticks. No sorting, no dictionaries.
+
+### 5.4 Decode
+
+Two `HardwareVideoDecoder`s. `HardwareVideoDecoder.decode` wraps the packet's memory with
+`CMBlockBufferCreateWithMemoryBlock` and a custom block source that holds an `av_buffer_ref` of
+`packet.buf` and unrefs it in `FreeBlock`, so VideoToolbox can retain the data past the call without a
+copy. When `packet.buf` is nil it falls back to the copy. This benefits every HEVC source on the
+software path, not just FEL.
+
+### 5.5 Pairing
+
+Pairing lives in `DualLayerVideoDecoder.handleBaseLayerFrame` / `handleEnhancementLayerFrame`, under
+the decoder's lock, and each call is O(K):
+
+- A **base-layer frame takes its ticket when it arrives.** VideoToolbox outputs in decode order, so
+  ticket order is decode order, whatever happens to the frame later. Display order is restored
+  downstream, by the renderer's reorder buffer (4 frames, the same depth as a single-layer hardware
+  decode; `DoviFelRealFileTests.reconstructsAndOrders` replays that rule on the real files).
+- If its enhancement layer is already waiting (within ±300 ticks), the pair is composed. Otherwise it
+  waits.
+- **A waiting base layer is bypassed, under its own ticket, once K newer base-layer frames have
+  arrived.** K (`maxLayerSkewFrames`) is the maximum layer skew, 3; the summary line reports the
+  observed skew (§5.11). A lost enhancement frame costs K frames of delay and never reorders output.
+- An enhancement frame whose base layer has already gone out (its key matches one of the last 64
+  settled base-layer keys) is dropped on arrival. At most 10 enhancement frames wait.
+- A frame's side data is looked up once, when its base layer arrives, and travels with the ticket;
+  delivery never touches a shared cache.
+- The `disable_residual_flag` of an individual frame becomes a kernel flag
+  (`DoviComposerFlags.disableResidual`); it never changes the stream classification.
+
+### 5.6 Compose
+
+- **Acquire the in-flight slot outside the decoder lock**, on the VideoToolbox output thread that
+  produced the `compose` action, then encode and commit. Blocking that thread is the intended
+  backpressure: VideoToolbox stops emitting, the display layer stops draining, and the demux loop's
+  existing `mayEnqueueVideoFrame` gate (the renderer's queue readiness plus the look-ahead bound) holds.
+- **Parameters** are written straight into one of `maxFramesInFlight` preallocated shared
+  `MTLBuffer`s (`DoviMetalParams.serialize(into:)`), bound with `setBuffer` for both kernels. No `Data`,
+  no heap arrays per frame.
+- **Output pool** gets `kCVPixelBufferPoolAllocationThresholdKey` = the renderer's FEL look-ahead (9)
+  + the frame on screen and the one the display layer retains (2) + the in-flight slots (3) + 1, so 15.
+  A refused buffer would put a base-layer frame on screen, a visible brightness step, so past the
+  threshold a burst draws on a reserve of 3 more. Only with the reserve spent does the composer wait,
+  for at most about 36 ms (a 300 ms wait stalled the VideoToolbox callback and starved audio into
+  rebuffers on device), and then the frame bypasses instead of growing the pool.
+- **Texture cache** is flushed from the 1 Hz tick, which releases textures for buffers no longer in use.
+- **Colour attachments** are copied from the base layer when encoding, on the calling thread, not on
+  Metal's completion queue.
+- **Pipelines** are compiled once per process, lazily on first composition (a shared `MTLLibrary` and
+  pipeline states), so a MEL or bypassed stream never compiles and a second decoder instance does not
+  recompile.
+- **Kernels:** a per-frame 1024-entry luma prediction table replaces piece selection and polynomial
+  evaluation per pixel whenever luma is polynomial (it is a pure function of the 10-bit base code);
+  residual evaluation is skipped per component when that component's NLQ is inactive; threadgroup sizes
+  come from `threadExecutionWidth`. Every one of these keeps `DoviGpuCurveSweepTests` bit-exact.
+
+### 5.7 Delivery
+
+An `OrderedDelivery` object owned by the decoder, not the composer:
+
+```swift
+final class OrderedDelivery {
+    private let queue = DispatchQueue(label: "de.superuser404.dovi.delivery", qos: .userInteractive)
+    // Confined to `queue`: no lock.
+    private var epoch: UInt64 = 0
+    private var nextToEmit: UInt64 = 0
+    private var pending: [UInt64: DeliveredFrame] = [:]
+
+    func fulfil(ticket: UInt64, epoch: UInt64, _ frame: DeliveredFrame)  // queue.async
+    func resetAsync(epoch: UInt64, nextTicket: UInt64)                    // queue.async, callable under a lock
+    func barrier()                                                        // queue.sync, never under a lock
+    func reset(epoch: UInt64, nextTicket: UInt64)                         // resetAsync + barrier
+}
+```
+
+- **Every** outgoing frame goes through `fulfil`: composed frames from the composer's relay queue
+  (after `slot.signal()`, see below), bypassed frames straight from the pairing call. One serial queue orders
+  both, so no lock and no recursive re-entry are needed.
+- **The queue owns its state.** `emit`, which attaches the DV metadata and calls `onFrame`, runs on it
+  with no decoder lock held, so the renderer's own lock is never nested inside ours.
+- **QoS `.userInteractive`.** The work per frame is O(1) (two attachments and an enqueue), it is bound
+  by the frame rate, and it decides what is on screen next, which is what that class is for. A queue
+  created with only a label has unspecified QoS and inherits whatever the submitting Metal completion
+  thread carries, so presentation can wait behind default- or utility-class work. Because the work is
+  tiny it cannot starve the UI; if a trace ever shows contention on tvOS, `.userInitiated` is the
+  fallback.
+- **Epochs instead of moving the line under a lock.** A ticket carries the epoch it was issued in;
+  a stale one is dropped when it reaches the head of the queue. `barrier()` runs with `queue.sync`,
+  which waits for any delivery in progress, so nothing from an old epoch can reach `onFrame` after
+  `flush()` returns. It asserts `dispatchPrecondition(condition: .notOnQueue(queue))`: a host must
+  never flush from inside `onFrame`.
+- **Stall guard.** If more than `maxFramesInFlight + K + 2` frames are pending behind a missing
+  ticket, skip the missing ticket and log once. A lost ticket must cost one frame, not the session.
+- **No `.global()` fallback.** The completion handler captures the delivery object strongly; a
+  completion that outlives the decoder delivers into an epoch that no longer exists and is dropped.
+
+**The composer keeps its own relay queue.** A composed frame's completion is not handed straight to
+`OrderedDelivery.fulfil` from Metal's completion handler. `DoviFelComposer` keeps a small serial `deliveryQueue` (`qos: .userInteractive`,
+captured as a plain value, no `.global()` fallback) that every composed frame's completion hops through
+first; only there does it call `completion`, which is `fulfil` in production. §4.3 requires exactly this
+shape — "release the slot inline in Metal's handler and do nothing there that can block; hop to another
+queue for everything else" — and `DoviComposeAsyncTests.doesNotDeadlockAgainstTheCallersLock` reproduces
+the deadlock removing the hop would reopen: a `completion` that blocks on the caller's lock, run directly
+on Metal's shared completion queue, stalls every later handler too, including the `inFlight.signal()` a
+different, currently-blocked caller needs. `deliveryQueue` carries no ordering responsibility of its
+own — `OrderedDelivery` reorders every frame by ticket regardless of which queue or thread calls
+`fulfil`, so a bypass arriving directly from a VideoToolbox thread and a composition arriving via this
+relay hop are indistinguishable once they reach it. This is a deliberate queue hop, not a second
+ordering mechanism. An `os_signpost` event in the Metal completion handler
+(`DoviFelComposer`'s "Compose" signpost) marks the instant Metal invoked it, separately from the
+interval's `.end` (which only fires after this hop), so the hop's own latency is visible in Instruments
+rather than folded into either "Compose" or "Delivery".
+
+### 5.8 Flush and close
+
+Order matters because `HardwareVideoDecoder.flush` waits for frames VideoToolbox still owes, and those
+arrive through the normal callbacks:
+
+1. Under the lock: bump the feed epoch (so `decode(packet:epoch:)` refuses packets from before the
+   seek), raise `draining`, take `nextTicket`, and enqueue `delivery.resetAsync(epoch:nextTicket:)` —
+   from inside this same critical section, not after. Then, still outside the lock but before draining,
+   call `delivery.barrier()` to wait for that reset to actually run.
+2. Flush both `HardwareVideoDecoder`s. Their pending frames land in pairing, in the old state, but
+   `draining` (still up) drops them before they can take a ticket, and any composition already in
+   flight before this call is dropped by the epoch check the instant it reaches `fulfil`.
+3. Under the lock, lower `draining` and reset pairing and the side-data ring.
+4. Flush the composer's texture cache.
+
+The epoch is retired in step 1, before draining, and not after the drain. Retiring it after the
+drain, with a plain `delivery.reset` once the lock was released, left a gap: a VideoToolbox callback
+landing between that `unlock()` and the `reset` could take a new-epoch ticket and reach `fulfil` before
+`reset` had run, so the ticket was dropped as still-old-epoch and `reset` then fast-forwarded past it,
+stalling every following frame until the stall guard skipped the hole. Splitting the reset into a
+non-blocking enqueue (`resetAsync`, called while still holding the lock) and a wait (`barrier`, called
+after releasing it) closes that gap: `draining` cannot go false, so no new ticket can be issued, until
+`barrier()` has confirmed the new epoch is installed. It also keeps a composition that was already in
+flight before the flush from reaching `onFrame` while `HardwareVideoDecoder.flush()` is still draining.
+`OrderedDeliveryTests.newEpochTicketFulfilledBeforeResetIsDeliveredIsNotLost` and
+`DualLayerVideoDecoderTests.flushDoesNotLosePostFlushTicketInTheUnlockToBarrierGap` drive that window
+directly.
+
+`close()` follows the same shape (bump epoch, capture `nextTicket`, `resetAsync` — all inside one
+critical section that also sets `isClosed` — then `barrier()` after unlocking), then clears `onFrame`,
+swaps the enhancement decoder out under the lock and closes it outside, and resets the stream
+classification so the object cannot leak one stream's decisions into the next. A closed decoder refuses
+`open` (single use) rather than being half reusable. A concurrent `flush()`/`flush()` or
+`flush()`/`close()` is serialized by the decoder's lock the same way either order: `_feedEpoch` and
+`deliveryNextTicket` only ever move forward under it, and the lock also fixes the order the two calls'
+`resetAsync`s land in `delivery`'s own queue, so whichever lands later always carries the larger epoch —
+neither the epoch nor `nextToEmit` can move backwards.
+
+### 5.9 Threading model
+
+| Thread | Does | Holds | May block on |
+|---|---|---|---|
+| Demux | NAL split, one libdovi parse, side-data ring insert, VideoToolbox submit | decoder lock, O(1) | nothing |
+| VideoToolbox output (BL, EL) | pairing; for `compose`, slot acquisition then encode and commit | decoder lock for the pairing call only | a GPU slot, with no lock held |
+| Metal completion | `slot.signal()`, GPU time sample, hop to the composer's relay queue | none | never |
+| Composer relay queue (`deliveryQueue`, `.userInteractive`) | `completion` (= `delivery.fulfil` in production) | none | nothing (a slow `completion` queues up behind itself and never blocks Metal; see I7 in §5.12) |
+| Delivery queue (`.userInteractive`) | ordering, epoch check, DV attachment, `onFrame` | none of ours | the renderer's enqueue |
+| Host (seek, stop) | `flush()`, `close()` | decoder lock briefly; `delivery.barrier()` outside it | VideoToolbox drain, and whatever `onFrame` is doing when `barrier()` catches up to it |
+
+### 5.10 Budgets
+
+Memory held by the pipeline (4K P010 = 24.9 MB, 1080p P010 = 6.2 MB; VideoToolbox's own reference
+pictures and the display layer's queue are extra):
+
+| Holder | Bound |
+|---|---|
+| Base-layer frames waiting for their EL | K = 3 → 75 MB |
+| Enhancement-layer frames waiting | 10 → 62 MB |
+| Composed output buffers (in flight, pending, idle in pool) | allocation threshold 15 + reserve 3 → 448 MB, the reserve freed after a second unused |
+
+CPU per composed frame:
+
+| Work | Cost |
+|---|---|
+| libdovi RPU parses | 1 |
+| Base-layer access-unit copies | 0 (`CustomBlockSource` hands VideoToolbox the packet's own buffer) |
+| Enhancement-layer copies | 1 (extraction into a standalone access unit) |
+| Log lines at the default level | 0; a 1 Hz summary instead (§5.11) |
+| Parameter upload | written into a preallocated `MTLBuffer` |
+| Side-data lookup | the 32-entry ring, no sorting |
+| Shader compilation | once per process, lazily |
+
+GPU: 12.9–14.3 ms per frame measured on the A12 (§4.2), against a 41.7 ms budget at 23.976 fps. A
+59.94 fps source (16.7 ms budget) has far less headroom.
+
+### 5.11 Observability
+
+One `[DualLayer] summary` line per second while composing: frames composed, bypassed without EL,
+bypassed without RPU, stale enhancement frames dropped, maximum observed layer skew in frames, peak
+GPU slots in use, output pool buffers allocated, delivery pending peak, mean GPU ms. The existing
+`[DoviFelComposer] gpu … ms/frame` line stays. `os_signpost` intervals around compose and delivery
+make the pipeline readable in Instruments. Nothing else logs per frame; anything genuinely per-frame
+for debugging uses `EngineLog` level `.verbose`.
+
+### 5.12 Invariants and the tests that hold them
+
+| # | Invariant | Test |
+|---|---|---|
+| I1 | Every base-layer frame is delivered exactly once, or dropped by a flush or close | `DualLayerVideoDecoderTests.singleLayerBypassesInOrder`, `orphanedBaseLayerIsEventuallyDelivered` |
+| I2 | Delivery order is base-layer decode order within an epoch | `asyncCompositionKeepsItsPlace`; `prunedFrameDoesNotOvertakeNewerFrames` |
+| I3 | Nothing from before `flush()` is delivered after it returns; nothing after `close()` returns | `flushRetiresOutstandingFrames`, `closeStopsDelivery`, `flushFromAnotherThreadInATightLoopKeepsInvariantI3` (200 concurrent flushes racing delivery, with a per-flush "started tag vs. returned count" detector), `flushDoesNotLosePostFlushTicketInTheUnlockToBarrierGap`, `flushDropsFramesEmittedFromInsideFlush`, and `OrderedDeliveryTests.newEpochTicketFulfilledBeforeResetIsDeliveredIsNotLost` |
+| I4 | A frame carries its own RPU; a frame without one carries none; the compatibility ID is a string | `displayMetadataTravelsWithItsFrame` |
+| I5 | Composition never invents coefficients | `missingRPUBypassesToBaseLayer` |
+| I6 | Layers pair within ±300 ticks and not beyond | `jitterTolerance` |
+| I7 | Held frames are bounded: waiting EL, waiting BL, GPU in flight | `orphanedEnhancementLayersAreBounded`, `lostEnhancementLayerDelaysBaseLayerByAtMostKFrames`; `DoviComposeAsyncTests.completionsAreExactlyOnceAndBounded`. **Not bounded on its own: the delivery queue.** A slow `onFrame` does not throttle pairing (a composed frame's GPU slot is released before delivery), so nothing bounds the backlog in `OrderedDelivery` itself. The demux thread's `mayEnqueueVideoFrame` gate limits how fast new packets arrive, which limits the backlog only indirectly; `flush()`'s `barrier()` waits for the queue to empty but does not cap it. |
+| I8 | No lock is held across a blocking wait or a host callback | `DualLayerVideoDecoderTests.slowOnFrameDoesNotBlockDecoderOperations` (a blocked `onFrame` never stalls concurrent decoder work); `DualLayerGpuSlotWaitTests` for the GPU slot wait |
+| I9 | Stream classification changes only at open, flush or close | `DualLayerStreamClassificationTests` |
+
+---
+
+## 6. Verification
+
+**Unit tests.** The GPU suites need a Metal device and skip without one.
+
+```bash
+swift test --filter "Dovi|DualLayer|OrderedDelivery|FrameSideDataRing"
+```
+
+| Suite | Covers |
+|---|---|
+| `DualLayerVideoDecoderTests` | pairing in both arrival orders, jitter tolerance, missing-RPU bypass, ordered delivery across async composition, DV metadata per frame, flush and close, bounded queues |
+| `DoviComposeAsyncTests` | async output identical to blocking compose, exactly-once completion, bounded in-flight work, the lock re-entrancy deadlock |
+| `DoviGpuCurveSweepTests` | bit-exact identity round trip and curve sweeps on the GPU |
+| `DoviFelMathTests` | NLQ, pivots, MMR, polynomial precision, a real RPU composed on the GPU |
+| `DoviDitherTests` | dither pattern, Cb / Cr phase offset, zero mean bias |
+| `DoviLayoutProbeTests` | GPU reads every parameter sub-block at the Swift offset |
+| `DoviShaderSyncTests` | every kernel present, parameter block size, one pipeline per process |
+| `DoviRpuConverterTests` | NAL surgery, framing, degradation to HDR10 |
+
+**CLI** ([cli.md](cli.md); these subcommands arrive with the tooling PR that follows this one): `aetherctl feltest` (pixel and metadata verdicts, exit codes 0–5),
+`dvsurvey`, `dovitest`, and `play --cycle-el` to flip the residual on a timer.
+
+**Device.** With `DEVELOPER_DIR` pointing at an Xcode that has `devicectl`:
+
+```bash
+# the host app's own log file, if it writes one (a sink on `EngineLog.handler`)
+xcrun devicectl device copy from --device <name> --domain-type appDataContainer \
+  --domain-identifier <bundle id> --source <host log file> --destination ./device.log
+# crash reports, including backboardd's
+xcrun devicectl device info files --device <name> --domain-type systemCrashLogs --no-recurse
+# live Dolby Vision diagnostics (text logs; the signposts are categories dovi.compose and dovi.delivery)
+log stream --predicate 'subsystem == "de.superuser404.AetherEngine" AND category == "sw.playback"'
+```
+
+`info files` takes `--subdirectory` and accepts `--username`; `copy from` takes `--source` and rejects
+`--username`. The absence of a `JetsamEvent` for the day rules out a memory kill.
+
+**Consumption test** (the tooling and the pin hook arrive with the tooling PR that follows this one). Pick a pin with `aetherctl dvsurvey`, arm a DEBUG build with
+`AetherEngine.armDolbyVisionPinTest("maxpq>=4095,period:2")` (an `@_spi(Diagnostics)` hook; on the
+Mac, `aetherctl play --dv-pin`) against that asset, and watch the panel with its own dynamic
+picture processing switched off. The substitution happens after composition, so a visible pulse can
+only come from the metadata.
+
+### 6.1 Correctness
+
+The composer's arithmetic is held by tests that need no media: `DoviCpuModelTests` runs a CPU model of
+both kernels against the GPU at 12 bits, before the final rounding (`DoviDither.debugRawVDR`, test only),
+and `DoviGpuCurveSweepTests` and `DoviGpuEdgeCaseTests` sweep the curve and NLQ parameter space. On
+real titles `DoviFelRealFileTests` and `DoviRealFileExportTests` run when the fixtures are present and
+skip otherwise. Bit-exact output cannot be claimed: the EL is lossy in real
+streams and Dolby's prediction is not public.
+
+### 6.2 What is and is not applied
+
+Applied: base layer (all planes, MMR luma reads base chroma), enhancement layer (bilinear upsampled, inverse
+NLQ with offset, scale, threshold, shift, `vdr_in_max`), the per-component polynomial and MMR curves, the
+bit depths, and the display metadata (carried into the converted Profile 8.1 RPU).
+
+- **Missing or CRC-failed RPU:** the frame borrows the previous real RPU's parameters for up to
+  `maxBorrowedParamsRun` (3) frames in a row, then bypasses to the base layer. Reshaping and NLQ are constant
+  across a scene. A frame whose RPU sets `use_prev_vdr_rpu_flag` keeps the previous mapping for as long as the
+  stream asks, with no limit. Both are resolved when the packet is demuxed (`recordSideData`), in decode order,
+  so "previous" is the previous frame of the stream and each frame reaches pairing with concrete parameters;
+  resolving at compose time would follow completion order instead.
+- **Output precision:** `DoviDither.fullPrecision` keeps the VDR bits below the 10-bit code in P010's unused low
+  6 bits. Opt-in, not yet validated on a display path; the default stays rounded or dithered 10-bit.
+- **Not implemented, by design:** NLQ methods other than linear (the spec defines only linear; an unknown method
+  yields no residual), MEL (no residual by definition), NLQ pivots (the linear inverse has one segment).
+- **Not implemented, blocked:** polynomial pieces with `poly_order_minus1 == 0` and `linear_interp_flag`. libdovi is
+  a prebuilt binary that aborts on them, so `DoviRpuGuard` rejects the RPU; supporting them needs a patched
+  libdovi (or our own full RPU parser, which the 8.1 conversion would still need libdovi for).
+
+### 6.3 Robustness
+
+- `DoviRpuGuard` checks the RPU CRC (MPEG-2 CRC32 over the unescaped bytes) and pre-scans for the paths
+  on which libdovi aborts, before libdovi, which is `panic=abort` and parses before it checks the CRC:
+  a polynomial piece with order 1 and linear interpolation (`unimplemented!` in the parser and the
+  writer), a reshaping curve that mixes polynomial and MMR pieces (parses, then the writer indexes the
+  polynomial list per piece out of bounds; mode 2 keeps the mapping of a MEL or residual-free RPU, only
+  an FEL RPU's is dropped before the write), pivot and block counts the payload cannot hold, and
+  display-management block lengths the spec does not define. This is a list of known paths, not a proof.
+  `DoviRpuGuardTests` holds each of them, including that the same RPU without the mix converts and
+  writes. `DoviCrcValidFuzzTests` mutates synthetic Profile 7 RPUs built in the test source (an FEL and
+  two MEL, so it runs without clips) and each clip's RPU when the clips are present, repairs the CRC, and
+  pushes every mutant the guard lets through the production parse, convert and write; `DoviFelFuzzTests`
+  does the same for corrupt RPUs and access units without the CRC repair. The random mutations do not
+  build the mixed curve themselves (it takes an insertion, not a bit flip), so that case rests on the
+  targeted tests. The clip-based fuzz and real-file tests show as skipped, not passed, without the clips.
+- `CustomBlockSource` addresses the packet payload, not `buf->data` (Matroska packets sit 4 bytes in).
+- Pairing is key-based: `settledBlKeys` (ring of 64) decides whether an enhancement frame's base layer
+  has already gone out.
+- `DoviFelComposer`'s completion handler keeps the in-flight semaphore alive past the composer.
+
+## 7. Document map
+
+| Document | Role |
+|---|---|
+| this file | design, implementation, evidence, verification |
+| [formats.md](formats.md#dolby-vision-signaling) | Profile 7 behaviour as a host sees it |
+| [api.md](api.md) | `preferDualLayerDolbyVision`, `dolbyVisionHandling` |
+| [cli.md](cli.md) | `feltest`, `dvsurvey`, `dovitest`, `play --cycle-el` (with the tooling PR) |
diff --git a/docs/formats.md b/docs/formats.md
index e1de54ebf..8862a8c88 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -198,7 +198,9 @@ For DV streams the demuxer surfaces the source's `AVDOVIDecoderConfigurationReco
 
 AV1+DV emits a bare `dav1.10.<dvLevel>` primary for Profile 10.0 (DV-only, no base layer to fall back to), and an `av01...` primary plus a supplemental entry for the two cross-compatible profiles: `dav1.10.<dvLevel>/db1p` with `VIDEO-RANGE=PQ` for Profile 10.1 (HDR10-compat base) and `dav1.10.<dvLevel>/db4h` with `VIDEO-RANGE=HLG` for Profile 10.4 (HLG-compat base), on hardware-AV1 hosts. Same split as HEVC: the `dav1` sample entry belongs to the profile without a base layer the way `dvh1` belongs to Profile 5, and a cross-compatible profile carries its base layer's own sample entry so a client that cannot read Dolby Vision still plays it.
 
-**Profile 7** (dual-layer, the common UHD-Blu-ray remux profile) has no decoder on any Apple platform, so the engine converts it to single-layer **Profile 8.1** live during muxing: the RPU of each video packet is rewritten with [libdovi](https://github.com/superuser404notfound/LibDovi) (`dovi_convert_rpu_with_mode`, mode 2, the same transform as `dovi_tool -m 2`), the enhancement-layer NALs are dropped, and the container `dvvC` is set to Profile 8.1. The conversion runs on every display and the result is served exactly as a Profile 8.1 is: on a DV-capable display this means real Dolby Vision (`dvh1.08/db1p` supplemental) instead of the plain HDR10 base, and on a display without Dolby Vision the kept `dvvC` lets AVPlayer tone-map from the RPU rather than from the base layer's static metadata, the way mpv plays Profile 7 without an EL decoder. It used to skip the conversion and strip the record there, which cost every Mac (no per-mode table) and every HDR10 / SDR panel the RPU and shipped the enhancement layer into segments nothing decodes. The conversion is loss-free relative to what Apple could show before (the enhancement layer was never decodable on Apple hardware). MEL and FEL sources are both handled; a Full Enhancement Layer (FEL) source is logged, since its enhancement layer, which a native Profile 7 player would fold in, is discarded here while a Minimal (MEL) source loses nothing. Any per-packet conversion failure drops that RPU so the frame degrades to the clean HDR10 base, rather than shipping a Profile 7 RPU inside a container already declared 8.1. A session that converts publishes `dolbyVisionConversion = .profile7ToProfile81`, so a host label can name the profile actually served next to `sourceDVProfile`.
+**Profile 7** (dual-layer, the common UHD-Blu-ray remux profile) is handled according to `LoadOptions.preferDualLayerDolbyVision` (default `false`: dual-layer composition is opt-in) and `LoadOptions.dolbyVisionHandling`:
+- **Dual-layer composition (`preferDualLayerDolbyVision = true`, `dolbyVisionHandling` `.automatic`, `el_type` FEL, VideoToolbox HEVC hardware decode)**: Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`. Each packet is split into the 4K base layer (BL), the enhancement layer (EL, typically 1080p, carried in `unspec63` NAL units) and the RPU (`unspec62`). Both layers decode in their own `VTDecompressionSession`; `DoviFelComposer` applies the RPU's reshaping (polynomial luma, MMR chroma) and the inverse-NLQ residual from the upsampled EL at 12-bit precision, then an ordered 8×8 Bayer dither (inverted on odd frames) takes the result to 10-bit P010 for `AVSampleBufferDisplayLayer`. The composed frame also carries the RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, with `DolbyCompatibilityID` set to the string `"1"`; tvOS 27 reads it on every frame and applies Dolby Vision display management, so L1 / L2 dynamic metadata reaches the panel. A MEL source never reaches the dual-layer decoder: the route is FEL only, and MEL (nothing to compose) keeps the native route below. The route needs a seekable VOD and is logged once per Profile 7 load (`DV P7 dual-layer route: taken` / `not taken (<reason>)`). It does not consult the display: on a display that does not take Dolby Vision the route is still taken and the composed picture is presented with its attached metadata, tvOS deciding how; the native route would have played the converted Profile 8.1 there. The software host also plays an E-AC-3 Atmos track as its channel-bed core (no objects). The stream is classified by `el_type` alone; an RPU that sets `disable_residual_flag` only switches the residual off for that frame and never changes the classification. See [dolby-vision-fel.md](dolby-vision-fel.md) for the design.
+- **Single-layer conversion (the default: `preferDualLayerDolbyVision = false`, or no VideoToolbox HEVC hardware decode)**: No Apple platform has a Profile 7 decoder, so the engine converts the stream to single-layer **Profile 8.1** live during muxing: the RPU of each video packet is rewritten with [libdovi](https://github.com/superuser404notfound/LibDovi) (`dovi_convert_rpu_with_mode`, mode 2, the same transform as `dovi_tool -m 2`), the enhancement-layer NALs are dropped, and the container `dvvC` is set to Profile 8.1. The conversion runs on every display and the result is served exactly as a Profile 8.1 is: on a DV-capable display this means real Dolby Vision (`dvh1.08/db1p` supplemental) instead of the plain HDR10 base, and on a display without Dolby Vision the kept `dvvC` lets AVPlayer tone-map from the RPU rather than from the base layer's static metadata, the way mpv plays Profile 7 without an EL decoder. It used to skip the conversion and strip the record there, which cost every Mac (no per-mode table) and every HDR10 / SDR panel the RPU and shipped the enhancement layer into segments nothing decodes. The conversion is loss-free relative to what Apple could show before (the enhancement layer was never decodable on Apple hardware). MEL and FEL sources are both handled; a Full Enhancement Layer (FEL) source is logged, since its enhancement layer, which a native Profile 7 player would fold in, is discarded on this route (the dual-layer route above keeps it) while a Minimal (MEL) source loses nothing. Any per-packet conversion failure drops that RPU so the frame degrades to the clean HDR10 base, rather than shipping a Profile 7 RPU inside a container already declared 8.1. A session that converts publishes `dolbyVisionConversion = .profile7ToProfile81`, so a host label can name the profile actually served next to `sourceDVProfile`.
 
 **SDR-compatible-base profiles** (HEVC **Profile 8.2**, AV1 **Profile 10.2**) carry a Rec.709 base layer that no Apple platform has a DV decoder for. The engine strips the `dvcC` / DV config and plays the base as plain `hvc1` / `av01` (logging `not DV-routable, playing Rec.709 base`); there is no Dolby Vision on any display for these, on DV panels and SDR panels alike.
 
@@ -540,7 +542,7 @@ A remote `.iso` / `.img` / `.udf` needs an origin that honours HTTP `Range`, bec
 
 **`cancel()` unblocks, it does not invalidate.** Its whole job is to wake a `read` that is parked so teardown does not hang; a memory or file reader leaves it at the default no-op. A reader the engine may rebuild in place must be able to serve again immediately afterwards, because the rebuild reuses it. Reading `cancel()` as terminal (the way a socket's in-flight-request cancel is terminal) is the difference between a rebuilt session and a dead one: the reopen fails on its first read and the session lands in `.error` carrying libavformat's `Operation not permitted`. What that death LOOKS like is the reader's own convention, so one host defect has two signatures: a latched reader whose read returns a negative value produces the `Operation not permitted` above, while one that returns `0` is mapped to `AVERROR_EOF` and the session ENDS instead of failing, which on a live source is a stream that was never supposed to have an end (cmcpherson274). The engine cancels a reader it intends to reuse exactly once, before the successor opens.
 
-**In-place rebuilds reuse the reader.** `reloadAtCurrentPosition()` and `reloadAtCurrentPosition(applying:)`, an audio-track switch, a disc-title switch and a background return all tear the pipeline down and reopen on the retained reader instead of reopening a URL, so a custom source gets the same session-preserving rebuild a URL source does. A reader that reports itself non-seekable is refused instead (`SessionReloadRefusal.customSourceNotSeekable`), since the rebuild cannot reposition it.
+**In-place rebuilds reuse the reader.** `reloadAtCurrentPosition()` and `reloadAtCurrentPosition(applying:)`, an audio-track switch, a disc-title switch and a background return all tear the pipeline down and reopen on the retained reader instead of reopening a URL, so a custom source gets the same session-preserving rebuild a URL source does (except that the Profile 7 dual-layer route is decided by `load()`: `reloadAtCurrentPosition(applying:)` refuses a `preferDualLayerDolbyVision` change (or a `dolbyVisionHandling` change while the preference is on) on a custom Profile 7 source with `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`). A reader that reports itself non-seekable is refused instead (`SessionReloadRefusal.customSourceNotSeekable`), since the rebuild cannot reposition it.
 
 **Where the reopen starts depends on whether the source is live.** A fresh `AVIOContext` always starts its byte axis at 0, so the reader's cursor and that axis have to agree, and there are two ways to make them:
 

From 73955ad2870070b5f985dc3b191f3f39773182d0 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:37:51 +0100
Subject: [PATCH 016/132] feat(probes): Dolby Vision pulse test (clip
 generator, tvOS host, filming harness, analysis)

Probes/DolbyVisionPulse: a reproducible measurement of whether a panel
follows Dolby Vision metadata. Clips keep the pixels constant and switch
only the RPU (or, for the enhancement-layer clip, only the residual) every
72 frames, so a phone filming the television shows whether the display
uses the metadata and the composed pixels. It is a measurement, not a unit
test, and it commits no media.

- Scripts: gen_pulse.py (pattern, RPU configs, EL residual design),
  build.sh, serve.py, run_tv.sh, cut.py (one phone recording per arm),
  analyze.py (verdict per arm), report.py (the change-per-patch table and
  phase-A levels), check_el.py (checks on the Mac that the EL clip carries
  the designed residual in phase B and none in A), dump_attachments.swift
  (what VideoToolbox attaches to a decoded frame), sim_recording.py (a fake
  recording that validates the analysis).
- Device/: a minimal tvOS host that plays the clips through AVPlayer,
  VideoToolbox and the FEL route (preferDualLayerDolbyVision). It uses only
  public engine API.
- CI: compiles the scripts and builds the host for the tvOS simulator, so a
  moved public API is found in CI instead of at the television.
- The pulse test is the measurement behind the consumption evidence in
  docs/dolby-vision-fel.md section 4.5, which arrived with the route PR.

No library code changes and no behaviour change. Public API: none. Not in
this PR: the aetherctl tooling. The host builds in CI; the rest needs a
television and a phone.

Checked here: Python and shell syntax of the scripts, swiftc -typecheck of
dump_attachments.swift, xcodebuild of the host for the tvOS simulator
(BUILD SUCCEEDED), swift build --build-tests of the package.
---
 .github/workflows/ci.yml                      |  24 ++
 CHANGELOG.md                                  |   1 +
 Probes/DolbyVisionPulse/.gitignore            |  11 +
 .../project.pbxproj                           | 342 ++++++++++++++++++
 .../contents.xcworkspacedata                  |   7 +
 .../xcschemes/DolbyVisionPulse.xcscheme       |  91 +++++
 .../Device/Host/DolbyVisionPulseHostApp.swift | 313 ++++++++++++++++
 .../DolbyVisionPulse/Device/Host/Info.plist   |  29 ++
 .../Device/Host/PulseLog.swift                |  26 ++
 .../Device/Host/PulseVideoToolbox.swift       | 220 +++++++++++
 Probes/DolbyVisionPulse/Device/project.yml    |  62 ++++
 Probes/DolbyVisionPulse/README.md             | 303 ++++++++++++++++
 Probes/DolbyVisionPulse/Scripts/analyze.py    | 339 +++++++++++++++++
 Probes/DolbyVisionPulse/Scripts/build.sh      | 135 +++++++
 Probes/DolbyVisionPulse/Scripts/check_el.py   | 226 ++++++++++++
 Probes/DolbyVisionPulse/Scripts/cut.py        | 144 ++++++++
 .../Scripts/dump_attachments.swift            |  72 ++++
 Probes/DolbyVisionPulse/Scripts/fel_count.py  | 168 +++++++++
 Probes/DolbyVisionPulse/Scripts/gen_pulse.py  | 298 +++++++++++++++
 Probes/DolbyVisionPulse/Scripts/report.py     | 114 ++++++
 Probes/DolbyVisionPulse/Scripts/run_tv.sh     |  95 +++++
 Probes/DolbyVisionPulse/Scripts/serve.py      |  72 ++++
 .../DolbyVisionPulse/Scripts/sim_recording.py |  77 ++++
 docs/dolby-vision-fel.md                      |   3 +-
 24 files changed, 3170 insertions(+), 2 deletions(-)
 create mode 100644 Probes/DolbyVisionPulse/.gitignore
 create mode 100644 Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj
 create mode 100644 Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.xcworkspace/contents.xcworkspacedata
 create mode 100644 Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/xcshareddata/xcschemes/DolbyVisionPulse.xcscheme
 create mode 100644 Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
 create mode 100644 Probes/DolbyVisionPulse/Device/Host/Info.plist
 create mode 100644 Probes/DolbyVisionPulse/Device/Host/PulseLog.swift
 create mode 100644 Probes/DolbyVisionPulse/Device/Host/PulseVideoToolbox.swift
 create mode 100644 Probes/DolbyVisionPulse/Device/project.yml
 create mode 100644 Probes/DolbyVisionPulse/README.md
 create mode 100755 Probes/DolbyVisionPulse/Scripts/analyze.py
 create mode 100755 Probes/DolbyVisionPulse/Scripts/build.sh
 create mode 100755 Probes/DolbyVisionPulse/Scripts/check_el.py
 create mode 100755 Probes/DolbyVisionPulse/Scripts/cut.py
 create mode 100644 Probes/DolbyVisionPulse/Scripts/dump_attachments.swift
 create mode 100755 Probes/DolbyVisionPulse/Scripts/fel_count.py
 create mode 100755 Probes/DolbyVisionPulse/Scripts/gen_pulse.py
 create mode 100755 Probes/DolbyVisionPulse/Scripts/report.py
 create mode 100755 Probes/DolbyVisionPulse/Scripts/run_tv.sh
 create mode 100755 Probes/DolbyVisionPulse/Scripts/serve.py
 create mode 100755 Probes/DolbyVisionPulse/Scripts/sim_recording.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3221315dd..553bf631a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -74,6 +74,15 @@ jobs:
       - name: build the transport probe (AE#377)
         run: swift build --build-tests --package-path Probes/TransportProbe
 
+      # The pulse test's scripts are Python, shell and Swift nobody runs in CI; a syntax error in one is found
+      # at the television. Compiling them is all that can be checked without a phone recording.
+      - name: Compile the Dolby Vision pulse scripts
+        run: |
+          python3 -m py_compile Probes/DolbyVisionPulse/Scripts/*.py
+          zsh -n Probes/DolbyVisionPulse/Scripts/build.sh
+          zsh -n Probes/DolbyVisionPulse/Scripts/run_tv.sh
+          swiftc -typecheck Probes/DolbyVisionPulse/Scripts/dump_attachments.swift
+
   build-tvos:
     name: xcodebuild (tvOS + visionOS Simulator)
     runs-on: xcode-27
@@ -115,6 +124,21 @@ jobs:
             -derivedDataPath .build/xcode-probe \
             CODE_SIGNING_ALLOWED=NO
 
+      # The Dolby Vision pulse host is the other device harness, and the one that links the engine
+      # itself, so it is also the one that breaks when a public API it uses moves. It plays clips on an
+      # Apple TV that someone films, runs nowhere in CI, and would otherwise be found out by the person
+      # who needed a measurement that evening. EXCLUDED_ARCHS for the reason given above: an app cannot
+      # link the x86_64 slice.
+      - name: Build the Dolby Vision pulse host (Probes/DolbyVisionPulse)
+        run: |
+          xcodebuild build \
+            -project Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj \
+            -scheme DolbyVisionPulse \
+            -destination 'generic/platform=tvOS Simulator' \
+            -derivedDataPath .build/xcode-pulse \
+            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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 269c12da4..f767bc611 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ the public-API contract.
 - **The Profile 7 dual-layer route is FEL only and capability gated, and says why.** `DualLayerRouteDecision` adds a real-time budget to the route: the base and enhancement layers together may need at most UHD 3840x2160 at 30 fps plus a 1920x1080 enhancement layer at 30 fps (a 24p UHD master uses 80%), otherwise the file keeps the native route, as MEL does and as does a box without hardware HEVC decode (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not). Every Profile 7 load logs one `DV P7 dual-layer route: taken (...)` or `not taken (<reason>)` line; the line is new, and with the preference off it is the only change.
 - **`AETHER_FEL_MEASURE` reports the signed FEL-minus-MEL mean per plane and luma band.** The diagnostic composes every Nth frame a second time with the residual off and compares the two; the signed mean says whether the residual brightens or darkens, which the absolute difference could not. It runs one sample at a time and skips a frame that arrives while one is in flight. Off by default; it is an environment-variable diagnostic, not API.
 - **The dual-layer decoder pairs the two layers by picture order.** `DualLayerPictureAlignment` derives each layer's display slot from its POC (`HEVCPictureOrderCount`, no decoding) and stamps each enhancement-layer packet with the time of the base-layer picture in the same slot, so a stream whose enhancement layer is coded with B-frames over a base layer without them pairs the right pictures. A stream whose layers share one GOP keeps every packet's own time. After a seek a layer pairs by access unit until its next sequence-opening IRAP.
+- **`Probes/DolbyVisionPulse`, a reproducible Dolby Vision pulse test.** Clips whose pixels are constant while only the RPU (or, for the enhancement-layer clip, only the residual) switches every 72 frames, counter clips whose base and enhancement layers each carry their own frame number (so a dropped or mispaired residual shows on screen), a tvOS host app that plays them through AVPlayer, VideoToolbox, and the FEL route, and scripts that build the clips, cut a phone recording per arm and read back whether the panel followed the metadata. It is the measurement behind [the FEL consumption evidence](docs/dolby-vision-fel.md#45-consumption-test-assets); the host builds in CI, the rest needs a television and a phone.
 
 ### Changed
 
diff --git a/Probes/DolbyVisionPulse/.gitignore b/Probes/DolbyVisionPulse/.gitignore
new file mode 100644
index 000000000..be9c2cfe9
--- /dev/null
+++ b/Probes/DolbyVisionPulse/.gitignore
@@ -0,0 +1,11 @@
+# Everything the scripts generate: clips, RPU binaries and configs, logs, recordings.
+out/
+*.mp4
+*.mov
+*.MOV
+*.hevc
+*.bin
+*.log
+recordings/
+.dd/
+__pycache__/
diff --git a/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj
new file mode 100644
index 000000000..a24a0aded
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj
@@ -0,0 +1,342 @@
+// !$*UTF8*$!
+{
+	archiveVersion = 1;
+	classes = {
+	};
+	objectVersion = 77;
+	objects = {
+
+/* Begin PBXBuildFile section */
+		1CC1EA98D9C5F77AAC72F7CC /* PulseVideoToolbox.swift in Sources */ = {isa = PBXBuildFile; fileRef = B9672B7938DDC09AAB435BC6 /* PulseVideoToolbox.swift */; };
+		77CB08AE958747D4126970C6 /* DolbyVisionPulseHostApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7BCA97A8853B09B4E7B4B99A /* DolbyVisionPulseHostApp.swift */; };
+		C3F88D052478C6D03F65C74C /* AetherEngine in Frameworks */ = {isa = PBXBuildFile; productRef = 5DDCF6DD2D95C3E73D4B2B5C /* AetherEngine */; };
+		FB3139445F0E0031753BB397 /* PulseLog.swift in Sources */ = {isa = PBXBuildFile; fileRef = DCACA2DF252349E564F73EAC /* PulseLog.swift */; };
+/* End PBXBuildFile section */
+
+/* Begin PBXFileReference section */
+		6EC0C4402B0A4CFAB2376CAB /* AetherEngine */ = {isa = PBXFileReference; lastKnownFileType = folder; name = AetherEngine; path = ../../..; sourceTree = SOURCE_ROOT; };
+		7BCA97A8853B09B4E7B4B99A /* DolbyVisionPulseHostApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DolbyVisionPulseHostApp.swift; sourceTree = "<group>"; };
+		81B68F565101F4AD4C23902A /* DolbyVisionPulseHost.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = DolbyVisionPulseHost.app; sourceTree = BUILT_PRODUCTS_DIR; };
+		B9672B7938DDC09AAB435BC6 /* PulseVideoToolbox.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PulseVideoToolbox.swift; sourceTree = "<group>"; };
+		DCACA2DF252349E564F73EAC /* PulseLog.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PulseLog.swift; sourceTree = "<group>"; };
+/* End PBXFileReference section */
+
+/* Begin PBXFrameworksBuildPhase section */
+		2BC4135493426C6DF7CC3B11 /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				C3F88D052478C6D03F65C74C /* AetherEngine in Frameworks */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXFrameworksBuildPhase section */
+
+/* Begin PBXGroup section */
+		877A8AC0E76ED624DD6E3BF6 /* Packages */ = {
+			isa = PBXGroup;
+			children = (
+				6EC0C4402B0A4CFAB2376CAB /* AetherEngine */,
+			);
+			name = Packages;
+			sourceTree = "<group>";
+		};
+		91F1FECFC9FBC63638DFB9F0 = {
+			isa = PBXGroup;
+			children = (
+				A0F3EC54F7CC8065A3A7DFAC /* Host */,
+				877A8AC0E76ED624DD6E3BF6 /* Packages */,
+				A0369D737D33D357FE77916A /* Products */,
+			);
+			sourceTree = "<group>";
+		};
+		A0369D737D33D357FE77916A /* Products */ = {
+			isa = PBXGroup;
+			children = (
+				81B68F565101F4AD4C23902A /* DolbyVisionPulseHost.app */,
+			);
+			name = Products;
+			sourceTree = "<group>";
+		};
+		A0F3EC54F7CC8065A3A7DFAC /* Host */ = {
+			isa = PBXGroup;
+			children = (
+				7BCA97A8853B09B4E7B4B99A /* DolbyVisionPulseHostApp.swift */,
+				DCACA2DF252349E564F73EAC /* PulseLog.swift */,
+				B9672B7938DDC09AAB435BC6 /* PulseVideoToolbox.swift */,
+			);
+			path = Host;
+			sourceTree = "<group>";
+		};
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+		1DDB0EFB1D0FFFD6D891F260 /* DolbyVisionPulseHost */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = AF89BEB4939AE144202F15AF /* Build configuration list for PBXNativeTarget "DolbyVisionPulseHost" */;
+			buildPhases = (
+				3DBDD39040B8692C0BA1124E /* Sources */,
+				2BC4135493426C6DF7CC3B11 /* Frameworks */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			name = DolbyVisionPulseHost;
+			packageProductDependencies = (
+				5DDCF6DD2D95C3E73D4B2B5C /* AetherEngine */,
+			);
+			productName = DolbyVisionPulseHost;
+			productReference = 81B68F565101F4AD4C23902A /* DolbyVisionPulseHost.app */;
+			productType = "com.apple.product-type.application";
+		};
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+		3E6283C4018EFBF976379C00 /* Project object */ = {
+			isa = PBXProject;
+			attributes = {
+				BuildIndependentTargetsInParallel = YES;
+				LastUpgradeCheck = 1430;
+				TargetAttributes = {
+					1DDB0EFB1D0FFFD6D891F260 = {
+						ProvisioningStyle = Automatic;
+					};
+				};
+			};
+			buildConfigurationList = 7345ED8B0955685E060F8EA6 /* Build configuration list for PBXProject "DolbyVisionPulse" */;
+			developmentRegion = en;
+			hasScannedForEncodings = 0;
+			knownRegions = (
+				Base,
+				en,
+			);
+			mainGroup = 91F1FECFC9FBC63638DFB9F0;
+			minimizedProjectReferenceProxies = 1;
+			packageReferences = (
+				A1D5E5D261EA7A828134329D /* XCLocalSwiftPackageReference "../../.." */,
+			);
+			preferredProjectObjectVersion = 77;
+			productRefGroup = A0369D737D33D357FE77916A /* Products */;
+			projectDirPath = "";
+			projectRoot = "";
+			targets = (
+				1DDB0EFB1D0FFFD6D891F260 /* DolbyVisionPulseHost */,
+			);
+		};
+/* End PBXProject section */
+
+/* Begin PBXSourcesBuildPhase section */
+		3DBDD39040B8692C0BA1124E /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				77CB08AE958747D4126970C6 /* DolbyVisionPulseHostApp.swift in Sources */,
+				FB3139445F0E0031753BB397 /* PulseLog.swift in Sources */,
+				1CC1EA98D9C5F77AAC72F7CC /* PulseVideoToolbox.swift in Sources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXSourcesBuildPhase section */
+
+/* Begin XCBuildConfiguration section */
+		058CE76FD1067ADB93FFA4B8 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = "App Icon & Top Shelf Image";
+				ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME = LaunchImage;
+				GENERATE_INFOPLIST_FILE = NO;
+				INFOPLIST_FILE = Host/Info.plist;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = "$(PULSE_BUNDLE_PREFIX).host";
+				SDKROOT = appletvos;
+				TARGETED_DEVICE_FAMILY = 3;
+			};
+			name = Release;
+		};
+		42160C4F45DACBA011092C36 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				CODE_SIGN_STYLE = Automatic;
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = dwarf;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_TESTABILITY = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = YES;
+				GCC_C_LANGUAGE_STANDARD = gnu11;
+				GCC_DYNAMIC_NO_PIC = NO;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_OPTIMIZATION_LEVEL = 0;
+				GCC_PREPROCESSOR_DEFINITIONS = (
+					"$(inherited)",
+					"DEBUG=1",
+				);
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
+				MTL_FAST_MATH = YES;
+				ONLY_ACTIVE_ARCH = YES;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				PULSE_BUNDLE_PREFIX = de.superuser404.dolbyvisionpulse;
+				SDKROOT = appletvos;
+				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
+				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+				SWIFT_VERSION = 6.0;
+				TARGETED_DEVICE_FAMILY = 3;
+				TVOS_DEPLOYMENT_TARGET = 18.0;
+			};
+			name = Debug;
+		};
+		58026C6AF77395FFB0ED71C2 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ASSETCATALOG_COMPILER_APPICON_NAME = "App Icon & Top Shelf Image";
+				ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME = LaunchImage;
+				GENERATE_INFOPLIST_FILE = NO;
+				INFOPLIST_FILE = Host/Info.plist;
+				LD_RUNPATH_SEARCH_PATHS = (
+					"$(inherited)",
+					"@executable_path/Frameworks",
+				);
+				PRODUCT_BUNDLE_IDENTIFIER = "$(PULSE_BUNDLE_PREFIX).host";
+				SDKROOT = appletvos;
+				TARGETED_DEVICE_FAMILY = 3;
+			};
+			name = Debug;
+		};
+		6CACE8A95F8A6D578B4F7D53 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				ALWAYS_SEARCH_USER_PATHS = NO;
+				CLANG_ANALYZER_NONNULL = YES;
+				CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+				CLANG_CXX_LANGUAGE_STANDARD = "gnu++14";
+				CLANG_CXX_LIBRARY = "libc++";
+				CLANG_ENABLE_MODULES = YES;
+				CLANG_ENABLE_OBJC_ARC = YES;
+				CLANG_ENABLE_OBJC_WEAK = YES;
+				CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+				CLANG_WARN_BOOL_CONVERSION = YES;
+				CLANG_WARN_COMMA = YES;
+				CLANG_WARN_CONSTANT_CONVERSION = YES;
+				CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+				CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+				CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+				CLANG_WARN_EMPTY_BODY = YES;
+				CLANG_WARN_ENUM_CONVERSION = YES;
+				CLANG_WARN_INFINITE_RECURSION = YES;
+				CLANG_WARN_INT_CONVERSION = YES;
+				CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+				CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+				CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+				CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+				CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+				CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+				CLANG_WARN_STRICT_PROTOTYPES = YES;
+				CLANG_WARN_SUSPICIOUS_MOVE = YES;
+				CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+				CLANG_WARN_UNREACHABLE_CODE = YES;
+				CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+				CODE_SIGN_STYLE = Automatic;
+				COPY_PHASE_STRIP = NO;
+				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+				ENABLE_NS_ASSERTIONS = NO;
+				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				ENABLE_USER_SCRIPT_SANDBOXING = YES;
+				GCC_C_LANGUAGE_STANDARD = gnu11;
+				GCC_NO_COMMON_BLOCKS = YES;
+				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+				GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+				GCC_WARN_UNDECLARED_SELECTOR = YES;
+				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+				GCC_WARN_UNUSED_FUNCTION = YES;
+				GCC_WARN_UNUSED_VARIABLE = YES;
+				MTL_ENABLE_DEBUG_INFO = NO;
+				MTL_FAST_MATH = YES;
+				PRODUCT_NAME = "$(TARGET_NAME)";
+				PULSE_BUNDLE_PREFIX = de.superuser404.dolbyvisionpulse;
+				SDKROOT = appletvos;
+				SWIFT_COMPILATION_MODE = wholemodule;
+				SWIFT_OPTIMIZATION_LEVEL = "-O";
+				SWIFT_VERSION = 6.0;
+				TARGETED_DEVICE_FAMILY = 3;
+				TVOS_DEPLOYMENT_TARGET = 18.0;
+			};
+			name = Release;
+		};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+		7345ED8B0955685E060F8EA6 /* Build configuration list for PBXProject "DolbyVisionPulse" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				42160C4F45DACBA011092C36 /* Debug */,
+				6CACE8A95F8A6D578B4F7D53 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Debug;
+		};
+		AF89BEB4939AE144202F15AF /* Build configuration list for PBXNativeTarget "DolbyVisionPulseHost" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				58026C6AF77395FFB0ED71C2 /* Debug */,
+				058CE76FD1067ADB93FFA4B8 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Debug;
+		};
+/* End XCConfigurationList section */
+
+/* Begin XCLocalSwiftPackageReference section */
+		A1D5E5D261EA7A828134329D /* XCLocalSwiftPackageReference "../../.." */ = {
+			isa = XCLocalSwiftPackageReference;
+			relativePath = ../../..;
+		};
+/* End XCLocalSwiftPackageReference section */
+
+/* Begin XCSwiftPackageProductDependency section */
+		5DDCF6DD2D95C3E73D4B2B5C /* AetherEngine */ = {
+			isa = XCSwiftPackageProductDependency;
+			productName = AetherEngine;
+		};
+/* End XCSwiftPackageProductDependency section */
+	};
+	rootObject = 3E6283C4018EFBF976379C00 /* Project object */;
+}
diff --git a/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.xcworkspace/contents.xcworkspacedata b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.xcworkspace/contents.xcworkspacedata
new file mode 100644
index 000000000..919434a62
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.xcworkspace/contents.xcworkspacedata
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "self:">
+   </FileRef>
+</Workspace>
diff --git a/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/xcshareddata/xcschemes/DolbyVisionPulse.xcscheme b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/xcshareddata/xcschemes/DolbyVisionPulse.xcscheme
new file mode 100644
index 000000000..5edd4a080
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/xcshareddata/xcschemes/DolbyVisionPulse.xcscheme
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1430"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      runPostActionsOnFailure = "NO">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "1DDB0EFB1D0FFFD6D891F260"
+               BuildableName = "DolbyVisionPulseHost.app"
+               BlueprintName = "DolbyVisionPulseHost"
+               ReferencedContainer = "container:DolbyVisionPulse.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      onlyGenerateCoverageForSpecifiedTargets = "NO">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "1DDB0EFB1D0FFFD6D891F260"
+            BuildableName = "DolbyVisionPulseHost.app"
+            BlueprintName = "DolbyVisionPulseHost"
+            ReferencedContainer = "container:DolbyVisionPulse.xcodeproj">
+         </BuildableReference>
+      </MacroExpansion>
+      <Testables>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "1DDB0EFB1D0FFFD6D891F260"
+            BuildableName = "DolbyVisionPulseHost.app"
+            BlueprintName = "DolbyVisionPulseHost"
+            ReferencedContainer = "container:DolbyVisionPulse.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+      <CommandLineArguments>
+      </CommandLineArguments>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "1DDB0EFB1D0FFFD6D891F260"
+            BuildableName = "DolbyVisionPulseHost.app"
+            BlueprintName = "DolbyVisionPulseHost"
+            ReferencedContainer = "container:DolbyVisionPulse.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift b/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
new file mode 100644
index 000000000..4dd62a30a
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
@@ -0,0 +1,313 @@
+import AetherEngine
+import AVFoundation
+import AVKit
+import CoreMedia
+import SwiftUI
+import UIKit
+
+// Device harness for the Dolby Vision pulse test (see ../../README.md). Every arm plays a clip whose
+// pixels are constant while only the RPU (or, for the EL clip, only the residual) switches, so a
+// camera pointed at the television can tell whether the metadata reached the panel.
+//
+// Arms come from the environment variable `PULSE_ARMS`, which `devicectl device process launch
+// --environment-variables` does deliver to an app process:
+//
+//   PULSE_ARMS="label|mode|url[|k=v;k=v],label|mode|url,..."
+//
+// Arms play back to back with a 5 s slate naming the arm in between, so one phone recording covers
+// the whole sequence. Modes:
+//
+// - `avplayer`: plain AVPlayer + AVPlayerLayer on the file (Apple's own path, the positive control).
+// - `vt`: AVAssetReader (VideoToolbox) output straight into AVSampleBufferDisplayLayer, with the
+//   attachments VideoToolbox set.
+// - `vtcopy`: as `vt`, but every frame copied into a buffer from our own IOSurface pool, with all of
+//   VideoToolbox's propagated attachments (Dolby Vision RPU included) copied across byte for byte.
+// - `vtstrip`: as `vtcopy`, without `DolbyVisionRPUData` / `DolbyCompatibilityID`.
+// - `engine`: AetherEngine with `preferDualLayerDolbyVision: true` (a Profile 7 FEL clip takes the
+//   dual-layer route).
+// - `enginenofel`: as `engine` with `preferDualLayerDolbyVision: false` (native 8.1 route, EL dropped).
+// - `soak`: `engine` for `minutes=` with a `seeks=at@to,...` schedule, sampled once a second, ending in
+//   one `soak summary` line.
+//
+// The VT modes request Dolby Vision display criteria from the track's own format description, as an
+// app on this path would.
+
+@main
+struct DolbyVisionPulseHostApp: App {
+    var body: some Scene {
+        WindowGroup {
+            RootView()
+                .onAppear {
+                    // About eleven minutes of playback, partly not AVPlayer: keep the screensaver away.
+                    UIApplication.shared.isIdleTimerDisabled = true
+                }
+        }
+    }
+}
+
+private struct RootView: View {
+    var body: some View {
+        if let arms = PulseArm.fromEnvironment() {
+            PulseHarnessView(arms: arms)
+        } else {
+            VStack(alignment: .leading, spacing: 24) {
+                Text("Dolby Vision pulse host").font(.title2)
+                Text("No PULSE_ARMS in the environment.").font(.title3)
+                Text("""
+                    Launch with devicectl device process launch --environment-variables \
+                    '{"PULSE_ARMS":"label|mode|url,..."}'. Scripts/run_tv.sh does it.
+                    """)
+                    .foregroundStyle(.secondary)
+            }
+            .padding(80)
+            .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
+        }
+    }
+}
+
+struct PulseArm {
+    let label: String
+    let mode: String
+    let url: URL
+    /// Optional 4th field, `key=value;key=value` (soak: `minutes=5;seeks=60@1800,150@600`).
+    let params: [String: String]
+
+    static func fromEnvironment() -> [PulseArm]? {
+        guard let raw = ProcessInfo.processInfo.environment["PULSE_ARMS"] else { return nil }
+        return parse(raw)
+    }
+
+    static func parse(_ raw: String) -> [PulseArm]? {
+        // Arms are comma separated, but a soak's `seeks=` list contains commas too: a new arm starts
+        // only at a piece shaped `label|mode|...`, anything else belongs to the previous arm's params.
+        var items: [String] = []
+        for piece in raw.split(separator: ",", omittingEmptySubsequences: true).map(String.init) {
+            if piece.contains("|") || items.isEmpty { items.append(piece) } else { items[items.count - 1] += "," + piece }
+        }
+        let arms = items.compactMap { item -> PulseArm? in
+            let parts = item.split(separator: "|", maxSplits: 3).map(String.init)
+            guard parts.count >= 3, let url = URL(string: parts[2]) else { return nil }
+            var params: [String: String] = [:]
+            if parts.count == 4 {
+                for kv in parts[3].split(separator: ";") {
+                    let p = kv.split(separator: "=", maxSplits: 1).map(String.init)
+                    if p.count == 2 { params[p[0]] = p[1] }
+                }
+            }
+            return PulseArm(label: parts[0], mode: parts[1], url: url, params: params)
+        }
+        return arms.isEmpty ? nil : arms
+    }
+}
+
+struct PulseHarnessView: View {
+    let arms: [PulseArm]
+    @State private var engine: AetherEngine?
+    @State private var slate: String = ""
+    @State private var host = PulseHostView()
+
+    var body: some View {
+        ZStack {
+            Color.black.ignoresSafeArea()
+            PulseHostRepresentable(host: host).ignoresSafeArea()
+            if let engine {
+                AetherPlayerSurface(engine: engine).ignoresSafeArea()
+            }
+            if !slate.isEmpty {
+                VStack(spacing: 30) {
+                    Text(slate).font(.system(size: 160, weight: .heavy)).foregroundColor(.white)
+                    // Live UTC clock: one readable slate frame pins the video time to wall time.
+                    TimelineView(.periodic(from: .now, by: 0.1)) { ctx in
+                        Text(Self.clock(ctx.date))
+                            .font(.system(size: 96, weight: .bold).monospacedDigit())
+                            .foregroundColor(.white)
+                    }
+                    Text("dv-pulse").font(.system(size: 48)).foregroundColor(.gray)
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+                .background(Color.black)
+            }
+        }
+        .task { await run() }
+    }
+
+    private static func clock(_ d: Date) -> String {
+        let s = d.timeIntervalSince1970
+        let day = s.truncatingRemainder(dividingBy: 86400)
+        return String(format: "%02d:%02d:%04.1f UTC", Int(day / 3600), Int(day / 60) % 60,
+                      day.truncatingRemainder(dividingBy: 60))
+    }
+
+    @MainActor
+    private func run() async {
+        EngineLog.handler = { line in
+            PulseLog.shared.note(line)
+            print(line)
+            fflush(stdout)
+        }
+        let started = Date()
+        // Wall-clock epoch seconds on every line, so the phone video (whose creation date and the
+        // slate clock give its own wall-clock start) can be cut per arm afterwards.
+        let say: @Sendable (String) -> Void = { s in
+            let now = Date()
+            let line = String(format: "[Pulse] wall=%.3f t=%.1f %@", now.timeIntervalSince1970,
+                              now.timeIntervalSince(started), s)
+            print(line)
+            fflush(stdout)
+            PulseLog.shared.note(line)
+        }
+        say("sequence: " + arms.map { "\($0.label)(\($0.mode))" }.joined(separator: " "))
+        for (n, arm) in arms.enumerated() {
+            slate = "\(n + 1)/\(arms.count)  \(arm.label)"
+            host.window?.avDisplayManager.preferredDisplayCriteria = nil
+            say("slate \(arm.label)")
+            try? await Task.sleep(nanoseconds: 5_000_000_000)
+            slate = ""
+            say("arm \(arm.label) start mode=\(arm.mode) url=\(arm.url.lastPathComponent)")
+            switch arm.mode {
+            case "avplayer":
+                await host.playAVPlayer(arm.url, log: say)
+            case "vt", "vtcopy", "vtstrip":
+                await host.playVT(arm.url, mode: arm.mode, log: say)
+            case "engine":
+                await playEngine(arm.url, fel: true, log: say)
+            case "enginenofel":
+                await playEngine(arm.url, fel: false, log: say)
+            case "soak":
+                await playSoak(arm, log: say)
+            default:
+                say("unknown mode \(arm.mode), skipped")
+            }
+            say("arm \(arm.label) end")
+        }
+        slate = "done"
+        host.window?.avDisplayManager.preferredDisplayCriteria = nil
+        try? await Task.sleep(nanoseconds: 3_000_000_000)
+        say("sequence done")
+        exit(0)
+    }
+
+    @MainActor
+    private func playEngine(_ url: URL, fel: Bool, log: @Sendable (String) -> Void) async {
+        guard let e = try? AetherEngine() else { log("engine init failed"); return }
+        engine = e
+        do {
+            try await e.load(url: url, startPosition: nil,
+                             options: LoadOptions(dolbyVisionHandling: .automatic, preferDualLayerDolbyVision: fel,
+                                                  audioBridgeMode: .surroundCompat),
+                             audioSourceStreamIndex: nil)
+            e.play()
+        } catch {
+            log("engine load failed: \(error)")
+            engine = nil
+            return
+        }
+        let deadline = Date().addingTimeInterval(80)
+        while Date() < deadline, e.state != .ended {
+            try? await Task.sleep(nanoseconds: 500_000_000)
+        }
+        log("engine state=\(e.state) t=\(e.currentTime)")
+        e.stop()
+        engine = nil
+    }
+
+    /// Long-run FEL playback with a seek schedule. Measures only what the engine exposes publicly:
+    /// - droppedFrames: `liveTelemetry.droppedFrameCount` (render synchronizer's dropped frames on the
+    ///   software path, session total; nil reads as -1).
+    /// - composeFailures: sum of `composeFailures=` over the engine's 1 Hz `[DualLayer] summary` log
+    ///   lines (seen through EngineLog.handler; the counter itself is internal). Stays 0 if the FEL
+    ///   route never ran, so `route=` is the thing to check first.
+    /// - footprint: task_vm_info phys_footprint, sampled each second.
+    @MainActor
+    private func playSoak(_ arm: PulseArm, log: @Sendable (String) -> Void) async {
+        let minutes = arm.params["minutes"].flatMap(Double.init) ?? 5
+        var seeks: [(at: Double, to: Double)] = []
+        for item in (arm.params["seeks"] ?? "").split(separator: ",") {
+            let p = item.split(separator: "@")
+            if p.count == 2, let at = Double(p[0]), let to = Double(p[1]) { seeks.append((at, to)) }
+        }
+        seeks.sort { $0.at < $1.at }
+        let tally = SoakTally()
+        let previous = EngineLog.handler
+        EngineLog.handler = { line in
+            previous?(line)
+            tally.ingest(line)
+        }
+        defer { EngineLog.handler = previous }
+        guard let e = try? AetherEngine() else { log("engine init failed"); return }
+        engine = e
+        do {
+            try await e.load(url: arm.url, startPosition: nil,
+                             options: LoadOptions(dolbyVisionHandling: .automatic, preferDualLayerDolbyVision: true,
+                                                  audioBridgeMode: .surroundCompat),
+                             audioSourceStreamIndex: nil)
+            e.play()
+        } catch {
+            log("engine load failed: \(error)")
+            engine = nil
+            return
+        }
+        log("soak start minutes=\(minutes) seeks=\(seeks.count)")
+        let started = Date()
+        let deadline = started.addingTimeInterval(minutes * 60)
+        var peak = Self.footprintMB()
+        var played = 0.0
+        var nSeeks = 0
+        var lastTick = Date()
+        while Date() < deadline {
+            try? await Task.sleep(nanoseconds: 1_000_000_000)
+            let now = Date()
+            if e.state == .playing { played += now.timeIntervalSince(lastTick) }
+            lastTick = now
+            peak = max(peak, Self.footprintMB())
+            if let next = seeks.first, now.timeIntervalSince(started) >= next.at {
+                seeks.removeFirst()
+                nSeeks += 1
+                await e.seek(to: next.to)
+                log(String(format: "seek to=%.1f landed=%.1f", next.to, e.currentTime))
+                lastTick = Date()
+            }
+            if e.state == .ended { log("soak ended early"); break }
+        }
+        let dropped = e.liveTelemetry?.droppedFrameCount ?? -1
+        let route = tally.sawDualLayer ? "FEL" : "\(e.videoRoute.rawValue)-noDualLayerSummary"
+        log(String(format: "soak summary: played=%.0fs seeks=%d droppedFrames=%d composeFailures=%d peakFootprintMB=%d endFootprintMB=%d route=%@",
+                   played, nSeeks, dropped, tally.composeFailures, peak, Self.footprintMB(), route))
+        e.stop()
+        engine = nil
+    }
+
+    /// `phys_footprint` (what jetsam judges), MB.
+    static func footprintMB() -> Int {
+        var info = task_vm_info_data_t()
+        var count = mach_msg_type_number_t(MemoryLayout<task_vm_info_data_t>.size / MemoryLayout<integer_t>.size)
+        let kr = withUnsafeMutablePointer(to: &info) {
+            $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) {
+                task_info(mach_task_self_, task_flavor_t(TASK_VM_INFO), $0, &count)
+            }
+        }
+        return kr == KERN_SUCCESS ? Int(info.phys_footprint / 1024 / 1024) : -1
+    }
+}
+
+/// Accumulates the engine's `[DualLayer] summary: ... composeFailures=N ...` lines (1 Hz, per-second deltas).
+private final class SoakTally: @unchecked Sendable {
+    private let lock = NSLock()
+    private var failures = 0
+    private var seen = false
+    var composeFailures: Int { lock.lock(); defer { lock.unlock() }; return failures }
+    var sawDualLayer: Bool { lock.lock(); defer { lock.unlock() }; return seen }
+    func ingest(_ line: String) {
+        guard line.contains("[DualLayer] summary:") else { return }
+        lock.lock(); defer { lock.unlock() }
+        seen = true
+        if let r = line.range(of: "composeFailures="),
+           let n = Int(line[r.upperBound...].prefix { $0.isNumber }) { failures += n }
+    }
+}
+
+private struct PulseHostRepresentable: UIViewRepresentable {
+    let host: PulseHostView
+    func makeUIView(context: Context) -> PulseHostView { host }
+    func updateUIView(_ uiView: PulseHostView, context: Context) {}
+}
diff --git a/Probes/DolbyVisionPulse/Device/Host/Info.plist b/Probes/DolbyVisionPulse/Device/Host/Info.plist
new file mode 100644
index 000000000..00222c321
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/Host/Info.plist
@@ -0,0 +1,29 @@
+<?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>CFBundleDevelopmentRegion</key>
+	<string>$(DEVELOPMENT_LANGUAGE)</string>
+	<key>CFBundleDisplayName</key>
+	<string>Dolby Vision pulse</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoads</key>
+		<true/>
+	</dict>
+</dict>
+</plist>
diff --git a/Probes/DolbyVisionPulse/Device/Host/PulseLog.swift b/Probes/DolbyVisionPulse/Device/Host/PulseLog.swift
new file mode 100644
index 000000000..0d1a476d2
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/Host/PulseLog.swift
@@ -0,0 +1,26 @@
+import Foundation
+
+/// A tiny file logger: every line the harness and the engine print also lands in
+/// `Library/Caches/pulse-log.txt`, which `devicectl device copy from` can pull after a run, including
+/// after a crash that took the console with it. Truncated at launch.
+final class PulseLog: @unchecked Sendable {
+    static let shared = PulseLog()
+
+    private let queue = DispatchQueue(label: "pulse.log")
+    private let url: URL
+    private var handle: FileHandle?
+
+    private init() {
+        let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
+        url = caches.appendingPathComponent("pulse-log.txt")
+        FileManager.default.createFile(atPath: url.path, contents: nil)
+        handle = try? FileHandle(forWritingTo: url)
+    }
+
+    func note(_ line: String) {
+        queue.async { [self] in
+            guard let data = (line + "\n").data(using: .utf8) else { return }
+            try? handle?.write(contentsOf: data)
+        }
+    }
+}
diff --git a/Probes/DolbyVisionPulse/Device/Host/PulseVideoToolbox.swift b/Probes/DolbyVisionPulse/Device/Host/PulseVideoToolbox.swift
new file mode 100644
index 000000000..04f6a6bd4
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/Host/PulseVideoToolbox.swift
@@ -0,0 +1,220 @@
+import AVFoundation
+import AVKit
+import CoreMedia
+import UIKit
+
+// The AVPlayer and VideoToolbox arms of the pulse harness: the hosts the engine's own route is
+// compared against. None of this touches AetherEngine.
+
+final class PulseHostView: UIView {
+
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        layer.sublayers?.forEach { $0.frame = bounds }
+    }
+
+    @MainActor
+    func playAVPlayer(_ url: URL, log: @escaping @Sendable (String) -> Void) async {
+        let item = AVPlayerItem(url: url)
+        let player = AVPlayer(playerItem: item)
+        // AVPlayerLayer has no automatic criteria (that is AVPlayerViewController's); request them from the
+        // track's own format description exactly as the VT arms do.
+        if let track = try? await item.asset.loadTracks(withMediaType: .video).first,
+           let fd = try? await track.load(.formatDescriptions).first,
+           let fps = try? await track.load(.nominalFrameRate) {
+            await requestCriteria(fd: fd, fps: fps, log: log)
+        }
+        let pl = AVPlayerLayer(player: player)
+        pl.frame = bounds
+        pl.videoGravity = .resizeAspect
+        layer.addSublayer(pl)
+        player.play()
+        let deadline = Date().addingTimeInterval(80)
+        let duration = (try? await item.asset.load(.duration).seconds) ?? 66
+        while Date() < deadline, item.status != .failed, player.currentTime().seconds < duration - 0.2 {
+            try? await Task.sleep(nanoseconds: 500_000_000)
+        }
+        log("avplayer status=\(item.status.rawValue) error=\(String(describing: item.error)) t=\(player.currentTime().seconds)")
+        player.pause()
+        pl.removeFromSuperlayer()
+    }
+
+    @MainActor
+    func playVT(_ url: URL, mode: String, log: @escaping @Sendable (String) -> Void) async {
+        do {
+            // AVAssetReader only reads local files: fetch the clip into the app's temp dir first.
+            var localURL = url
+            if !url.isFileURL {
+                let (tmp, _) = try await URLSession.shared.download(from: url)
+                localURL = FileManager.default.temporaryDirectory.appendingPathComponent(url.lastPathComponent)
+                try? FileManager.default.removeItem(at: localURL)
+                try FileManager.default.moveItem(at: tmp, to: localURL)
+                log("downloaded \(url.lastPathComponent) to temp")
+            }
+            let asset = AVURLAsset(url: localURL)
+            guard let track = try await asset.loadTracks(withMediaType: .video).first,
+                  let fd = try await track.load(.formatDescriptions).first else { log("no video track"); return }
+            let fps = try await track.load(.nominalFrameRate)
+            await requestCriteria(fd: fd, fps: fps, log: log)
+
+            let reader = try AVAssetReader(asset: asset)
+            let out = AVAssetReaderTrackOutput(track: track, outputSettings: [
+                kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+                kCVPixelBufferIOSurfacePropertiesKey as String: [String: Any]()])
+            out.alwaysCopiesSampleData = false
+            reader.add(out)
+            guard reader.startReading() else { log("reader failed: \(String(describing: reader.error))"); return }
+
+            let dl = AVSampleBufferDisplayLayer()
+            dl.frame = bounds
+            dl.videoGravity = .resizeAspect
+            var tb: CMTimebase?
+            CMTimebaseCreateWithSourceClock(allocator: kCFAllocatorDefault, sourceClock: CMClockGetHostTimeClock(), timebaseOut: &tb)
+            guard let tb else { log("timebase failed"); return }
+            dl.controlTimebase = tb
+            layer.addSublayer(dl)
+
+            let renderer = dl.sampleBufferRenderer
+            let queue = DispatchQueue(label: "dv-pulse.feed")
+            let state = FeedState()
+            let copier = PulseFrameCopier()
+            nonisolated(unsafe) let output = out
+            nonisolated(unsafe) let r = renderer
+            renderer.requestMediaDataWhenReady(on: queue) {
+                while r.isReadyForMoreMediaData {
+                    guard let sb = output.copyNextSampleBuffer() else {
+                        r.stopRequestingMediaData()
+                        state.finish()
+                        return
+                    }
+                    let n = state.count
+                    let pts = CMSampleBufferGetPresentationTimeStamp(sb)
+                    if n == 0 {
+                        CMTimebaseSetTime(tb, time: CMTimeSubtract(pts, CMTime(value: 1, timescale: 4)))
+                        CMTimebaseSetRate(tb, rate: 1)
+                    }
+                    guard let enq = copier.transform(sb, mode: mode) else { state.fail(); continue }
+                    if n < 2 || n == 150 {
+                        let pb = CMSampleBufferGetImageBuffer(enq)!
+                        let atts = CVBufferCopyAttachments(pb, .shouldPropagate) as? [String: Any] ?? [:]
+                        let rpu = (atts["DolbyVisionRPUData"] as? Data)?.count ?? 0
+                        log("frame \(n) pts=\(String(format: "%.3f", pts.seconds)) rpu=\(rpu)B compat=\(atts["DolbyCompatibilityID"] ?? "nil") keys=\(atts.keys.sorted())")
+                    }
+                    r.enqueue(enq)
+                    state.advance(lastPTS: pts)
+                }
+            }
+            let deadline = Date().addingTimeInterval(80)
+            while Date() < deadline {
+                try? await Task.sleep(nanoseconds: 500_000_000)
+                if state.done, CMTimebaseGetTime(tb) > state.lastPTS { break }
+                if dl.sampleBufferRenderer.status == .failed {
+                    log("renderer failed: \(String(describing: dl.sampleBufferRenderer.error))")
+                    break
+                }
+            }
+            log("vt \(mode): enqueued=\(state.count) copyFailures=\(state.failures) reader=\(reader.status.rawValue)")
+            renderer.stopRequestingMediaData()
+            reader.cancelReading()
+            renderer.flush(removingDisplayedImage: true, completionHandler: nil)
+            dl.removeFromSuperlayer()
+        } catch {
+            log("vt error: \(error)")
+        }
+    }
+
+    @MainActor
+    private func requestCriteria(fd: CMFormatDescription, fps: Float, log: @Sendable (String) -> Void) async {
+        window?.avDisplayManager.preferredDisplayCriteria = AVDisplayCriteria(refreshRate: fps, formatDescription: fd)
+        log("criteria requested codec=\(fourCC(CMFormatDescriptionGetMediaSubType(fd))) fps=\(fps)")
+        let switchDeadline = Date().addingTimeInterval(10)
+        try? await Task.sleep(nanoseconds: 300_000_000)
+        while window?.avDisplayManager.isDisplayModeSwitchInProgress == true, Date() < switchDeadline {
+            try? await Task.sleep(nanoseconds: 100_000_000)
+        }
+        try? await Task.sleep(nanoseconds: 1_000_000_000)
+        log("mode switch settled")
+    }
+
+    private func fourCC(_ v: FourCharCode) -> String {
+        String(bytes: [24, 16, 8, 0].map { UInt8((v >> $0) & 0xff) }, encoding: .ascii) ?? "\(v)"
+    }
+}
+
+
+/// Frame copy for the `vtcopy` / `vtstrip` arms, used on the feed queue.
+nonisolated private final class PulseFrameCopier: @unchecked Sendable {
+    private var pool: CVPixelBufferPool?
+    private var poolKey: (Int, Int, OSType)?
+
+    /// `vt`: unchanged. `vtcopy` / `vtstrip`: pixels copied into our own pool buffer, propagated
+    /// attachments copied across (minus the two Dolby Vision keys for `vtstrip`), new sample buffer
+    /// built from the image buffer the way AetherEngine's renderer builds its own.
+    func transform(_ sb: CMSampleBuffer, mode: String) -> CMSampleBuffer? {
+        if mode == "vt" { return sb }
+        guard let src = CMSampleBufferGetImageBuffer(sb), let dst = copyPixels(src) else { return nil }
+        var atts = CVBufferCopyAttachments(src, .shouldPropagate) as? [String: Any] ?? [:]
+        CVBufferRemoveAllAttachments(dst)
+        if mode == "vtstrip" {
+            atts["DolbyVisionRPUData"] = nil
+            atts["DolbyCompatibilityID"] = nil
+        }
+        CVBufferSetAttachments(dst, atts as CFDictionary, .shouldPropagate)
+        var fd: CMVideoFormatDescription?
+        guard CMVideoFormatDescriptionCreateForImageBuffer(allocator: nil, imageBuffer: dst, formatDescriptionOut: &fd) == noErr,
+              let fd else { return nil }
+        var timing = CMSampleTimingInfo()
+        CMSampleBufferGetSampleTimingInfo(sb, at: 0, timingInfoOut: &timing)
+        var out: CMSampleBuffer?
+        guard CMSampleBufferCreateReadyWithImageBuffer(allocator: nil, imageBuffer: dst, formatDescription: fd,
+                                                       sampleTiming: &timing, sampleBufferOut: &out) == noErr else { return nil }
+        return out
+    }
+
+    private func copyPixels(_ src: CVPixelBuffer) -> CVPixelBuffer? {
+        let w = CVPixelBufferGetWidth(src), h = CVPixelBufferGetHeight(src)
+        let fmt = CVPixelBufferGetPixelFormatType(src)
+        if pool == nil || poolKey.map({ $0 != (w, h, fmt) }) ?? true {
+            let attrs: [String: Any] = [
+                kCVPixelBufferWidthKey as String: w, kCVPixelBufferHeightKey as String: h,
+                kCVPixelBufferPixelFormatTypeKey as String: fmt,
+                kCVPixelBufferIOSurfacePropertiesKey as String: [String: Any](),
+                kCVPixelBufferMetalCompatibilityKey as String: true]
+            CVPixelBufferPoolCreate(nil, [kCVPixelBufferPoolMinimumBufferCountKey as String: 12] as CFDictionary,
+                                    attrs as CFDictionary, &pool)
+            poolKey = (w, h, fmt)
+        }
+        guard let pool else { return nil }
+        var dst: CVPixelBuffer?
+        guard CVPixelBufferPoolCreatePixelBuffer(nil, pool, &dst) == kCVReturnSuccess, let dst else { return nil }
+        CVPixelBufferLockBaseAddress(src, .readOnly)
+        CVPixelBufferLockBaseAddress(dst, [])
+        defer {
+            CVPixelBufferUnlockBaseAddress(dst, [])
+            CVPixelBufferUnlockBaseAddress(src, .readOnly)
+        }
+        for p in 0..<CVPixelBufferGetPlaneCount(src) {
+            guard let s = CVPixelBufferGetBaseAddressOfPlane(src, p),
+                  let d = CVPixelBufferGetBaseAddressOfPlane(dst, p) else { return nil }
+            let sr = CVPixelBufferGetBytesPerRowOfPlane(src, p), dr = CVPixelBufferGetBytesPerRowOfPlane(dst, p)
+            let rows = CVPixelBufferGetHeightOfPlane(src, p)
+            let n = min(sr, dr)
+            for r in 0..<rows { memcpy(d + r * dr, s + r * sr, n) }
+        }
+        return dst
+    }
+
+}
+
+nonisolated private final class FeedState: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _count = 0, _failures = 0, _done = false
+    private var _last = CMTime.zero
+    var count: Int { lock.withLock { _count } }
+    var failures: Int { lock.withLock { _failures } }
+    var done: Bool { lock.withLock { _done } }
+    var lastPTS: CMTime { lock.withLock { _last } }
+    func advance(lastPTS: CMTime) { lock.withLock { _count += 1; _last = lastPTS } }
+    func fail() { lock.withLock { _failures += 1 } }
+    func finish() { lock.withLock { _done = true } }
+}
diff --git a/Probes/DolbyVisionPulse/Device/project.yml b/Probes/DolbyVisionPulse/Device/project.yml
new file mode 100644
index 000000000..bd5197724
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/project.yml
@@ -0,0 +1,62 @@
+# Device harness for the Dolby Vision pulse test (Probes/DolbyVisionPulse/README.md): a tvOS app
+# that plays the clips from Scripts/build.sh, arm by arm, so a camera pointed at the television can
+# see whether the Dolby Vision metadata reaches the panel. It depends on the engine as a local Swift
+# package (the repository root, three levels up).
+#
+# Regenerate with `xcodegen generate --spec project.yml` from this directory. The generated project
+# is committed so that running the probe needs Xcode and nothing else.
+#
+# XcodeGen names the local-package folder reference after the checkout directory it ran in, which
+# would commit a developer's folder name. After regenerating, change that name in project.pbxproj
+# (the `PBXFileReference` with `path = ../../..`, and its group entry) back to `AetherEngine`.
+name: DolbyVisionPulse
+options:
+  bundleIdPrefix: de.superuser404.dolbyvisionpulse
+  createIntermediateGroups: true
+  deploymentTarget:
+    tvOS: "18.0"
+
+settings:
+  base:
+    SWIFT_VERSION: "6.0"
+    TARGETED_DEVICE_FAMILY: "3"
+    CODE_SIGN_STYLE: Automatic
+    # If a team cannot register this id, override it on the command line
+    # (PULSE_BUNDLE_PREFIX=com.example.pulse); the app's id is $(PULSE_BUNDLE_PREFIX).host.
+    PULSE_BUNDLE_PREFIX: de.superuser404.dolbyvisionpulse
+    ENABLE_USER_SCRIPT_SANDBOXING: YES
+
+packages:
+  AetherEngine:
+    path: ../../..
+
+targets:
+  DolbyVisionPulseHost:
+    type: application
+    platform: tvOS
+    sources:
+      - path: Host
+        excludes:
+          - Info.plist
+    dependencies:
+      - package: AetherEngine
+        product: AetherEngine
+    info:
+      path: Host/Info.plist
+      properties:
+        CFBundleDisplayName: Dolby Vision pulse
+        # The clips are served over plain http by Scripts/serve.py on the Mac next door.
+        NSAppTransportSecurity:
+          NSAllowsArbitraryLoads: true
+    settings:
+      base:
+        PRODUCT_BUNDLE_IDENTIFIER: $(PULSE_BUNDLE_PREFIX).host
+        GENERATE_INFOPLIST_FILE: NO
+
+schemes:
+  DolbyVisionPulse:
+    build:
+      targets:
+        DolbyVisionPulseHost: all
+    run:
+      config: Debug
diff --git a/Probes/DolbyVisionPulse/README.md b/Probes/DolbyVisionPulse/README.md
new file mode 100644
index 000000000..e839d7af9
--- /dev/null
+++ b/Probes/DolbyVisionPulse/README.md
@@ -0,0 +1,303 @@
+# Dolby Vision pulse test
+
+A measurement, not a test. It answers whether a television is *using* the Dolby Vision metadata a
+player hands it, as opposed to merely switching into a Dolby Vision mode and showing the base layer.
+The badge cannot tell those apart. A pulse can.
+
+The clips hold the pixels constant. After a 144 frame pre-roll, only the RPU switches between two
+states A and B every 72 frames (about three seconds, ten cycles, a 66 second clip). If the panel
+applies the metadata, the picture brightens and darkens in step with the switches, and a phone
+filming the screen sees it. If the RPU is ignored, the filmed picture is steady, apart from drift.
+Running the same clip through different players puts the engine's Profile 7 FEL route next to Apple's
+own and says whether the route is real Dolby Vision. The evidence this was built for is in
+[docs/dolby-vision-fel.md](../../docs/dolby-vision-fel.md).
+
+A variant, `p7fel_el.mp4`, keeps the RPU constant and switches only the enhancement-layer residual on
+six patches. It answers a different question: whether the composed FEL pixels, not just the metadata,
+reach the panel.
+
+Nothing here is a unit test and none of it runs in CI beyond compiling. It needs a television, an
+Apple TV and a phone on a tripod.
+
+## What is in here
+
+| path | what |
+| --- | --- |
+| `Scripts/gen_pulse.py` | the synthetic pattern, the RPU configs for every variant, the EL residual design |
+| `Scripts/build.sh` | builds the clips (x265, dovi_tool, MP4Box) into `out/` |
+| `Scripts/fel_count.py` | the counter clips: BL and EL each carry their own frame number; also reads them back from composed frames |
+| `Scripts/serve.py` | static server with HTTP Range support, which AVFoundation requires |
+| `Scripts/run_tv.sh` | builds and installs the host on an Apple TV, serves the clips, plays a sequence |
+| `Scripts/cut.py` | cuts one phone recording into one piece per arm from the app's wall-clock log |
+| `Scripts/analyze.py` | reads a phone recording back and prints a verdict per arm |
+| `Scripts/report.py` | turns the cut arms into the change-per-patch table, the phase-A levels and the all-arms figure |
+| `Scripts/check_el.py` | checks on the Mac that the EL clip carries the designed residual in B and none in A |
+| `Scripts/dump_attachments.swift` | prints what VideoToolbox attaches to a decoded Dolby Vision frame, with a hash of the RPU |
+| `Scripts/sim_recording.py` | a fake phone recording, to prove the analysis before trusting a real one |
+| `Device/` | the tvOS host app (xcodegen project, committed generated project) |
+
+## Tools
+
+`x265`, `dovi_tool`, `MP4Box` (gpac), `ffmpeg`/`ffprobe`, `curl`, Python 3 with `numpy`, and `Pillow`
+for the optional plots (`analyze.py --png`, `report.py --png`; `cut.py` writes its per-arm `.png` only
+when Pillow is installed). On macOS: `brew install x265 dovi_tool gpac ffmpeg`,
+`python3 -m pip install numpy pillow`. `xcodegen` only if the Xcode project is regenerated.
+
+Tested with ffmpeg 9.0.2, dovi_tool 2.3.4, x265 4.3, MP4Box (GPAC) 26.07, Python 3.14 with numpy 2.3
+and Pillow 12.1, and Xcode 27.0 (tvOS 27 SDK), on an LG C1 filmed with a phone.
+
+## Build the clips
+
+```bash
+Scripts/build.sh
+```
+
+Everything lands in `out/` (override with `PULSE_OUT`), which is gitignored; no media is committed.
+The 4K encode takes a few minutes and is skipped when `out/base.hevc` exists.
+
+| clip | profile | what switches |
+| --- | --- | --- |
+| `pulse_l2.mp4` | 8.1 | L2 trims at 100/600/1000/4000 nit targets, neutral and extreme |
+| `pulse_l1.mp4` | 8.1 | L1 `max_pq`, 100 nit and 10000 nit |
+| `pulse_null.mp4` | 8.1 | nothing: L1 constant, trims neutral, the same shot boundaries as `l2` |
+| `p7fel_{l2,l1,null}.mp4` | 7 FEL | the same three RPUs, enhancement layer flat (zero residual) |
+| `p7fel_el.mp4` | 7 FEL | the RPU never changes; a positive luma residual on six patches in phase B |
+| `p7fel_count_{null,l2}.mp4` | 7 FEL | counter clips: "BL nnnn" in the base layer, "EL nnnn" in the residual only; `l2` pulses the RPU as `pulse_l2` |
+| `count_mel.mp4` | 8.1 | the counter clip's base layer alone (no EL numbers), the MEL/AVPlayer control |
+
+The Profile 7 clips need a FEL RPU to start from. `build.sh` fetches dovi_tool's own 384 byte test
+RPU once and checks its hash:
+
+```
+https://raw.githubusercontent.com/quietvoid/dovi_tool/ef85991cfc31e26bc3ffed76364965f29f9fd281/assets/tests/fel_orig.bin
+```
+
+It is the same file Homebrew installs under `$(brew --prefix dovi_tool)/share/dovi_tool/assets/tests/`.
+The mapping and NLQ parameters stay as that file has them in every frame, so the composed picture is
+the same in every phase; only L1/L2/L5/L6 are replaced per frame.
+
+The pattern carries what the analysis reads: four corner squares that locate the screen in the camera
+image, an orientation tag, twelve grey patches from 0.1 to 10000 nit, eight colour patches, a PQ ramp,
+and a strip of sixteen cells that is the frame counter (the clip frame number in Gray code with two
+parity bits, so the analysis knows which phase is on screen). Frames whose counter does not decode
+(slates, black during the mode switch, motion blur) are dropped.
+
+## The arms
+
+One phone recording covers a whole sequence. The host plays the arms back to back with a five second
+slate on black naming the arm and a live UTC clock between them, then the switch into the video mode.
+Nothing is touched during the run.
+
+| arm | mode | clip | what it is | expected if the RPU is used |
+| --- | --- | --- | --- | --- |
+| P | `avplayer` | `pulse_l2` | AVPlayer, Apple's own path | pulses. **If not, stop: the TV or its settings cannot show the test** |
+| V1 | `vt` | `pulse_l2` | AVAssetReader (VideoToolbox) into an `AVSampleBufferDisplayLayer`, Apple's attachments | pulses if the display layer carries Dolby Vision at all |
+| V2 | `vtcopy` | `pulse_l2` | as V1, every frame copied into our own IOSurface pool, Apple's RPU bytes re-attached | pulses if buffer origin does not matter |
+| S | `vtstrip` | `pulse_l2` | as V2 with no Dolby attachments | steady; this is what HDR10-in-Dolby-Vision looks like |
+| T | `engine` | `p7fel_l2` | AetherEngine FEL route (`preferDualLayerDolbyVision: true`) | **the question** |
+| N | `engine` | `p7fel_null` | AetherEngine FEL route, metadata never changes | steady (camera and TV drift only) |
+| P1 | `avplayer` | `pulse_l1` | AVPlayer, `max_pq` switches | pulses (highlights) |
+| T1 | `engine` | `p7fel_l1` | AetherEngine FEL route | the same as P1 |
+| TE | `engine` | `p7fel_el` | FEL route, only the residual switches | pulses on the six patches only if the composed pixels reach the panel |
+| NE | `enginenofel` | `p7fel_el` | `preferDualLayerDolbyVision: false`: native 8.1 route, EL dropped | steady |
+| T (count) | `engine` | `p7fel_count_null` | FEL route on the counter clip, constant RPU | "BL nnnn" and "EL nnnn" show the same number |
+| NE (count) | `enginenofel` | `p7fel_count_null` | native 8.1 route, EL dropped | the EL panel stays empty |
+| TL | `engine` | `p7fel_count_l2` | FEL route, counter clip, the RPU pulses as in `pulse_l2` | the same numbers, and the picture pulses |
+| PM | `avplayer` | `count_mel` | AVPlayer on the base layer alone as 8.1 (what a MEL player shows) | no EL numbers |
+| SOAK | `soak` | any FEL clip | `engine` for `minutes=` with a `seeks=` schedule | not a pulse arm, see below |
+
+Sequences (`SEQ=` for `run_tv.sh`): `main` is P V1 V2 T N S P1 T1 P, about 11 minutes; the closing P
+repeats the first and checks drift over the session. `el` is TE NE T, about 4 minutes. `vt` is P V1
+V2 S. `count` is T NE TL PM on the counter clips, about 5 minutes. `soak` is one long arm.
+
+The counter clips are read by eye on the recording, not by `analyze.py`. Each layer carries its own frame
+number: the base layer draws "BL 0123" in its pixels, the enhancement layer draws "EL 0123" in its residual
+only, with a slower "S042" row (frame / 24) for when the fast digits blur on camera, and a Gray-code cell row
+per layer. Composed correctly, both sides show the same number. A route that drops the residual shows an
+empty EL panel; one that pairs the wrong EL picture shows a different number; TL shows that the RPU is
+applied on top of the composed residual. Both layers use one fixed GOP, so their picture order matches.
+tvOS AVPlayer does not play single-track Profile 7, so the AVPlayer control is the 8.1 base layer (PM).
+Off the TV, `Scripts/fel_count.py read <frames.yuv>` decodes both code rows from raw 3840x2160 yuv420p
+frames of any composer's output and prints `ok`, `MISMATCH` or `no-EL` per frame.
+
+The soak arm is not a pulse measurement. It plays a FEL title for several minutes through a seek
+schedule and reports one line, `soak summary: played= seeks= droppedFrames= composeFailures=
+peakFootprintMB= endFootprintMB= route=`. Check `route=` first: it reads `FEL` only if the engine's
+dual-layer summary lines were seen, and a run that never took the route reports zero compose failures
+for the wrong reason.
+
+## Run on an Apple TV
+
+The host app takes its arms from the environment variable `PULSE_ARMS`:
+
+```
+label|mode|url[|k=v;k=v],label|mode|url,...
+```
+
+Arms are comma separated; a soak's `seeks=at@to,at@to` list contains commas too, so a piece that does
+not look like `label|mode|...` continues the previous arm's parameters.
+`xcrun devicectl device process launch --environment-variables` does deliver environment to an app
+process. That is not true of an XCTest bundle on tvOS, which is why the transport probe cannot use it.
+
+```bash
+DEVICE="<devicectl name or id>" TEAM=<team id> Scripts/run_tv.sh
+```
+
+`xcrun devicectl list devices` names the devices. Options, all environment variables:
+
+| variable | default | what it is |
+| --- | --- | --- |
+| `DEVICE` | required | the Apple TV |
+| `TEAM` | none | development team id for signing |
+| `PULSE_BUNDLE_PREFIX` | `de.superuser404.dolbyvisionpulse` | the app's id is `<prefix>.host`; set it when a team cannot register the default |
+| `SEQ` | `main` | `main`, `el`, `vt`, `count` or `soak` |
+| `SOAK_URL`, `SOAK_MIN`, `SOAK_SEEKS` | none, 5, `60@1800,150@600,240@3000` | the soak arm: a URL or a file under `out/`, minutes, `at@to` seek schedule in seconds |
+| `PULSE_OUT` | `out/` | where the clips are |
+| `IFACE` | first of `en0`, `en1` with an address | the network interface whose address the Apple TV fetches the clips from |
+| `DEVELOPER_DIR` | `xcode-select -p` | the Xcode to build with |
+
+`run_tv.sh --no-build` plays without rebuilding. The script builds `Device/DolbyVisionPulse.xcodeproj`,
+installs it, serves `out/` from this Mac over plain http (`serve.py`; the host allows it), waits ten
+seconds so the recording can be started, launches with `--console`, and afterwards pulls the app's own
+log (`Library/Caches/pulse-log.txt`) off the device. A launch that ends non-zero, because the app
+crashed or was killed, still gets its log pulled. Pull a crash report from the device yourself when
+that happens.
+
+In Xcode: open `Device/DolbyVisionPulse.xcodeproj`, pick the Apple TV, set `PULSE_ARMS` in the scheme's
+environment variables and run. The host keeps the screen saver off, because an Apple TV that sleeps
+mid-sequence suspends the process.
+
+Apple TV settings: Format **4K SDR**, Match Content with **Dynamic Range** and **Frame Rate** on, and
+leave the HDMI chroma and range settings alone between runs.
+
+## Film it
+
+**Television.** Dolby Vision on an LG OLED (the C1 was used): picture mode **Dolby Vision Cinema**,
+not *Cinema Home*, which follows the room light. AI Picture Pro, AI Brightness, Energy Saving, OLED
+Motion Pro, TruMotion and OLED Care's Logo Luminance Adjustment all off; the last two matter because
+black frame insertion flickers on a phone and the logo dimming darkens static areas, which this
+pattern is. LG keeps separate Dolby Vision and HDR10 settings and the Dolby Vision ones can only be
+changed while Dolby Vision is playing, so set them during any Dolby Vision title. Dark room, ten minutes
+of warm-up. Note whether the Dolby Vision badge shows on each arm; it says only that the TV is in
+Dolby Vision mode, and the pulse is what says the RPU is used.
+
+**Phone.** 4K at 30 fps (1080p 30 works), **HDR Video off** so the recording is not itself tone
+mapped, Auto Low Light FPS off, Enhanced Stabilization off, Lock Camera on. On a tripod, with the
+whole screen and all four corner squares filling most of the frame and nothing else bright in view.
+Start recording before the launch; `run_tv.sh` waits ten seconds. Hands off until the sequence ends,
+then stop.
+
+**Exposure must be locked.** With auto exposure the camera compensates for the very brightness change
+being measured. The stock Camera app's AE/AF lock (long press) **did not hold** here: exposure moved
+on a locked frame. Use a manual camera app with a fixed ISO, a fixed shutter (1/30 or 1/60) and a
+fixed white balance (5600 K), set so the brightest patch (top row, right end) is not blown out.
+Blackmagic Camera is one. If the stock app is all there is, lock during the first arm's pre-roll and
+treat the first run as a shakedown; the closing P arm repeats it.
+
+## Cut and analyse
+
+`cut.py` splits one recording into one piece per arm using the `[Pulse] wall=...` lines in the console
+log (or the pulled app log), so the labels do not depend on counting runs in order.
+
+```bash
+python3 Scripts/cut.py recording.MOV tv_main_<stamp>.log --slates
+```
+
+The video's start comes from its QuickTime creation date, to a second. `--slates` writes one still per
+slate; read the UTC clock off one and pass it back for sub-second alignment:
+
+```bash
+python3 Scripts/cut.py recording.MOV tv_main_<stamp>.log --sync 12.5=17:08:31.2
+```
+
+That is "the slate frame at 12.5 s of the video shows 17:08:31.2". The result is a table of arm, mode
+and verdict, plus a `.mov` and `.json` per arm (and a `.png` when Pillow is installed) next to the recording.
+
+To analyse a recording directly, labelling runs in order:
+
+```bash
+python3 Scripts/analyze.py recording.MOV --arms P,V1,V2,T,N,S,P1,T1,P --png result.png
+```
+
+## Report
+
+`report.py` reads the arms directory `cut.py` wrote (`summary.json` and every `NN_<ARM>.json`) and prints
+markdown: the change in camera brightness, B against A, per grey patch as a signed percent (FEL-route
+rows in bold, a repeated arm labelled "(repeat)", an arm with no decoded run flagged), the number of
+patches with |t| above 5 and the strongest t per arm, and the absolute phase-A levels of the arms that
+show whether the panel was in Dolby Vision at all. `--png` draws every arm's trace in one figure.
+
+```bash
+python3 Scripts/report.py recording_arms --md report.md --png report.png
+python3 Scripts/report.py recording_arms --levels-arms V1,V2,T,S --patches g10,g100,g400,g1000,g4000,g10000
+```
+
+## Check the clips before filming
+
+A steady EL arm only means something if the clip carries the residual. `check_el.py` demuxes the BL and EL
+of the muxed `.mp4` (`dovi_tool demux`), or takes an EL-only `.hevc`, decodes the EL to raw
+`yuv420p10le` (no range conversion), and checks that the median EL code inside every `EL_PATCHES` box is
+512 in phase A and the `el_design()` code in phase B (within one code value). It prints the share of EL
+pixels away from 512 per phase (0 in A, about the patch area in B), the composed 10-bit change each patch
+should show, and for an `.mp4` that the RPU is the same on every frame. It exits 1 on a failure, so the
+flat-EL control clip fails phase B by design.
+
+```bash
+python3 Scripts/check_el.py out/p7fel_el.mp4
+```
+
+`dump_attachments.swift` decodes a Profile 8.1 clip through AVAssetReader, that is VideoToolbox's own
+decoder, prints every attachment on the chosen frames' pixel buffers, and hashes `DolbyVisionRPUData` on
+every frame. It shows the payload the platform attaches itself, to compare with what the engine attaches;
+on a pulse clip the hash differs between an A frame and a B frame.
+
+```bash
+swift Scripts/dump_attachments.swift out/pulse_l2.mp4 0 200
+```
+
+## Reading the verdicts
+
+For every patch and every B phase, the effect is `B - (A_before + A_after) / 2`, so slow drift cancels.
+Per arm the output is a verdict, the eight patches that moved most (level, B-A change, relative change,
+t statistic) and the lag in clip frames between the switch and the panel's response.
+
+- **PULSE**: at least three patches with |t| above 5. **weak**: one or two. **steady**: none.
+- **Real Dolby Vision**: T is about the same as P, and much larger than N.
+- **Fake Dolby Vision** (the mode switches, the metadata is ignored): T is about N while P pulses.
+- **V1 pulses, V2 does not**: tvOS cares where the buffer came from.
+- **V2 pulses, T does not**: the problem is in our RPU bytes or our path, not the platform.
+- **TE pulses on the six patches, NE steady**: the residual reaches the panel. The six are the 10, 100,
+  400 and 1000 nit greys, red and cyan (about +17 % in 10-bit luma code value after composition); the
+  other patches are in-frame controls and must not move.
+
+N and NE are the drift floor. A verdict only means something against them.
+
+## Proving the analysis first
+
+`sim_recording.py` writes a fake phone recording of `pulse_l2.mp4`: filmed at 30 fps with perspective,
+vignetting and noise, B phases darkened with a three frame latency for a `pulse` run, nothing for a
+`steady` one.
+
+```bash
+python3 Scripts/sim_recording.py sim.mp4 pulse,steady        # about two minutes
+python3 Scripts/analyze.py sim.mp4 --arms pulse,steady        # PULSE (28 patches), steady (0 patches)
+```
+
+`cut.py` can be exercised the same way with a hand-written log of `[Pulse] wall=<epoch> t=<s> slate
+<label>`, `arm <label> start mode=<mode> url=<clip>` and `arm <label> end` lines and `--sync`.
+
+## Caveats
+
+- **The camera reports its own values, not nits.** The numbers are camera luma after its tone curve
+  and exposure. They say whether a patch changed and by how much relative to itself, not by how many
+  nits. Compare arms with each other, not with the clip's nominal levels.
+- **A panel's own processing can mask or invent a pulse.** Dynamic tone mapping and ABL react to the
+  frame's content, and the content here is constant, which is the point; the null arms measure what
+  is left.
+- **The pulse proves the metadata is consumed, not that it is applied correctly.** Whether the
+  display-mapping result is right needs a colorimeter.
+- **The EL arms' size depends on the composer.** The residual design assumes an identity-scaled
+  BL-to-VDR luma map; `gen_pulse.py el-design` states the assumption and the verification is the
+  measured size of the TE pulse.
+- **Expect to run the whole sequence more than once.** A run where P does not pulse says nothing about
+  the other arms.
diff --git a/Probes/DolbyVisionPulse/Scripts/analyze.py b/Probes/DolbyVisionPulse/Scripts/analyze.py
new file mode 100755
index 000000000..fa86eaf8f
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/analyze.py
@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+"""Analyse a phone recording of the pulse clips (see gen_pulse.py and the README).
+
+For every camera frame: find the four corner fiducials, map the clip layout onto the camera image,
+read the frame-counter strip (which clip frame is on screen, so which RPU phase), and sample every
+patch. Frames whose counter does not decode (slates, mode-switch black, motion) are dropped.
+
+A run is a stretch where the decoded clip frame keeps increasing; it restarts when the counter jumps
+back. Label runs in order with --arms (e.g. --arms P,V1,V2,T,N,S,P).
+
+Per run and patch the metadata effect is d_k = B_k - (A_before + A_after)/2 over the k-th B phase
+(so slow drift cancels), reported as mean relative change, t statistic, and the frame lag at which
+the response crosses half its size after a switch.
+
+Usage: analyze.py recording.mov [--arms P,T,...] [--csv out.csv] [--png out.png] [--scale 1280]
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+import numpy as np
+
+import gen_pulse as G
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SETTLE = 12  # clip frames ignored after each phase switch (~0.5 s)
+
+
+def probe(path):
+    out = subprocess.check_output(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                                   "stream=width,height,r_frame_rate:stream_side_data=rotation",
+                                   "-of", "json", path])
+    s = json.loads(out)["streams"][0]
+    num, den = (int(x) for x in s["r_frame_rate"].split("/"))
+    return s["width"], s["height"], num / den
+
+
+def frames(path, scale):
+    """Yield luma frames as float32 [0,1], scaled to `scale` px wide (ffmpeg applies rotation)."""
+    w, h, fps = probe(path)
+    cmd = ["ffmpeg", "-v", "error", "-i", path, "-vf", f"scale={scale}:-2", "-pix_fmt", "gray16le",
+           "-f", "rawvideo", "-"]
+    # Output size: decode one frame to PGM and read its header (ffmpeg applies display rotation).
+    pgm = subprocess.check_output(["ffmpeg", "-v", "error", "-i", path, "-vf", f"scale={scale}:-2",
+                                   "-frames:v", "1", "-pix_fmt", "gray", "-f", "image2pipe", "-c:v", "pgm", "-"])
+    ow, oh = (int(x) for x in pgm.split(b"\n")[1].split())
+    p = subprocess.Popen(cmd, stdout=subprocess.PIPE)
+    n = ow * oh * 2
+    t = 0
+    while True:
+        buf = p.stdout.read(n)
+        if len(buf) < n:
+            break
+        yield t, np.frombuffer(buf, dtype="<u2").reshape(oh, ow).astype(np.float32) / 65535.0
+        t += 1
+    p.wait()
+
+
+def find_corners(Y):
+    """Outer corners of the four fiducials: extreme bright pixels along the diagonals.
+
+    On a real phone image the TV sits on a bright wall, so the search is restricted to the dark
+    screen region (found from row/column projections of dark pixels)."""
+    oh, ow = Y.shape
+    x_lo, x_hi, y_lo, y_hi = 0, ow, 0, oh
+    dark = Y < 0.3
+    xs_d = np.nonzero(dark.mean(0) > 0.4)[0]
+    ys_d = np.nonzero(dark.mean(1) > 0.4)[0]
+    if len(xs_d) and len(ys_d):
+        x_lo, x_hi, y_lo, y_hi = xs_d.min(), xs_d.max() + 1, ys_d.min(), ys_d.max() + 1
+        # bright wall/bezel pokes into the bbox at curved screen corners; fiducials never touch its edge
+        m = int(0.013 * (x_hi - x_lo))
+        if x_hi - x_lo < ow or y_hi - y_lo < oh:
+            x_lo, x_hi, y_lo, y_hi = x_lo + m, x_hi - m, y_lo + m, y_hi - m
+    Z = Y[y_lo:y_hi, x_lo:x_hi]
+    lo, hi = np.percentile(Z, 5), np.percentile(Z, 99.5)  # percentile, not max: glare/reflections
+    if hi - lo < 0.08:
+        return None
+    M = Z > lo + 0.35 * (hi - lo)
+    # keep only pixels inside a solid 7x7 bright block (fiducials are big squares; specks and thin
+    # reflection streaks are not)
+    c = np.pad(M.astype(np.int32).cumsum(0).cumsum(1), ((1, 0), (1, 0)))
+    k = 7
+    solid = (c[k:, k:] - c[:-k, k:] - c[k:, :-k] + c[:-k, :-k]) == k * k
+    M = np.zeros_like(M)
+    M[k // 2:k // 2 + solid.shape[0], k // 2:k // 2 + solid.shape[1]] = solid
+    ys, xs = np.nonzero(M)
+    if len(xs) < 200:
+        return None
+    xs, ys = xs + x_lo, ys + y_lo
+    s, d = xs + ys, xs - ys
+    tl = (xs[s.argmin()], ys[s.argmin()])
+    br = (xs[s.argmax()], ys[s.argmax()])
+    tr = (xs[d.argmax()], ys[d.argmax()])
+    bl = (xs[d.argmin()], ys[d.argmin()])
+    o = k // 2  # the solid-block test insets each corner pixel by k//2
+    return np.array([tl, tr, bl, br], dtype=np.float64) + np.array([[-o, -o], [o, -o], [-o, o], [o, o]])
+
+
+def homography(src, dst):
+    A = []
+    for (x, y), (u, v) in zip(src, dst):
+        A.append([x, y, 1, 0, 0, 0, -u * x, -u * y, -u])
+        A.append([0, 0, 0, x, y, 1, -v * x, -v * y, -v])
+    _, _, vt = np.linalg.svd(np.array(A))
+    Hm = vt[-1].reshape(3, 3)
+    return Hm / Hm[2, 2]
+
+
+def sampler(L, Hm, Y_shape, inset=0.2, n=7):
+    """Precompute camera pixel coordinates for an n x n grid inside every box (inset fraction trimmed)."""
+    oh, ow = Y_shape
+
+    def grid(box):
+        x0, y0, x1, y1 = box
+        dx, dy = (x1 - x0) * inset, (y1 - y0) * inset
+        gx, gy = np.meshgrid(np.linspace(x0 + dx, x1 - dx, n), np.linspace(y0 + dy, y1 - dy, n))
+        P = np.stack([gx.ravel(), gy.ravel(), np.ones(gx.size)])
+        Q = Hm @ P
+        u = np.clip(np.round(Q[0] / Q[2]).astype(int), 0, ow - 1)
+        v = np.clip(np.round(Q[1] / Q[2]).astype(int), 0, oh - 1)
+        return v, u
+
+    names = [p["name"] for p in L["patches"]]
+    boxes = [p["box"] for p in L["patches"]]
+    # Ramp: 8 equal slices.
+    x0, y0, x1, y1 = L["ramp"]["box"]
+    for k in range(8):
+        a = x0 + (x1 - x0) * k // 8
+        b = x0 + (x1 - x0) * (k + 1) // 8
+        names.append(f"ramp{k}")
+        boxes.append([a, y0, b, y1])
+    names.append("black")
+    boxes.append([1700, 1950, 2140, 2100])  # surround below the code strip
+    names.append("fid")
+    boxes.append(L["fiducials"][0])
+    return names, [grid(b) for b in boxes], [grid(c) for c in L["code_cells"]]
+
+
+def analyse(path, arms, scale):
+    L = G.layout()
+    W, H = L["width"], L["height"]
+    m, s = 80, 200
+    src_corners = np.array([[m, m], [W - m, m], [m, H - m], [W - m, H - m]], dtype=np.float64)
+    _, _, cam_fps = probe(path)
+
+    rows = []  # (cam_frame, clip_frame, values...)
+    names = None
+    cache = None  # (corners, names, patch grids, cell grids)
+    bad = 0
+    def decode(Y, c):
+        nonlocal cache
+        if cache is None or np.abs(cache[0] - c).max() > 3:
+            names, pg, cg = sampler(L, homography(src_corners, c), Y.shape)
+            cache = (c, names, pg, cg)
+        _, names, pg, cg = cache
+        vals = np.array([Y[v, u].mean() for v, u in pg])
+        black, fid = vals[-2], vals[-1]
+        if fid - black < 0.05:
+            return None
+        cells = [Y[v, u].mean() for v, u in cg]
+        # cells 0 and 15 are always lit: use them as the 'on' reference (the fiducial's level can differ
+        # from the strip's when the RPU darkens the picture unevenly)
+        thr = black + 0.5 * (min(cells[0], cells[-1]) - black)
+        idx = G.decode_bits([int(x > thr) for x in cells])
+        if idx is None or idx >= L["n_frames"]:
+            return None
+        return idx, vals
+
+    good = None  # corners of the last frame that decoded: the phone is on a tripod, so they stay valid
+    for t, Y in frames(path, scale):
+        out = None
+        c = find_corners(Y)
+        if c is not None:
+            out = decode(Y, c)
+        if out is not None:
+            good = c
+        elif good is not None:
+            # dim frames (the RPU can darken the whole picture) can fool the fiducial search
+            out = decode(Y, good)
+        if out is None:
+            bad += 1
+            continue
+        rows.append((t, out[0], out[1]))
+    names = cache[1] if cache else None
+    if not rows:
+        sys.exit(f"no decodable frames ({bad} rejected): check framing, exposure, fiducials in view")
+
+    # The 2 parity bits let some misreads through (more often in the dim phases). A real counter
+    # advances 23.976 clip frames per second, so drop decodes that disagree with the median of what
+    # their neighbours (+-2 s, at least 4 of them) predict for this instant.
+    T = np.array([r[0] for r in rows], dtype=np.float64)
+    I = np.array([r[1] for r in rows], dtype=np.float64)
+    rate = 24000 / 1001 / cam_fps
+    ok = np.zeros(len(rows), dtype=bool)
+    for i in range(len(rows)):
+        lo, hi = np.searchsorted(T, [T[i] - 2 * cam_fps, T[i] + 2 * cam_fps])
+        sel = np.arange(lo, hi) != i
+        pred = (I[lo:hi] + rate * (T[i] - T[lo:hi]))[sel]
+        ok[i] = len(pred) >= 4 and abs(I[i] - np.median(pred)) <= 6
+    print(f"  counter consistency filter dropped {int((~ok).sum())} of {len(rows)} decodes")
+    bad += int((~ok).sum())
+    rows = [r for r, k in zip(rows, ok) if k]
+
+    # Split into runs where the clip frame index restarts.
+    runs, cur = [], [rows[0]]
+    for r in rows[1:]:
+        if r[1] + 48 < cur[-1][1]:
+            runs.append(cur)
+            cur = [r]
+        else:
+            cur.append(r)
+    runs.append(cur)
+    for r in runs:
+        print(f"  segment {r[0][0] / cam_fps:6.1f}-{r[-1][0] / cam_fps:6.1f} s: {len(r):5d} decoded frames, "
+              f"clip frames {r[0][1]}..{r[-1][1]}" + ("" if len(r) > 10 * cam_fps else "  (too short, dropped)"))
+    runs = [r for r in runs if len(r) > 10 * cam_fps]
+    labels = (arms or [])
+    print(f"{path}: camera {cam_fps:.2f} fps, {len(rows)} decoded frames, {bad} rejected, {len(runs)} runs")
+    if labels and len(labels) != len(runs):
+        print(f"  warning: {len(labels)} arm labels for {len(runs)} runs; labels applied in order")
+
+    results = []
+    for k, run in enumerate(runs):
+        label = labels[k] if k < len(labels) else f"run{k + 1}"
+        idx = np.array([r[1] for r in run])
+        V = np.array([r[2] for r in run])
+        V = V[:, :-2]  # drop black, fid
+        pnames = names[:-2]
+        phase_no = np.where(idx < G.PREROLL, -1, (idx - G.PREROLL) // G.PHASE_LEN)
+        pos = np.where(idx < G.PREROLL, idx, (idx - G.PREROLL) % G.PHASE_LEN)
+        keep = (pos >= SETTLE) & (phase_no >= -1)
+        means = {}
+        for ph in np.unique(phase_no[keep]):
+            sel = keep & (phase_no == ph)
+            if sel.sum() >= 5:
+                means[int(ph)] = V[sel].mean(axis=0)
+        # B phases are even phase numbers; A neighbours are odd (or the pre-roll, -1).
+        d = []
+        for ph in sorted(means):
+            if ph >= 0 and ph % 2 == 0 and (ph - 1) in means and (ph + 1) in means:
+                d.append(means[ph] - 0.5 * (means[ph - 1] + means[ph + 1]))
+        d = np.array(d)
+        base = np.mean([v for p, v in means.items() if p == -1 or p % 2 == 1], axis=0)
+        if len(d) < 2:
+            print(f"  {label}: only {len(d)} complete B phases, skipped")
+            continue
+        mean_d = d.mean(axis=0)
+        sd = d.std(axis=0, ddof=1)
+        tstat = mean_d / np.maximum(sd / np.sqrt(len(d)), 1e-6)
+        rel = mean_d / np.maximum(base, 1e-3)
+        # Response lag: average trace around A->B switches of the most responsive patch.
+        j = int(np.argmax(np.abs(tstat)))
+        lag = step_lag(idx, V[:, j], phase_no, pos)
+        span = (run[0][0] / cam_fps, run[-1][0] / cam_fps)
+        n_sig = int((np.abs(tstat) > 5).sum())
+        verdict = "PULSE" if n_sig >= 3 else ("weak" if n_sig >= 1 else "steady")
+        print(f"\n  [{label}] camera {span[0]:.1f}-{span[1]:.1f} s, clip frames {idx.min()}-{idx.max()}, "
+              f"{len(d)} B phases -> {verdict} ({n_sig} patches |t|>5), lag {lag}")
+        order = np.argsort(-np.abs(tstat))
+        for i in order[:8]:
+            print(f"    {pnames[i]:>8}: level {base[i]:.3f}  B-A {mean_d[i]:+.4f} ({100 * rel[i]:+.1f}%)  t={tstat[i]:+.1f}")
+        results.append({"arm": label, "span_s": span, "b_phases": len(d), "verdict": verdict,
+                        "n_sig": n_sig, "lag_clip_frames": lag,
+                        "patches": {pnames[i]: {"level": float(base[i]), "delta": float(mean_d[i]),
+                                                "rel": float(rel[i]), "t": float(tstat[i])}
+                                    for i in range(len(pnames))},
+                        "trace": {"clip_frame": idx.tolist(), "values": V.tolist(), "names": pnames}})
+    return results
+
+
+def step_lag(idx, v, phase_no, pos):
+    """Clip frames after an A->B switch until the averaged response passes half its size."""
+    win = range(-12, 36)
+    acc = {o: [] for o in win}
+    for ph in set(phase_no[phase_no >= 0].tolist()):
+        if ph % 2:
+            continue
+        start = G.PREROLL + ph * G.PHASE_LEN
+        for o in win:
+            sel = idx == start + o
+            if sel.any():
+                acc[o].append(v[sel].mean())
+    tr = np.array([np.mean(acc[o]) if acc[o] else np.nan for o in win])
+    pre = np.nanmean(tr[:12])
+    post = np.nanmean(tr[-12:])
+    if not np.isfinite(pre) or not np.isfinite(post) or abs(post - pre) < 1e-3:
+        return None
+    half = pre + 0.5 * (post - pre)
+    for o, x in zip(win, tr):
+        if o >= 0 and np.isfinite(x) and (x - half) * np.sign(post - pre) >= 0:
+            return o
+    return None
+
+
+def png(results, out):
+    from PIL import Image, ImageDraw
+    rows = len(results)
+    Wd, Hd = 1600, 260
+    img = Image.new("RGB", (Wd, Hd * rows), "white")
+    dr = ImageDraw.Draw(img)
+    for r, res in enumerate(results):
+        tr = res["trace"]
+        idx = np.array(tr["clip_frame"])
+        V = np.array(tr["values"])
+        best = sorted(res["patches"], key=lambda n: -abs(res["patches"][n]["t"]))[:3]
+        y0 = r * Hd
+        dr.text((10, y0 + 5), f"{res['arm']}: {res['verdict']} ({res['n_sig']} patches |t|>5)", fill="black")
+        for f in range(G.PREROLL, G.N_FRAMES, G.PHASE_LEN):
+            if G.phase_of(f) == "B":
+                x = 10 + (f / G.N_FRAMES) * (Wd - 20)
+                x2 = 10 + ((f + G.PHASE_LEN) / G.N_FRAMES) * (Wd - 20)
+                dr.rectangle([x, y0 + 25, x2, y0 + Hd - 10], fill=(235, 235, 250))
+        for c, name in zip([(200, 0, 0), (0, 120, 0), (0, 0, 200)], best):
+            j = tr["names"].index(name)
+            v = V[:, j]
+            lo, hi = v.min(), v.max()
+            pts = [(10 + (i / G.N_FRAMES) * (Wd - 20),
+                    y0 + Hd - 15 - (x - lo) / max(hi - lo, 1e-6) * (Hd - 50)) for i, x in zip(idx, v)]
+            dr.line(pts, fill=c, width=1)
+            dr.text((Wd - 300, y0 + 5 + 14 * best.index(name)), f"{name} t={res['patches'][name]['t']:+.1f}", fill=c)
+    img.save(out)
+
+
+if __name__ == "__main__":
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("recording")
+    ap.add_argument("--arms", help="comma-separated labels for the runs, in order")
+    ap.add_argument("--scale", type=int, default=1280, help="analysis width in px")
+    ap.add_argument("--json", help="write full results (with traces) here")
+    ap.add_argument("--png", help="write a trace plot here")
+    a = ap.parse_args()
+    res = analyse(a.recording, a.arms.split(",") if a.arms else None, a.scale)
+    if a.json:
+        json.dump(res, open(a.json, "w"))
+    if a.png and res:
+        png(res, a.png)
diff --git a/Probes/DolbyVisionPulse/Scripts/build.sh b/Probes/DolbyVisionPulse/Scripts/build.sh
new file mode 100755
index 000000000..de327a1fc
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/build.sh
@@ -0,0 +1,135 @@
+#!/bin/zsh
+# Builds the pulse clips into $PULSE_OUT (default ../out, gitignored): one HEVC encode of the synthetic
+# pattern, then one MP4 per RPU variant. Needs x265, dovi_tool, MP4Box (gpac), curl, python3 + numpy (the analysis scripts also need ffmpeg).
+# The 4K encode takes a few minutes; every intermediate is kept and reused, delete it to rebuild it.
+#
+#   pulse_{l2,l1,null}.mp4   Profile 8.1, the RPU switches (l2: trims, l1: max_pq, null: never)
+#   p7fel_{l2,l1,null}.mp4   Profile 7 FEL, same RPUs; the enhancement layer is flat (zero residual)
+#   p7fel_el.mp4             Profile 7 FEL, constant RPU; the enhancement-layer residual switches
+#   p7fel_count_{null,l2}.mp4  Profile 7 FEL counter clips (fel_count.py): BL and EL each carry their own frame
+#                            number, the EL one as residual only; null: constant RPU, l2: the RPU pulses as in pulse_l2
+#   count_mel.mp4            control: the counter clip's base layer alone as Profile 8.1 (no EL numbers)
+set -euo pipefail
+HERE=${0:A:h}
+OUT=${PULSE_OUT:-$HERE/../out}
+mkdir -p "$OUT"
+OUT=${OUT:A}
+cd "$OUT"
+GEN=$HERE/gen_pulse.py
+
+for tool in x265 dovi_tool MP4Box python3 curl; do
+  command -v $tool >/dev/null || { echo "missing tool: $tool (brew install x265 dovi_tool gpac)"; exit 1; }
+done
+python3 -c 'import numpy' 2>/dev/null || { echo "missing python module: numpy (python3 -m pip install numpy)"; exit 1; }
+
+for v in l2 l1 null; do
+  python3 "$GEN" rpu-json $v > rpu_$v.json
+  dovi_tool generate -j rpu_$v.json -o rpu_$v.bin
+done
+
+if [[ ! -s base.hevc ]]; then
+  python3 "$GEN" frames | x265 --input - --input-res 3840x2160 --fps 24000/1001 \
+    --input-depth 10 --input-csp i420 --output-depth 10 --profile main10 \
+    --preset fast --crf 14 --keyint 48 --min-keyint 48 --no-scenecut --no-open-gop \
+    --colorprim bt2020 --transfer smpte2084 --colormatrix bt2020nc --range limited \
+    --master-display "G(8500,39850)B(6550,2300)R(35400,14600)WP(15635,16450)L(100000000,50)" \
+    --max-cll "10000,400" --hdr10 --hdr10-opt --repeat-headers --aud \
+    --vbv-bufsize 100000 --vbv-maxrate 100000 \
+    --frames 1584 -o base.hevc.tmp
+  mv base.hevc.tmp base.hevc
+fi
+
+for v in l2 l1 null; do
+  dovi_tool inject-rpu -i base.hevc --rpu-in rpu_$v.bin -o pulse_$v.hevc
+  rm -f pulse_$v.mp4
+  MP4Box -add pulse_$v.hevc:fps=24000/1001:dvp=f8.1 -brand mp42isom -ab dby1 -quiet -new pulse_$v.mp4
+  rm pulse_$v.hevc
+done
+
+# ---- Profile 7 FEL variants, for the engine's FEL route (arms T, N, T1) ----
+# RPU: dovi_tool's own FEL test RPU, duplicated to every frame, with L1/L2/L5/L6 replaced per frame
+# from the generated 8.1 RPUs. The mapping and NLQ stay constant, so the composed pixels are identical
+# in every frame and phase. EL: flat 512 (= nlq_offset), i.e. zero residual.
+#
+# The template is a 384-byte file in dovi_tool's repository, fetched once from a pinned commit and
+# checked by hash:
+#   https://github.com/quietvoid/dovi_tool/blob/$FEL_COMMIT/assets/tests/fel_orig.bin
+# (Homebrew also ships it under $(brew --prefix dovi_tool)/share/dovi_tool/assets/tests/.)
+FEL_COMMIT=ef85991cfc31e26bc3ffed76364965f29f9fd281
+FEL_SHA=b2b27714b7279c4e24d1a795cb6f95d3ad06745db96d360698ee0932184117a0
+if [[ ! -s fel_template.bin ]]; then
+  curl -fsSL -o fel_template.bin https://raw.githubusercontent.com/quietvoid/dovi_tool/$FEL_COMMIT/assets/tests/fel_orig.bin
+fi
+[[ "$(shasum -a 256 fel_template.bin | cut -d' ' -f1)" == "$FEL_SHA" ]] || {
+  echo "fel_template.bin does not match the expected fel_orig.bin (sha256 $FEL_SHA); delete it and retry"; exit 1; }
+
+if [[ ! -s el.hevc ]]; then
+  python3 -c "
+import sys
+y = bytes([0x00, 0x02]) * (1920 * 1080)
+c = bytes([0x00, 0x02]) * (960 * 540)
+f = y + c + c
+for _ in range(1584): sys.stdout.buffer.write(f)
+" | x265 --input - --input-res 1920x1080 --fps 24000/1001 --input-depth 10 --input-csp i420 \
+    --output-depth 10 --profile main10 --preset fast --crf 20 --keyint 48 --min-keyint 48 \
+    --no-scenecut --no-open-gop --repeat-headers --aud --frames 1584 -o el.hevc.tmp
+  mv el.hevc.tmp el.hevc
+fi
+print '{"duplicate":[{"source":0,"offset":1,"length":1583}]}' > fel_dup.json
+dovi_tool editor -i fel_template.bin -j fel_dup.json -o fel_1584.bin
+for v in l2 null l1; do
+  print "{\"source_rpu\":\"rpu_$v.bin\",\"rpu_levels\":[1,2,5,6]}" > fel_levels_$v.json
+  dovi_tool editor -i fel_1584.bin -j fel_levels_$v.json -o fel_rpu_$v.bin
+  dovi_tool inject-rpu -i el.hevc --rpu-in fel_rpu_$v.bin -o el_$v.hevc
+  dovi_tool mux --bl base.hevc --el el_$v.hevc -o p7_$v.hevc
+  rm -f p7fel_$v.mp4
+  MP4Box -add p7_$v.hevc:fps=24000/1001:dvp=f7.6 -brand mp42isom -ab dby1 -quiet -new p7fel_$v.mp4
+  rm el_$v.hevc p7_$v.hevc
+done
+
+# ---- p7fel_el: constant RPU (the `null` one), the EL residual switches (arms TE, NE) ----
+# EL: flat 512 in phase A; in phase B a positive luma residual on a set of patches (gen_pulse.py
+# el-design), flat 512 elsewhere. Same 1920x1080 / x265 settings as el.hevc.
+if [[ ! -s el_resid.hevc ]]; then
+  python3 "$GEN" el-frames | x265 --input - --input-res 1920x1080 --fps 24000/1001 --input-depth 10 \
+    --input-csp i420 --output-depth 10 --profile main10 --preset fast --crf 20 --keyint 48 --min-keyint 48 \
+    --no-scenecut --no-open-gop --repeat-headers --aud --frames 1584 -o el_resid.hevc.tmp
+  mv el_resid.hevc.tmp el_resid.hevc
+fi
+dovi_tool inject-rpu -i el_resid.hevc --rpu-in fel_rpu_null.bin -o el_el.hevc
+dovi_tool mux --bl base.hevc --el el_el.hevc -o p7_el.hevc
+rm -f p7fel_el.mp4
+MP4Box -add p7_el.hevc:fps=24000/1001:dvp=f7.6 -brand mp42isom -ab dby1 -quiet -new p7fel_el.mp4
+rm el_el.hevc p7_el.hevc
+
+# ---- Counter clips (arms T, NE, TL, PM of SEQ=count) ----
+# Same RPUs as p7fel_null / p7fel_l2. Both layers get the same fixed GOP (no adaptive B-frame placement,
+# 3 B-frames, pyramid), so BL and EL picture order match and a composer that pairs the wrong EL picture
+# shows a different EL number. Two more encodes (4K BL, 1080p EL), a few minutes each.
+COUNT=$HERE/fel_count.py
+GOP=(--preset fast --keyint 48 --min-keyint 48 --no-scenecut --no-open-gop --bframes 3 --b-adapt 0 --b-pyramid
+     --repeat-headers --aud --fps 24000/1001 --input-depth 10 --input-csp i420 --output-depth 10 --profile main10
+     --frames 1584)
+if [[ ! -s count_bl.hevc ]]; then
+  python3 "$COUNT" frames | x265 --input - --input-res 3840x2160 "${GOP[@]}" --crf 14 \
+    --colorprim bt2020 --transfer smpte2084 --colormatrix bt2020nc --range limited \
+    --master-display "G(8500,39850)B(6550,2300)R(35400,14600)WP(15635,16450)L(100000000,50)" \
+    --max-cll "10000,400" --hdr10 --hdr10-opt --vbv-bufsize 100000 --vbv-maxrate 100000 -o count_bl.hevc.tmp
+  mv count_bl.hevc.tmp count_bl.hevc
+fi
+if [[ ! -s count_el.hevc ]]; then
+  python3 "$COUNT" el-frames | x265 --input - --input-res 1920x1080 "${GOP[@]}" --crf 12 -o count_el.hevc.tmp
+  mv count_el.hevc.tmp count_el.hevc
+fi
+for v in null l2; do
+  dovi_tool inject-rpu -i count_el.hevc --rpu-in fel_rpu_$v.bin -o count_el_$v.hevc
+  dovi_tool mux --bl count_bl.hevc --el count_el_$v.hevc -o count_p7_$v.hevc
+  rm -f p7fel_count_$v.mp4
+  MP4Box -add count_p7_$v.hevc:fps=24000/1001:dvp=f7.6 -brand mp42isom -ab dby1 -quiet -new p7fel_count_$v.mp4
+  rm count_el_$v.hevc count_p7_$v.hevc
+done
+dovi_tool inject-rpu -i count_bl.hevc --rpu-in rpu_null.bin -o count_mel.hevc
+rm -f count_mel.mp4
+MP4Box -add count_mel.hevc:fps=24000/1001:dvp=f8.1 -brand mp42isom -ab dby1 -quiet -new count_mel.mp4
+rm count_mel.hevc
+ls -la "$OUT"/*.mp4
diff --git a/Probes/DolbyVisionPulse/Scripts/check_el.py b/Probes/DolbyVisionPulse/Scripts/check_el.py
new file mode 100755
index 000000000..56c5b9037
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/check_el.py
@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Verify the enhancement layer (EL) of a Dolby Vision "pulse test" Profile 7 FEL clip.
+
+CLIP is either the muxed .mp4 (HEVC track = BL + EL + RPU) or an EL-only .hevc elementary stream.
+For .mp4 the track is copied to Annex-B (ffmpeg), split with `dovi_tool demux` and the EL is used.
+The EL is decoded with ffmpeg to raw yuv420p10le (no range conversion) and, per checked frame:
+  * phase A (gen_pulse.phase_of): the median luma code in the inset (20%) of every EL patch box must
+    be 512 (+-1); the fraction of EL luma pixels != 512 must be 0.
+  * phase B: every patch median must equal its el_design() code (+-1); the non-512 pixel fraction
+    is printed and compared with the patch area fraction.
+The expected composed 10-bit luma delta (delta10, delta_pct) per patch is printed alongside.
+For .mp4 the RPU payloads (dovi_tool extract-rpu) are also hashed to confirm they are constant.
+
+Usage: check_el.py CLIP [--frames N] [--json OUT]
+  --frames N  check at most N frames per phase segment (evenly spread, default: all frames)
+Exit status 0 = PASS, 1 = FAIL, 2 = tool/usage error.
+"""
+import argparse
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+
+import numpy as np
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+import gen_pulse as G  # noqa: E402
+
+TOL = 1
+INSET = 0.20
+
+
+def die(msg):
+    print("error: " + msg, file=sys.stderr)
+    sys.exit(2)
+
+
+def run(cmd, **kw):
+    try:
+        r = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kw)
+    except FileNotFoundError:
+        die(f"{cmd[0]} not found in PATH")
+    if r.returncode != 0:
+        die(f"{' '.join(cmd[:3])}... failed (rc {r.returncode}): {r.stderr.decode(errors='replace')[-400:]}")
+    return r
+
+
+def rpu_payloads(path):
+    """Split a dovi_tool RPU.bin (start-code separated) into payloads."""
+    data = open(path, "rb").read()
+    parts = data.split(b"\x00\x00\x00\x01")
+    return [p for p in parts if p]
+
+
+def prepare_el(clip, tmp):
+    """Return (el_hevc_path, rpu_info dict or None)."""
+    if not os.path.isfile(clip):
+        die(f"no such file: {clip}")
+    if not clip.lower().endswith(".mp4"):
+        return clip, None
+    annexb = os.path.join(tmp, "stream.hevc")
+    run(["ffmpeg", "-v", "error", "-y", "-i", clip, "-map", "0:v:0", "-c:v", "copy",
+         "-bsf:v", "hevc_mp4toannexb", "-f", "hevc", annexb])
+    run(["dovi_tool", "demux", "-i", annexb, "--bl-out", os.path.join(tmp, "BL.hevc"),
+         "--el-out", os.path.join(tmp, "EL.hevc")], cwd=tmp)
+    el = os.path.join(tmp, "EL.hevc")
+    if not os.path.isfile(el) or os.path.getsize(el) == 0:
+        die("dovi_tool demux produced no EL (is this a dual-layer Profile 7 clip?)")
+    rpu = None
+    rb = os.path.join(tmp, "RPU.bin")
+    r = subprocess.run(["dovi_tool", "extract-rpu", "-i", annexb, "-o", rb],
+                       stdout=subprocess.PIPE, stderr=subprocess.PIPE, cwd=tmp)
+    if r.returncode == 0 and os.path.isfile(rb):
+        pl = rpu_payloads(rb)
+        hashes = [hashlib.sha1(p).hexdigest() for p in pl]
+        rpu = {"count": len(pl), "distinct": len(set(hashes)), "constant": len(set(hashes)) == 1}
+    return el, rpu
+
+
+def pick_frames(n_frames, per_seg):
+    """Frames to check: every frame, or `per_seg` evenly spread (>=3) in every phase segment."""
+    bounds = [0, G.PREROLL] + [G.PREROLL + G.PHASE_LEN * k for k in range(1, G.N_PHASES + 1)]
+    bounds = [b for b in bounds if b < n_frames] + [n_frames]
+    segs = [(bounds[k], bounds[k + 1]) for k in range(len(bounds) - 1)]
+    sel = set()
+    for a, b in segs:
+        idx = list(range(a, b))
+        if per_seg and len(idx) > per_seg:
+            idx = sorted({int(round(x)) for x in np.linspace(a, b - 1, max(per_seg, 3))})
+        sel.update(idx)
+    return sel
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("clip")
+    ap.add_argument("--frames", type=int, default=0,
+                    help="max frames checked per phase segment (default: all, minimum 3)")
+    ap.add_argument("--json", metavar="OUT")
+    a = ap.parse_args()
+    t0 = time.time()
+    design = G.el_design()
+    W, H = G.EL_W, G.EL_H
+    rois, areas = [], 0
+    for d in design:
+        x0, y0, x1, y1 = (v // 2 for v in d["box"])
+        ix, iy = int((x1 - x0) * INSET), int((y1 - y0) * INSET)
+        rois.append((y0 + iy, y1 - iy, x0 + ix, x1 - ix))
+        areas += (x1 - x0) * (y1 - y0)
+    area_frac = areas / (W * H)
+
+    tmp = tempfile.mkdtemp(prefix="check_el_")
+    try:
+        el, rpu = prepare_el(a.clip, tmp)
+        want_all = a.frames <= 0
+        fsize = W * H * 3 // 2 * 2
+        p = subprocess.Popen(["ffmpeg", "-v", "error", "-i", el, "-f", "rawvideo", "-pix_fmt", "yuv420p10le", "-"],
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        sel = None
+        if not want_all:
+            r = subprocess.run(["ffprobe", "-v", "error", "-count_packets", "-select_streams", "v:0",
+                                "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", el],
+                               stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            try:
+                sel = pick_frames(int(r.stdout.decode().strip().split(",")[0]), a.frames)
+            except ValueError:
+                sel = None
+        stats = {"A": {"n": 0, "nz": 0.0, "bad": 0, "med": [[] for _ in design]},
+                 "B": {"n": 0, "nz": 0.0, "bad": 0, "med": [[] for _ in design]}}
+        i = 0
+        while True:
+            buf = p.stdout.read(fsize)
+            if len(buf) < fsize:
+                break
+            if sel is None or i in sel:
+                ph = G.phase_of(i)
+                y = np.frombuffer(buf, dtype=np.uint16, count=W * H).reshape(H, W)
+                s = stats[ph]
+                s["n"] += 1
+                s["nz"] += float(np.count_nonzero(y != G.EL_FLAT)) / (W * H)
+                bad = False
+                for k, (ya, yb, xa, xb) in enumerate(rois):
+                    m = int(np.median(y[ya:yb, xa:xb]))
+                    s["med"][k].append(m)
+                    want = design[k]["el_code"] if ph == "B" else G.EL_FLAT
+                    if abs(m - want) > TOL:
+                        bad = True
+                s["bad"] += bad
+            i += 1
+        p.stdout.close()
+        err = p.stderr.read().decode(errors="replace")
+        if p.wait() != 0:
+            die("ffmpeg decode failed: " + err[-400:])
+        if i == 0:
+            die("decoded 0 frames from the EL" + (": " + err[-200:] if err else ""))
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    ok_all = True
+    print(f"{a.clip}: {i} EL frames decoded, checked A={stats['A']['n']} B={stats['B']['n']}, "
+          f"EL {W}x{H}, inset {int(INSET*100)}%, tol +-{TOL}")
+    print(f"{'patch':8} {'BL Y10':>6} {'dY10':>5} {'dY%':>6} | {'A want':>6} {'A med(min..max)':>16} {'':4} "
+          f"| {'B want':>6} {'B med(min..max)':>16}")
+    rows = []
+    for k, d in enumerate(design):
+        row = {"patch": d["name"], "bl_y10": d["bl_y10"], "delta10": d["delta10"], "delta_pct": d["delta_pct"],
+               "el_code_expected": d["el_code"]}
+        cells = []
+        for ph, want in (("A", G.EL_FLAT), ("B", d["el_code"])):
+            m = stats[ph]["med"][k]
+            if not m:
+                cells.append("n/a")
+                row[ph] = {"ok": None}
+                continue
+            lo, hi = min(m), max(m)
+            ok = abs(lo - want) <= TOL and abs(hi - want) <= TOL
+            ok_all &= ok
+            row[ph] = {"min": lo, "max": hi, "ok": ok}
+            cells.append(f"{lo}..{hi} {'PASS' if ok else 'FAIL'}")
+        print(f"{d['name']:8} {d['bl_y10']:6d} {d['delta10']:5d} {d['delta_pct']:6.2f} | {G.EL_FLAT:6d} "
+              f"{cells[0]:>21} | {d['el_code']:6d} {cells[1]:>21}")
+        rows.append(row)
+    res = {"clip": a.clip, "frames_decoded": i, "patches": rows, "area_fraction": area_frac}
+    for ph in "AB":
+        s = stats[ph]
+        if not s["n"]:
+            print(f"phase {ph}: no frames checked -> FAIL")
+            ok_all = False
+            continue
+        frac = s["nz"] / s["n"]
+        if ph == "A":
+            ok = frac == 0.0
+        else:
+            ok = abs(frac - area_frac) <= 0.15 * area_frac
+        ok_all &= ok and s["bad"] == 0
+        res["phase_" + ph] = {"frames": s["n"], "frames_failing": s["bad"], "nonflat_fraction": frac, "ok": ok}
+        extra = f" (patch area {100*area_frac:.2f}%)" if ph == "B" else ""
+        print(f"phase {ph}: {s['n']} frames, {s['bad']} failing, EL luma != 512: {100*frac:.3f}%{extra} "
+              f"-> {'PASS' if ok and s['bad'] == 0 else 'FAIL'}")
+    if stats["B"]["n"] and stats["B"]["nz"] == 0:
+        print("FAIL: phase B EL is flat 512 everywhere (no residual carried; null/flat-EL clip?)")
+    if rpu is None:
+        print("RPU constancy: skipped (EL-only input or extract-rpu failed)")
+    elif rpu["count"] == 0:
+        print("RPU constancy: no RPUs found -> skipped")
+    else:
+        ok = rpu["constant"]
+        ok_all &= ok
+        print(f"RPU constancy: {rpu['count']} RPUs, {rpu['distinct']} distinct payload(s) -> "
+              f"{'PASS' if ok else 'FAIL'}")
+    res["rpu"] = rpu
+    res["pass"] = bool(ok_all)
+    print(f"RESULT: {'PASS' if ok_all else 'FAIL'}  ({time.time()-t0:.1f}s)")
+    if a.json:
+        with open(a.json, "w") as f:
+            json.dump(res, f, indent=1)
+    sys.exit(0 if ok_all else 1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/Probes/DolbyVisionPulse/Scripts/cut.py b/Probes/DolbyVisionPulse/Scripts/cut.py
new file mode 100755
index 000000000..dffb1e716
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/cut.py
@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Cut a phone recording into one piece per arm using the harness's wall-clock log, then run
+analyze.py on each piece with its own label (no reliance on counting runs in order).
+
+  cut.py REC.MOV LOG [--sync VIDEO_S=HH:MM:SS.S] [--slates] [--out DIR]
+
+LOG is the devicectl console log (sequence_*.log) or the app's pulled pulse-log.txt; both carry
+'[Pulse] wall=<epoch> ...' lines. The video's wall-clock start comes from its QuickTime creationdate
+(1 s resolution). For sub-second accuracy, read the UTC clock on a slate frame (--slates writes one
+still per slate into DIR) and pass --sync <seconds into the video>=<clock shown>.
+"""
+import argparse
+import datetime as dt
+import importlib.util
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+HAVE_PIL = importlib.util.find_spec("PIL") is not None  # the per-arm plot needs Pillow
+PAD = 1.0  # seconds kept either side of an arm; analyze.py drops undecodable frames anyway
+
+
+def parse_iso_time(raw):
+    """ISO 8601 to epoch seconds. `datetime.fromisoformat` takes `Z` and `+0100` (no colon) only from
+    Python 3.11, and the system Python on macOS is older, so normalise both before parsing."""
+    raw = raw.strip()
+    if raw.endswith(("Z", "z")):
+        raw = raw[:-1] + "+00:00"
+    raw = re.sub(r"([+-]\d{2})(\d{2})$", r"\1:\2", raw)   # +0100 -> +01:00
+    raw = re.sub(r"([+-]\d{2})$", r"\1:00", raw)           # +01 -> +01:00
+    # Python <= 3.10 also wants 0, 3 or 6 fractional digits.
+    raw = re.sub(r"\.(\d+)", lambda m: "." + (m.group(1) + "000000")[:6], raw, count=1)
+    parsed = dt.datetime.fromisoformat(raw)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=dt.timezone.utc)
+    return parsed.timestamp()
+
+
+def video_start(rec):
+    out = subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format_tags", "-of", "json", rec],
+                         capture_output=True, text=True, check=True).stdout
+    tags = json.loads(out)["format"].get("tags", {})
+    raw = tags.get("com.apple.quicktime.creationdate") or tags.get("creation_time")
+    if not raw:
+        return None
+    return parse_iso_time(raw)
+
+
+def parse_log(path):
+    events = []
+    for line in Path(path).read_text(errors="replace").splitlines():
+        m = re.search(r"\[Pulse\] wall=([\d.]+) t=[\d.]+ (.*)", line)
+        if m and (float(m.group(1)), m.group(2)) not in events[-3:]:  # console echoes the app's own log lines
+            events.append((float(m.group(1)), m.group(2)))
+    if not events:
+        sys.exit(f"no '[Pulse] wall=' lines in {path} (log from an older build?)")
+    arms, slates, open_ = [], [], {}
+    for wall, msg in events:
+        if m := re.match(r"slate (\S+)", msg):
+            slates.append((wall, m.group(1)))
+        elif m := re.match(r"arm (\S+) start mode=(\S+) url=(\S+)", msg):
+            open_ = {"label": m.group(1), "mode": m.group(2), "clip": m.group(3), "start": wall}
+        elif (m := re.match(r"arm (\S+) end", msg)) and open_:
+            open_["end"] = wall
+            arms.append(open_)
+            open_ = {}
+    return arms, slates
+
+
+def sync_offset(spec, day_of):
+    vsec, clock = spec.split("=")
+    h, m, s = clock.replace("UTC", "").strip().split(":")
+    midnight = dt.datetime.fromtimestamp(day_of, dt.timezone.utc).replace(hour=0, minute=0, second=0,
+                                                                          microsecond=0).timestamp()
+    return midnight + int(h) * 3600 + int(m) * 60 + float(s) - float(vsec)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("recording")
+    ap.add_argument("log")
+    ap.add_argument("--sync", help="VIDEO_SECONDS=HH:MM:SS.S read off a slate frame")
+    ap.add_argument("--slates", action="store_true", help="only dump one still per slate, then stop")
+    ap.add_argument("--out", default=None, help="output dir (default <recording>_arms next to the recording)")
+    ap.add_argument("--scale", type=int, default=None, help="passed to analyze.py")
+    a = ap.parse_args()
+
+    rec = a.recording
+    out = Path(a.out or Path(rec).with_suffix("").as_posix() + "_arms")
+    out.mkdir(parents=True, exist_ok=True)
+    arms, slates = parse_log(a.log)
+    t0 = video_start(rec)
+    if a.sync:
+        t0 = sync_offset(a.sync, t0 if t0 is not None else arms[0]["start"])
+    elif t0 is None:
+        sys.exit("recording has no creation date; pass --sync")
+    print(f"video starts at {dt.datetime.fromtimestamp(t0, dt.timezone.utc):%H:%M:%S.%f}"[:-3] + " UTC"
+          + (" (from --sync)" if a.sync else " (from creationdate, ±1 s)"))
+
+    if a.slates:
+        for n, (wall, label) in enumerate(slates):
+            v = wall - t0 + 2.5  # mid-slate
+            p = out / f"slate{n + 1:02d}_{label}_{v:.1f}s.png"
+            subprocess.run(["ffmpeg", "-v", "error", "-y", "-ss", f"{v:.2f}", "-i", rec, "-frames:v", "1",
+                            "-vf", "scale=1280:-2", str(p)], check=True)
+            print(f"slate {label}: video {v:.1f}s -> {p}")
+        print("read the clock on one still, then rerun with --sync <video seconds>=<clock>")
+        return
+
+    summary = []
+    for n, arm in enumerate(arms):
+        lo = max(0.0, arm["start"] - t0 - PAD)
+        dur = arm["end"] - arm["start"] + 2 * PAD
+        tag = f"{n + 1:02d}_{arm['label']}"
+        clip = out / f"{tag}.mov"
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-ss", f"{lo:.2f}", "-i", rec, "-t", f"{dur:.2f}",
+                        "-map", "0:v:0", "-c", "copy", str(clip)], check=True)
+        cmd = [sys.executable, str(HERE / "analyze.py"), str(clip), "--arms", arm["label"],
+               "--json", str(out / f"{tag}.json")]
+        if HAVE_PIL:
+            cmd += ["--png", str(out / f"{tag}.png")]
+        if a.scale:
+            cmd += ["--scale", str(a.scale)]
+        print(f"\n=== {tag}  {arm['mode']} {arm['clip']}  video {lo:.1f}s +{dur:.1f}s ===", flush=True)
+        r = subprocess.run(cmd)
+        runs = []
+        if r.returncode == 0 and (out / f"{tag}.json").exists():
+            runs = json.loads((out / f"{tag}.json").read_text())
+        summary.append({"arm": arm["label"], "mode": arm["mode"], "clip": arm["clip"],
+                        "video_start": round(lo, 2), "duration": round(dur, 2),
+                        "runs": [{k: v for k, v in x.items() if not isinstance(v, (list, dict))}
+                                 for x in runs]})
+    (out / "summary.json").write_text(json.dumps(summary, indent=1))
+    print("\narm   mode       verdict(s)")
+    for s in summary:
+        v = ", ".join(f"{x.get('verdict')}({x.get('n_sig')})" for x in s["runs"]) or "no run decoded"
+        print(f"{s['arm']:<5} {s['mode']:<10} {v}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/Probes/DolbyVisionPulse/Scripts/dump_attachments.swift b/Probes/DolbyVisionPulse/Scripts/dump_attachments.swift
new file mode 100644
index 000000000..e142788d9
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/dump_attachments.swift
@@ -0,0 +1,72 @@
+// dump_attachments.swift - what does VideoToolbox attach to a decoded Dolby Vision frame?
+//
+// Decodes a Profile 8.1 clip with AVAssetReader (i.e. VideoToolbox's own decoder) and, for the chosen
+// frames, prints every attachment on the CVPixelBuffer plus the sample-buffer attachment keys. For all
+// frames it records a short SHA-256 of the "DolbyVisionRPUData" attachment and finishes with a summary
+// of how many frames share each hash.
+//
+// What it proves: the RPU payload (its size and bytes) that VideoToolbox itself attaches to the pixel
+// buffer, so the payload an engine attaches can be compared byte-for-byte with it. On the pulse clip the
+// hash must differ between an A-phase and a B-phase frame (the RPU changes with the pulse). Expect two
+// hashes per phase: keyframes carry a slightly different payload from the frames between them.
+//
+// Usage: swift dump_attachments.swift <clip.mp4> [frame indices...]
+//   e.g. swift dump_attachments.swift pulse_l2.mp4 0 200
+import AVFoundation
+import CryptoKit
+
+let args = CommandLine.arguments
+guard args.count >= 2 else {
+    FileHandle.standardError.write(Data("usage: swift dump_attachments.swift <clip.mp4> [frames...]\n".utf8))
+    exit(2)
+}
+let url = URL(fileURLWithPath: args[1])
+let want = Set(args.dropFirst(2).compactMap(Int.init))
+let asset = AVURLAsset(url: url)
+let sem = DispatchSemaphore(value: 0)
+Task {
+  do {
+    let track = try await asset.loadTracks(withMediaType: .video)[0]
+    let fds = try await track.load(.formatDescriptions)
+    if let fd = fds.first {
+        print("codec:", String(fourCC: CMFormatDescriptionGetMediaSubType(fd)))
+        print("format extensions:", (CMFormatDescriptionGetExtensions(fd) as? [String: Any])?.keys.sorted() ?? [])
+    }
+    let reader = try AVAssetReader(asset: asset)
+    let out = AVAssetReaderTrackOutput(track: track, outputSettings: [
+        kCVPixelBufferPixelFormatTypeKey as String: kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange])
+    reader.add(out)
+    reader.startReading()
+    var i = 0
+    var hashes: [String: [Int]] = [:]
+    while let sb = out.copyNextSampleBuffer() {
+        defer { i += 1 }
+        guard let pb = CMSampleBufferGetImageBuffer(sb) else { continue }
+        let atts = CVBufferCopyAttachments(pb, .shouldPropagate) as? [String: Any] ?? [:]
+        let rpu = atts["DolbyVisionRPUData"] as? Data
+        let h = rpu.map { SHA256.hash(data: $0).prefix(4).map { String(format: "%02x", $0) }.joined() } ?? "none"
+        hashes[h, default: []].append(i)
+        if want.contains(i) {
+            print("frame \(i): rpu=\(rpu?.count ?? 0)B hash=\(h) compat=\(atts["DolbyCompatibilityID"] ?? "nil")")
+            print("  keys:", atts.keys.sorted())
+            let sa = CMSampleBufferGetSampleAttachmentsArray(sb, createIfNecessary: false) as? [[String: Any]]
+            print("  sample attachments:", sa?.first?.keys.sorted() ?? [])
+        }
+    }
+    print("frames decoded:", i)
+    for (h, frames) in hashes.sorted(by: { $0.value.first! < $1.value.first! }) {
+        print("rpu \(h): \(frames.count) frames, first \(frames.first!), last \(frames.last!)")
+    }
+  } catch {
+    FileHandle.standardError.write(Data("error: \(error)\n".utf8))
+    exit(1)
+  }
+  sem.signal()
+}
+sem.wait()
+
+extension String {
+    init(fourCC v: FourCharCode) {
+        self = String(bytes: [24, 16, 8, 0].map { UInt8((v >> $0) & 0xff) }, encoding: .ascii) ?? "\(v)"
+    }
+}
diff --git a/Probes/DolbyVisionPulse/Scripts/fel_count.py b/Probes/DolbyVisionPulse/Scripts/fel_count.py
new file mode 100755
index 000000000..938a5ce48
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/fel_count.py
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Profile 7 FEL counter clip: the base layer and the enhancement layer each carry their own frame number.
+
+Same pattern, timeline and RPU variants as gen_pulse.py, plus readable counters for filming:
+
+  top band     "BL 0123" in base-layer pixels | "EL 0123" in enhancement-layer residual only
+  slow row     "BL S005" | "EL S005"  (frame // 24, readable when the fast numbers blur on camera)
+  code cells   BL: gen_pulse.py's Gray-code row; EL: a second row below it, drawn in residual only
+
+Every counter sits on a dark grey panel (~20 nit, Y 380); a lit stroke is +120 10-bit codes (~90 nit), which
+is the largest positive residual fel_orig.bin's NLQ can carry (|EL-512| - 1 12-bit codes, vdr_in_max 0.125).
+Composed properly, both sides show the same number. A MEL player (residual ignored) shows an empty EL panel and
+an EL code row that does not decode. A player pairing the wrong EL frame shows a different EL number.
+
+Both layers use the same fixed GOP (b-adapt 0, 3 B-frames, pyramid) so EL and BL POC order match. build.sh
+encodes and muxes the clips (p7fel_count_{null,l2}.mp4, count_mel.mp4).
+
+Usage: fel_count.py frames     -> raw 3840x2160 yuv420p10le BL frames on stdout (feed x265)
+       fel_count.py el-frames  -> raw 1920x1080 yuv420p10le EL frames on stdout (feed x265)
+       fel_count.py layout     -> panel/cell boxes as JSON
+       fel_count.py read <composed.yuv> [bitdepth=10]  -> per frame: BL code, EL code (decoded back from cells)
+                                                   of raw 3840x2160 yuv420p frames from any composer
+"""
+import json
+import sys
+
+import numpy as np
+
+import gen_pulse as gp
+
+W, H, N_FRAMES = gp.W, gp.H, gp.N_FRAMES
+EL_W, EL_H = W // 2, H // 2
+PANEL_Y = 380          # PQ 0.36, ~20 nit, neutral
+LIFT10 = 120           # stroke lift in 10-bit codes (BL pixels or EL residual)
+EL_ON = gp.EL_FLAT + 4 * LIFT10 + 1
+SLOW = 24              # slow counter period in frames
+
+# 5x7 glyphs, rows top to bottom
+FONT = {
+    "0": ["01110", "10001", "10011", "10101", "11001", "10001", "01110"],
+    "1": ["00100", "01100", "00100", "00100", "00100", "00100", "01110"],
+    "2": ["01110", "10001", "00001", "00010", "00100", "01000", "11111"],
+    "3": ["11111", "00010", "00100", "00010", "00001", "10001", "01110"],
+    "4": ["00010", "00110", "01010", "10010", "11111", "00010", "00010"],
+    "5": ["11111", "10000", "11110", "00001", "00001", "10001", "01110"],
+    "6": ["00110", "01000", "10000", "11110", "10001", "10001", "01110"],
+    "7": ["11111", "00001", "00010", "00100", "01000", "01000", "01000"],
+    "8": ["01110", "10001", "10001", "01110", "10001", "10001", "01110"],
+    "9": ["01110", "10001", "10001", "01111", "00001", "00010", "01100"],
+    "B": ["11110", "10001", "10001", "11110", "10001", "10001", "11110"],
+    "L": ["10000", "10000", "10000", "10000", "10000", "10000", "11111"],
+    "E": ["11111", "10000", "10000", "11110", "10000", "10000", "11111"],
+    "S": ["01111", "10000", "10000", "01110", "00001", "00001", "11110"],
+    " ": ["00000"] * 7,
+}
+
+
+def text_mask(s, scale):
+    """Boolean mask of s, glyph advance 6 cells (1 cell spacing)."""
+    m = np.zeros((7 * scale, (6 * len(s) - 1) * scale), dtype=bool)
+    for k, ch in enumerate(s):
+        g = np.array([[c == "1" for c in row] for row in FONT[ch]])
+        m[:, 6 * k * scale:(6 * k + 5) * scale] = np.kron(g, np.ones((scale, scale), dtype=bool))
+    return m
+
+
+def layout():
+    base = gp.layout()
+    # Top band between the fiducials, slow row between the ramp and the BL cells, EL cells below the BL cells.
+    # All coordinates even, so the half-resolution EL boxes are exact.
+    top = {"bl": [520, 160, 1980, 380], "el": [2100, 160, 3560, 380], "scale": 28}
+    slow = {"bl": [520, 1566, 1980, 1714], "el": [2100, 1566, 3560, 1714], "scale": 16}
+    el_cells = [[c[0], 1940, c[2], 2080] for c in base["code_cells"]]
+    panel = [el_cells[0][0] - 20, 1930, el_cells[-1][2] + 20, 2090]
+    return {"base": base, "top": top, "slow": slow, "bl_cells": base["code_cells"], "el_cells": el_cells,
+            "el_cells_panel": panel, "panel_y": PANEL_Y, "lift10": LIFT10, "el_on": EL_ON}
+
+
+def place(box, mask):
+    """Top-left of mask centred in box, even."""
+    x0, y0, x1, y1 = box
+    h, w = mask.shape
+    return (x0 + (x1 - x0 - w) // 2) & ~1, (y0 + (y1 - y0 - h) // 2) & ~1
+
+
+def labels(i):
+    return f"{i:04d}", f"S{i // SLOW:03d}"
+
+
+def write_frames(out):
+    L = layout()
+    Y, Cb, Cr = gp.base_planes(L["base"])
+    for band in ("top", "slow"):
+        for side in ("bl", "el"):
+            x0, y0, x1, y1 = L[band][side]
+            Y[y0:y1, x0:x1] = PANEL_Y
+    x0, y0, x1, y1 = L["el_cells_panel"]
+    Y[y0:y1, x0:x1] = PANEL_Y
+    on = gp.rgb_nits_to_ycc10((gp.CELL_NITS,) * 3)[0]
+    cb_bytes, cr_bytes = Cb.tobytes(), Cr.tobytes()
+    clean = Y.copy()
+    for i in range(N_FRAMES):
+        Y[:] = clean
+        fast, slow = labels(i)
+        for band, s in (("top", "BL " + fast), ("slow", "BL " + slow)):
+            m = text_mask(s, L[band]["scale"])
+            px, py = place(L[band]["bl"], m)
+            Y[py:py + m.shape[0], px:px + m.shape[1]][m] = PANEL_Y + LIFT10
+        for bit, (x0, y0, x1, y1) in zip(gp.code_bits_for(i), L["bl_cells"]):
+            Y[y0:y1, x0:x1] = on if bit else 64
+        out.write(Y.tobytes())
+        out.write(cb_bytes)
+        out.write(cr_bytes)
+
+
+def write_el_frames(out):
+    L = layout()
+    Y = np.full((EL_H, EL_W), gp.EL_FLAT, dtype=np.uint16)
+    chroma = np.full((EL_H // 2) * (EL_W // 2), gp.EL_FLAT, dtype=np.uint16).tobytes()
+    for i in range(N_FRAMES):
+        Y[:] = gp.EL_FLAT
+        fast, slow = labels(i)
+        for band, s in (("top", "EL " + fast), ("slow", "EL " + slow)):
+            sc = L[band]["scale"]
+            m = text_mask(s, sc // 2)
+            px, py = place(L[band]["el"], text_mask(s, sc))
+            Y[py // 2:py // 2 + m.shape[0], px // 2:px // 2 + m.shape[1]][m] = EL_ON
+        for bit, (x0, y0, x1, y1) in zip(gp.code_bits_for(i), L["el_cells"]):
+            if bit:
+                Y[y0 // 2:y1 // 2, x0 // 2:x1 // 2] = EL_ON
+        out.write(Y.tobytes())
+        out.write(chroma)
+        out.write(chroma)
+
+
+def read_cells(Yf, cells, thr):
+    """Decode a code row from a full-resolution luma plane in 10-bit codes (centre 50% of each cell)."""
+    bits = []
+    for x0, y0, x1, y1 in cells:
+        dx, dy = (x1 - x0) // 4, (y1 - y0) // 4
+        bits.append(int(np.median(Yf[y0 + dy:y1 - dy, x0 + dx:x1 - dx]) > thr))
+    return gp.decode_bits(bits)
+
+
+def read(path, depth=10):
+    L = layout()
+    on = gp.rgb_nits_to_ycc10((gp.CELL_NITS,) * 3)[0]
+    fsize = W * H * 3 // 2
+    data = np.memmap(path, dtype=np.uint16, mode="r")
+    for k in range(len(data) // fsize):
+        Yf = data[k * fsize:k * fsize + W * H].reshape(H, W).astype(np.float64) / (1 << (depth - 10))
+        bl = read_cells(Yf, L["bl_cells"], (64 + on) / 2)
+        el = read_cells(Yf, L["el_cells"], PANEL_Y + LIFT10 / 2)
+        print(k, bl, el, "no-EL" if el is None else "ok" if bl == el else "MISMATCH")
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else ""
+    if cmd == "frames":
+        write_frames(sys.stdout.buffer)
+    elif cmd == "el-frames":
+        write_el_frames(sys.stdout.buffer)
+    elif cmd == "layout":
+        json.dump({k: v for k, v in layout().items() if k != "base"}, sys.stdout, indent=1)
+    elif cmd == "read" and len(sys.argv) in (3, 4):
+        read(sys.argv[2], int(sys.argv[3]) if len(sys.argv) == 4 else 10)
+    else:
+        sys.exit(__doc__)
diff --git a/Probes/DolbyVisionPulse/Scripts/gen_pulse.py b/Probes/DolbyVisionPulse/Scripts/gen_pulse.py
new file mode 100755
index 000000000..bd0cb4adb
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/gen_pulse.py
@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""Synthetic Dolby Vision pulse clips for the RPU-consumption experiment.
+
+The pixels are identical in every variant and every phase, except for a frame-counter strip that
+the analysis reads back from the phone video. Only the RPU changes:
+
+  l2    L1 constant (true stats); L2 trims at 100/600/1000/4000-nit targets switch neutral <-> extreme
+  l1    L1 max_pq switches 100 nits <-> 10000 nits; no trims
+  null  L1 constant, L2 trims always neutral (same shot boundaries as l2)
+
+Timeline at 24000/1001 fps: 144 frames of phase A (pre-roll, lets the HDMI mode switch settle),
+then 20 phases of 72 frames alternating B, A, B, ... (10 cycles of ~6 s). The phase of any frame is
+a pure function of its index, see `phase_of`.
+
+Usage: gen_pulse.py layout                  -> layout.json (patch boxes, code cells) on stdout
+       gen_pulse.py frames                  -> raw yuv420p10le frames on stdout (feed x265)
+       gen_pulse.py rpu-json <variant>      -> dovi_tool generate config on stdout
+       gen_pulse.py el-frames               -> raw 1920x1080 yuv420p10le EL frames on stdout (feed x265)
+       gen_pulse.py el-design               -> the EL residual design (patches, EL codes) as JSON
+
+el-frames is for the p7fel_el clip: the RPU is constant (as in `null`), the enhancement layer is flat
+512 (zero residual) in phase A and carries a positive luma residual on EL_PATCHES in phase B.
+"""
+import json
+import sys
+
+import numpy as np
+
+W, H = 3840, 2160
+FPS_NUM, FPS_DEN = 24000, 1001
+PREROLL = 144
+PHASE_LEN = 72
+N_PHASES = 20
+N_FRAMES = PREROLL + PHASE_LEN * N_PHASES  # 1584, ~66 s
+
+CODE_BITS = 12  # frame index, Gray-coded
+CELL_NITS = 300.0
+FID_NITS = 300.0
+
+
+def phase_of(i):
+    """'A' or 'B' for frame index i."""
+    if i < PREROLL:
+        return "A"
+    return "B" if ((i - PREROLL) // PHASE_LEN) % 2 == 0 else "A"
+
+
+def pq(nits):
+    m1 = 2610 / 16384
+    m2 = 2523 / 4096 * 128
+    c1 = 3424 / 4096
+    c2 = 2413 / 4096 * 32
+    c3 = 2392 / 4096 * 32
+    y = np.power(np.asarray(nits, dtype=np.float64) / 10000.0, m1)
+    return np.power((c1 + c2 * y) / (1 + c3 * y), m2)
+
+
+def pq12(nits):
+    return int(round(float(pq(nits)) * 4095))
+
+
+# ---------------------------------------------------------------- layout
+GRAY_NITS = [0.1, 1, 10, 50, 100, 200, 400, 600, 1000, 2000, 4000, 10000]
+# Linear-light BT.2020 RGB in nits.
+COLORS = {
+    "gray150": (150, 150, 150),
+    "red": (400, 60, 60),
+    "green": (60, 300, 60),
+    "blue": (60, 60, 400),
+    "yellow": (300, 300, 40),
+    "cyan": (40, 300, 300),
+    "magenta": (300, 40, 300),
+    "skin": (250, 160, 120),
+}
+
+
+def layout():
+    boxes = []  # name, x0, y0, x1, y1, rgb nits
+    pw, gap, x0 = 240, 40, 260
+    for k, n in enumerate(GRAY_NITS):
+        x = x0 + k * (pw + gap)
+        boxes.append({"name": f"g{n:g}", "box": [x, 400, x + pw, 760], "rgb": [n, n, n]})
+    cw, cgap = 380, 40
+    cx0 = (W - (len(COLORS) * cw + (len(COLORS) - 1) * cgap)) // 2
+    for k, (name, rgb) in enumerate(COLORS.items()):
+        x = cx0 + k * (cw + cgap)
+        boxes.append({"name": name, "box": [x, 880, x + cw, 1240], "rgb": list(rgb)})
+    ramp = {"name": "ramp", "box": [260, 1360, 260 + 3320, 1560], "pq_range": [0.0, float(pq(1000))]}
+    cells = []
+    nc, cell, cgap2 = CODE_BITS + 4, 180, 20
+    sx = (W - (nc * cell + (nc - 1) * cgap2)) // 2
+    for k in range(nc):
+        x = sx + k * (cell + cgap2)
+        cells.append([x, 1720, x + cell, 1900])
+    s, m = 200, 80
+    fids = [[m, m, m + s, m + s], [W - m - s, m, W - m, m + s],
+            [m, H - m - s, m + s, H - m], [W - m - s, H - m - s, W - m, H - m]]
+    # Orientation tag right of the top-left fiducial.
+    tag = [m + s + 60, m + 50, m + s + 160, m + 150]
+    return {"width": W, "height": H, "fps": [FPS_NUM, FPS_DEN], "preroll": PREROLL,
+            "phase_len": PHASE_LEN, "n_phases": N_PHASES, "n_frames": N_FRAMES,
+            "patches": boxes, "ramp": ramp, "code_cells": cells, "code_bits": CODE_BITS,
+            "fiducials": fids, "orientation_tag": tag, "cell_nits": CELL_NITS}
+
+
+def code_bits_for(i):
+    """16 cells: [1, gray(11..0), parity(gray 0-5), parity(gray 6-11), 1]."""
+    g = i ^ (i >> 1)
+    bits = [(g >> (CODE_BITS - 1 - b)) & 1 for b in range(CODE_BITS)]
+    p_lo = sum(bits[CODE_BITS - 6:]) & 1
+    p_hi = sum(bits[:CODE_BITS - 6]) & 1
+    return [1] + bits + [p_lo, p_hi, 1]
+
+
+def decode_bits(cells):
+    """Inverse of code_bits_for; returns frame index or None if the check fails."""
+    if len(cells) != CODE_BITS + 4 or cells[0] != 1 or cells[-1] != 1:
+        return None
+    bits = cells[1:1 + CODE_BITS]
+    if (sum(bits[CODE_BITS - 6:]) & 1) != cells[CODE_BITS + 1] or (sum(bits[:CODE_BITS - 6]) & 1) != cells[CODE_BITS + 2]:
+        return None
+    g = 0
+    for b in bits:
+        g = (g << 1) | b
+    n = 0
+    while g:
+        n ^= g
+        g >>= 1
+    return n
+
+
+# ---------------------------------------------------------------- pixels
+def rgb_nits_to_ycc10(rgb):
+    r, g, b = (float(pq(c)) for c in rgb)
+    y = 0.2627 * r + 0.6780 * g + 0.0593 * b
+    cb = (b - y) / 1.8814
+    cr = (r - y) / 1.4746
+    return (int(round(64 + 876 * y)), int(round(512 + 896 * cb)), int(round(512 + 896 * cr)))
+
+
+def base_planes(L):
+    Y = np.full((H, W), 64, dtype=np.uint16)
+    Cb = np.full((H // 2, W // 2), 512, dtype=np.uint16)
+    Cr = np.full((H // 2, W // 2), 512, dtype=np.uint16)
+
+    def fill(box, rgb):
+        x0, y0, x1, y1 = box
+        yv, cbv, crv = rgb_nits_to_ycc10(rgb)
+        Y[y0:y1, x0:x1] = yv
+        Cb[y0 // 2:y1 // 2, x0 // 2:x1 // 2] = cbv
+        Cr[y0 // 2:y1 // 2, x0 // 2:x1 // 2] = crv
+
+    for p in L["patches"]:
+        fill(p["box"], p["rgb"])
+    x0, y0, x1, y1 = L["ramp"]["box"]
+    lo, hi = L["ramp"]["pq_range"]
+    ramp = np.linspace(lo, hi, x1 - x0)
+    Y[y0:y1, x0:x1] = np.round(64 + 876 * ramp).astype(np.uint16)[None, :]
+    for f in L["fiducials"] + [L["orientation_tag"]]:
+        fill(f, (FID_NITS,) * 3)
+    return Y, Cb, Cr
+
+
+def l1_stats(L):
+    """L1 min/max/avg in 12-bit PQ over max(R',G',B'), code strip assumed half on."""
+    Y, _, _ = base_planes(L)
+    # Gray/colour patches: use max(R',G',B') per patch weighted by area.
+    tot = W * H
+    acc = 0.0
+    mx = 0.0
+    for p in L["patches"]:
+        x0, y0, x1, y1 = p["box"]
+        v = max(float(pq(c)) for c in p["rgb"])
+        acc += v * (x1 - x0) * (y1 - y0)
+        mx = max(mx, v)
+    x0, y0, x1, y1 = L["ramp"]["box"]
+    lo, hi = L["ramp"]["pq_range"]
+    acc += (lo + hi) / 2 * (x1 - x0) * (y1 - y0)
+    v = float(pq(FID_NITS))
+    for f in L["fiducials"] + [L["orientation_tag"]]:
+        acc += v * (f[2] - f[0]) * (f[3] - f[1])
+    for c in L["code_cells"]:
+        acc += 0.5 * float(pq(CELL_NITS)) * (c[2] - c[0]) * (c[3] - c[1])
+    return 0, int(round(mx * 4095)), int(round(acc / tot * 4095))
+
+
+def write_frames(out):
+    L = layout()
+    Y, Cb, Cr = base_planes(L)
+    on = rgb_nits_to_ycc10((CELL_NITS,) * 3)[0]
+    cb_bytes, cr_bytes = Cb.tobytes(), Cr.tobytes()
+    for i in range(N_FRAMES):
+        for bit, (x0, y0, x1, y1) in zip(code_bits_for(i), L["code_cells"]):
+            Y[y0:y1, x0:x1] = on if bit else 64
+        out.write(Y.tobytes())
+        out.write(cb_bytes)
+        out.write(cr_bytes)
+
+
+# ---------------------------------------------------------------- enhancement layer (p7fel_el)
+EL_W, EL_H = W // 2, H // 2
+EL_FLAT = 512          # = nlq_offset of fel_orig.bin, i.e. zero residual
+EL_GAIN = 0.17         # target luma change in PQ code value, fraction of the patch's own 10-bit Y
+EL_MAX_DELTA10 = 120   # cap in 10-bit codes: the NLQ range is +-511 12-bit codes (= +-127.75 10-bit)
+# Every other grey patch from 10 to 1000 nit, plus two colour patches. The rest are in-frame controls.
+EL_PATCHES = ["g10", "g100", "g400", "g1000", "red", "cyan"]
+
+
+def el_design():
+    """Per target patch: BL Y, wanted 10-bit delta, EL code. fel_orig.bin NLQ (all components):
+    nlq_offset 512, vdr_in_max 0.125, slope 2048 @ denom 23, threshold 0, vdr 12 bit. The composer's
+    inverse NLQ then gives residual = (|EL-512| - 1/2) * 2048 >> 11 = |EL-512| - 1 VDR 12-bit codes
+    (= 1/4 of a code in the 10-bit output), assuming the BL->VDR luma map is identity-scaled
+    (poly c0=0, c1=1); that is checked empirically, not assumed."""
+    out = []
+    for p in layout()["patches"]:
+        if p["name"] not in EL_PATCHES:
+            continue
+        y10 = rgb_nits_to_ycc10(p["rgb"])[0]
+        d10 = min(int(round(EL_GAIN * y10)), EL_MAX_DELTA10, 940 - y10)
+        d12 = 4 * d10
+        out.append({"name": p["name"], "box": p["box"], "bl_y10": y10, "delta10": d10,
+                    "delta_pct": round(100.0 * d10 / y10, 2), "el_code": EL_FLAT + d12 + 1})
+    return out
+
+
+def write_el_frames(out):
+    A = np.full((EL_H, EL_W), EL_FLAT, dtype=np.uint16)
+    B = A.copy()
+    for d in el_design():
+        x0, y0, x1, y1 = (v // 2 for v in d["box"])
+        B[y0:y1, x0:x1] = d["el_code"]
+    chroma = np.full((EL_H // 2) * (EL_W // 2), EL_FLAT, dtype=np.uint16).tobytes()
+    fa = A.tobytes() + chroma + chroma
+    fb = B.tobytes() + chroma + chroma
+    for i in range(N_FRAMES):
+        out.write(fb if phase_of(i) == "B" else fa)
+
+
+# ---------------------------------------------------------------- RPU configs
+NEUTRAL_TRIM = dict(trim_slope=2048, trim_offset=2048, trim_power=2048,
+                    trim_chroma_weight=2048, trim_saturation_gain=2048, ms_weight=2048)
+# Darker and nearly monochrome: slope 0.625, offset -1/16, power 1.375, saturation -0.5.
+EXTREME_TRIM = dict(trim_slope=512, trim_offset=1792, trim_power=3584,
+                    trim_chroma_weight=2048, trim_saturation_gain=0, ms_weight=2048)
+TRIM_TARGETS = [100, 600, 1000, 4000]
+
+
+def shots():
+    """(start, duration, phase) covering the timeline."""
+    out = [(0, PREROLL, "A")]
+    for k in range(N_PHASES):
+        s = PREROLL + k * PHASE_LEN
+        out.append((s, PHASE_LEN, phase_of(s)))
+    return out
+
+
+def rpu_config(variant):
+    L = layout()
+    mn, mx, avg = l1_stats(L)
+    cfg = {
+        "cm_version": "V29",
+        "profile": "8.1",
+        "length": N_FRAMES,
+        "level6": {"max_display_mastering_luminance": 10000, "min_display_mastering_luminance": 1,
+                   "max_content_light_level": 10000, "max_frame_average_light_level": 400},
+        "shots": [],
+    }
+    for start, dur, ph in shots():
+        blocks = []
+        if variant == "l1":
+            peak = 2081 if ph == "A" else 4095
+            blocks.append({"Level1": {"min_pq": mn, "max_pq": peak, "avg_pq": min(avg, peak)}})
+        else:
+            blocks.append({"Level1": {"min_pq": mn, "max_pq": mx, "avg_pq": avg}})
+            trim = EXTREME_TRIM if (variant == "l2" and ph == "B") else NEUTRAL_TRIM
+            for t in TRIM_TARGETS:
+                blocks.append({"Level2": dict(target_max_pq=pq12(t), **trim)})
+        cfg["shots"].append({"start": start, "duration": dur, "metadata_blocks": blocks})
+    return cfg
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else ""
+    if cmd == "layout":
+        L = layout()
+        L["l1"] = dict(zip(["min_pq", "max_pq", "avg_pq"], l1_stats(L)))
+        json.dump(L, sys.stdout, indent=1)
+    elif cmd == "frames":
+        write_frames(sys.stdout.buffer)
+    elif cmd == "el-frames":
+        write_el_frames(sys.stdout.buffer)
+    elif cmd == "el-design":
+        json.dump(el_design(), sys.stdout, indent=1)
+    elif cmd == "rpu-json" and len(sys.argv) == 3 and sys.argv[2] in ("l1", "l2", "null"):
+        json.dump(rpu_config(sys.argv[2]), sys.stdout, indent=1)
+    else:
+        sys.exit(__doc__)
diff --git a/Probes/DolbyVisionPulse/Scripts/report.py b/Probes/DolbyVisionPulse/Scripts/report.py
new file mode 100755
index 000000000..adce053f0
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/report.py
@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Turn a directory of cut arms (cut.py output) into the tables and figure used in the write-up.
+
+Reads ARMS_DIR/summary.json and every NN_<ARM>.json (analyze.py --json output) and prints:
+  1. "Change in camera brightness, B vs A" - per patch, rel as a signed integer percent.
+     A non-PULSE arm shows 0 unless the patch has |t| > 5, then the signed percent.
+     Rows whose mode starts with "engine" (the engine/FEL route) are bold.
+  2. a significance line per arm (patches with |t| > 5, strongest t).
+  3. "absolute levels" (phase A level, 3 decimals) for selected arms and patches.
+Optionally writes the markdown (--md) and the all-arms trace figure (--png, via analyze.png).
+
+  report.py recordings/take_arms --md report.md --png report.png
+"""
+import argparse
+import json
+import math
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+MINUS = "−"
+
+
+def pct(rel):
+    """Signed integer percent, round-half-away, real minus sign, '+' for positives, '0' for zero."""
+    p = int(math.floor(abs(rel) * 100 + 0.5))
+    if p == 0:
+        return "0"
+    return ("+" if rel > 0 else MINUS) + str(p)
+
+
+def cell(res, name):
+    p = res["patches"].get(name)
+    if p is None:
+        return "n/a"
+    if res["verdict"] != "PULSE" and abs(p["t"]) <= 5:
+        return "0"
+    return pct(p["rel"])
+
+
+def header(name):
+    if name.startswith("g") and name[1:].replace(".", "", 1).isdigit():
+        return f"{name[1:]} nit"
+    return name
+
+
+def load(arms_dir):
+    summary = json.load(open(os.path.join(arms_dir, "summary.json")))
+    rows, seen = [], {}
+    for n, s in enumerate(summary, 1):
+        arm = s["arm"]
+        k = seen[arm] = seen.get(arm, 0) + 1
+        label = arm if k == 1 else (f"{arm} (repeat)" if k == 2 else f"{arm} (repeat {k - 1})")
+        path = os.path.join(arms_dir, f"{n:02d}_{arm}.json")
+        runs = json.load(open(path)) if os.path.exists(path) else []
+        rows.append({"arm": arm, "label": label, "mode": s.get("mode", ""), "runs": runs})
+    return rows
+
+
+def build(rows, patches, level_arms, level_patches):
+    out = ["Change in camera brightness, B vs A (percent):", ""]
+    out.append("| Run | Verdict | " + " | ".join(header(p) for p in patches) + " |")
+    out.append("|---|---|" + "---|" * len(patches))
+    notes = []
+    for r in rows:
+        bold = r["mode"].startswith("engine")
+        if not r["runs"]:
+            out.append(f"| {r['label']} | no run decoded |" + " |" * len(patches))
+            notes.append(f"- {r['label']}: no run decoded")
+            continue
+        for k, res in enumerate(r["runs"], 1):
+            lab = r["label"] + (f" run {k}" if len(r["runs"]) > 1 else "")
+            lab = f"**{lab}**" if bold else lab
+            out.append(f"| {lab} | {res['verdict']} | " + " | ".join(cell(res, p) for p in patches) + " |")
+            top = max(res["patches"].items(), key=lambda kv: abs(kv[1]["t"]))
+            notes.append(f"- {lab}: {res['n_sig']} patches with |t|>5, strongest t = "
+                         f"{top[1]['t']:+.1f} ({top[0]})")
+    out += [""] + notes + ["", "Absolute levels (phase A):", ""]
+    out.append("| Run | " + " | ".join(header(p) for p in level_patches) + " |")
+    out.append("|---|" + "---|" * len(level_patches))
+    for r in rows:
+        if r["arm"] not in level_arms or not r["runs"]:
+            continue
+        res = r["runs"][0]
+        lab = r["label"] + (" (phase A)" if res["verdict"] == "PULSE" else "")
+        vals = [f"{res['patches'][p]['level']:.3f}" if p in res["patches"] else "n/a" for p in level_patches]
+        out.append(f"| {lab} | " + " | ".join(vals) + " |")
+    return "\n".join(out) + "\n"
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("arms_dir")
+    ap.add_argument("--md", help="also write the markdown here")
+    ap.add_argument("--png", help="write the all-arms trace figure here")
+    ap.add_argument("--levels-arms", default="V1,V2,T,S", help="arms for the absolute-levels table")
+    ap.add_argument("--patches", default="g10,g100,g400,g1000,g4000,g10000")
+    ap.add_argument("--levels-patches", default="g10,g100,g1000,g10000")
+    a = ap.parse_args()
+    rows = load(a.arms_dir)
+    md = build(rows, a.patches.split(","), set(a.levels_arms.split(",")), a.levels_patches.split(","))
+    print(md)
+    if a.md:
+        open(a.md, "w").write(md)
+    if a.png:
+        import analyze
+        results = [dict(res, arm=r["label"]) for r in rows for res in r["runs"]]
+        if results:
+            analyze.png(results, a.png)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/Probes/DolbyVisionPulse/Scripts/run_tv.sh b/Probes/DolbyVisionPulse/Scripts/run_tv.sh
new file mode 100755
index 000000000..50d053791
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/run_tv.sh
@@ -0,0 +1,95 @@
+#!/bin/zsh
+# Builds the pulse host, installs it on an Apple TV, serves the clips from this Mac and plays an arm
+# sequence, with the console attached. Only run it when a television session is wanted.
+#
+#   DEVICE="Apple TV" ./run_tv.sh               build + install, then play SEQ=main (about 11 min)
+#   DEVICE=... ./run_tv.sh --no-build           play only (app already installed)
+#   DEVICE=... SEQ=el ./run_tv.sh               TE engine (FEL) / NE enginenofel (EL dropped) on p7fel_el.mp4, then T
+#   DEVICE=... SEQ=vt ./run_tv.sh               the three VideoToolbox arms only, on pulse_l2.mp4
+#   DEVICE=... SEQ=count ./run_tv.sh            counter clips: T / NE / TL (FEL route, residual, RPU pulse) and PM (8.1 control)
+#   DEVICE=... SEQ=soak SOAK_URL=<http url | file under $PULSE_OUT> [SOAK_MIN=5] [SOAK_SEEKS=60@1800,150@600,240@3000] ./run_tv.sh
+#                                               one FEL soak arm; its summary line is grepped at the end
+#
+# Required: DEVICE, a `xcrun devicectl list devices` name or identifier.
+# Optional: TEAM (development team id, for signing), PULSE_BUNDLE_PREFIX (default
+#           de.superuser404.dolbyvisionpulse), PULSE_OUT (clip directory, default ../out),
+#           PORT (default 8765), DD (derived data path, default ../.dd, gitignored),
+#           IFACE (network interface whose address the Apple TV fetches the clips from; default: the
+#           first of en0, en1 that has an address).
+# Xcode is the one `xcode-select -p` points at; set DEVELOPER_DIR to use another.
+set -euo pipefail
+HERE=${0:A:h}
+ROOT=${HERE:h}
+: "${DEVICE:?set DEVICE to a devicectl name or id (xcrun devicectl list devices)}"
+xcrun --find xcodebuild >/dev/null 2>&1 || { echo "no Xcode found: install it or run xcode-select -s <Xcode.app>/Contents/Developer"; exit 1; }
+PREFIX=${PULSE_BUNDLE_PREFIX:-de.superuser404.dolbyvisionpulse}
+BUNDLE=$PREFIX.host
+OUT=${PULSE_OUT:-$ROOT/out}
+PORT=${PORT:-8765}
+DD=${DD:-$ROOT/.dd}
+SEQ=${SEQ:-main}
+
+if [[ -n "${IFACE:-}" ]]; then
+  IP=$(ipconfig getifaddr "$IFACE" 2>/dev/null || true)
+  [[ -n "$IP" ]] || { echo "no IP address on IFACE=$IFACE"; exit 1; }
+else
+  IP=$(ipconfig getifaddr en0 2>/dev/null || ipconfig getifaddr en1 2>/dev/null || true)
+  [[ -n "$IP" ]] || { echo "no IP address on en0 or en1: set IFACE=<interface> or connect this Mac to the Apple TV's network (the device fetches the clips from it)"; exit 1; }
+fi
+B="http://$IP:$PORT"
+case "$SEQ" in
+  main)
+    ARMS="P|avplayer|$B/pulse_l2.mp4,V1|vt|$B/pulse_l2.mp4,V2|vtcopy|$B/pulse_l2.mp4,T|engine|$B/p7fel_l2.mp4,N|engine|$B/p7fel_null.mp4,S|vtstrip|$B/pulse_l2.mp4,P1|avplayer|$B/pulse_l1.mp4,T1|engine|$B/p7fel_l1.mp4,P|avplayer|$B/pulse_l2.mp4"
+    LABELS=P,V1,V2,T,N,S,P1,T1,P ;;
+  el)
+    ARMS="TE|engine|$B/p7fel_el.mp4,NE|enginenofel|$B/p7fel_el.mp4,T|engine|$B/p7fel_l2.mp4"
+    LABELS=TE,NE,T ;;
+  vt)
+    ARMS="P|avplayer|$B/pulse_l2.mp4,V1|vt|$B/pulse_l2.mp4,V2|vtcopy|$B/pulse_l2.mp4,S|vtstrip|$B/pulse_l2.mp4"
+    LABELS=P,V1,V2,S ;;
+  count)
+    ARMS="T|engine|$B/p7fel_count_null.mp4,NE|enginenofel|$B/p7fel_count_null.mp4,TL|engine|$B/p7fel_count_l2.mp4,PM|avplayer|$B/count_mel.mp4"
+    LABELS=T,NE,TL,PM ;;
+  soak)
+    : "${SOAK_URL:?SEQ=soak needs SOAK_URL=<http url or a file under PULSE_OUT>}"
+    case "$SOAK_URL" in
+      http://*|https://*) U="$SOAK_URL" ;;
+      *) [[ -e "$OUT/$SOAK_URL" ]] || { echo "no such file under $OUT: $SOAK_URL"; exit 1; }
+         U="$B/${SOAK_URL#./}" ;;
+    esac
+    ARMS="SOAK|soak|$U|minutes=${SOAK_MIN:-5};seeks=${SOAK_SEEKS:-60@1800,150@600,240@3000}"
+    LABELS=SOAK ;;
+  *) echo "unknown SEQ=$SEQ (main|el|vt|count|soak)"; exit 1 ;;
+esac
+
+if [[ "${1:-}" != "--no-build" ]]; then
+  SIGN=()
+  [[ -n "${TEAM:-}" ]] && SIGN=(DEVELOPMENT_TEAM="$TEAM")
+  xcodebuild -project "$ROOT/Device/DolbyVisionPulse.xcodeproj" -scheme DolbyVisionPulse \
+    -destination 'generic/platform=tvOS' -configuration Debug -derivedDataPath "$DD" \
+    -allowProvisioningUpdates PULSE_BUNDLE_PREFIX="$PREFIX" "${SIGN[@]}" build | tail -1
+  xcrun devicectl device install app --device "$DEVICE" "$DD/Build/Products/Debug-appletvos/DolbyVisionPulseHost.app"
+fi
+
+python3 "$HERE/serve.py" $PORT "$IP" "$OUT" >/dev/null 2>&1 &
+SERVER=$!
+trap 'kill $SERVER 2>/dev/null' EXIT
+sleep 1
+
+LOG=tv_${SEQ}_$(date +%Y%m%d_%H%M%S).log
+echo "labels for analyze.py: --arms $LABELS"
+[[ "$SEQ" == soak ]] || echo "start the phone recording now; launching in 10 s"
+sleep 10
+# `process launch` hands --environment-variables to the app process (unlike a test bundle).
+xcrun devicectl device process launch --device "$DEVICE" --terminate-existing --console \
+  --environment-variables "{\"PULSE_ARMS\":\"$ARMS\"}" $BUNDLE | tee "$LOG" || echo "(launch ended non-zero: app crashed or was killed; pulling the log anyway)"
+xcrun devicectl device copy from --device "$DEVICE" --domain-type appDataContainer \
+  --domain-identifier $BUNDLE --source Library/Caches/pulse-log.txt --destination "${LOG%.log}.app.log" \
+  >/dev/null 2>&1 || echo "(could not pull the app log)"
+echo "log: $LOG (+ ${LOG%.log}.app.log)"
+if [[ "$SEQ" == soak ]]; then
+  grep -h "soak summary" "$LOG" "${LOG%.log}.app.log" 2>/dev/null | sort -u || echo "(no soak summary line found)"
+else
+  echo "cut and analyse: python3 $HERE/cut.py <recording>.MOV $LOG --slates"
+  echo "                 then the same command with --sync <video seconds>=<clock read off the slate>"
+fi
diff --git a/Probes/DolbyVisionPulse/Scripts/serve.py b/Probes/DolbyVisionPulse/Scripts/serve.py
new file mode 100755
index 000000000..3635cb7c5
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/serve.py
@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Static file server with HTTP Range support (AVPlayer / AVURLAsset require byte ranges;
+python -m http.server ignores Range and AVFoundation fails with -11850 / -12939).
+
+Usage: serve.py PORT BIND_ADDR [DIR]   (serves DIR, default ../out next to this script)
+"""
+import http.server
+import os
+import re
+import sys
+
+
+class RangeHandler(http.server.SimpleHTTPRequestHandler):
+    def send_head(self):
+        path = self.translate_path(self.path)
+        rng = self.headers.get("Range")
+        if not rng or os.path.isdir(path) or not os.path.exists(path):
+            return super().send_head()
+        m = re.match(r"bytes=(\d*)-(\d*)$", rng.strip())
+        size = os.path.getsize(path)
+        if not m:
+            self.send_error(416)
+            return None
+        a, b = m.groups()
+        if a == "" and b == "":
+            # `bytes=-` names no range at all: RFC 9110 says to ignore an unparsable Range header.
+            return super().send_head()
+        if a == "":
+            start, end = max(0, size - int(b)), size - 1
+        else:
+            start, end = int(a), (int(b) if b else size - 1)
+        end = min(end, size - 1)
+        if start > end:
+            self.send_response(416)
+            self.send_header("Content-Range", f"bytes */{size}")
+            self.end_headers()
+            return None
+        f = open(path, "rb")
+        f.seek(start)
+        self.send_response(206)
+        self.send_header("Content-Type", self.guess_type(path))
+        self.send_header("Content-Range", f"bytes {start}-{end}/{size}")
+        self.send_header("Content-Length", str(end - start + 1))
+        self.end_headers()
+        self._remaining = end - start + 1
+        return f
+
+    def end_headers(self):
+        self.send_header("Accept-Ranges", "bytes")
+        super().end_headers()
+
+    def copyfile(self, source, outputfile):
+        remaining = getattr(self, "_remaining", None)
+        if remaining is None:
+            return super().copyfile(source, outputfile)
+        while remaining > 0:
+            chunk = source.read(min(65536, remaining))
+            if not chunk:
+                break
+            outputfile.write(chunk)
+            remaining -= len(chunk)
+        self._remaining = None
+
+    def log_message(self, *args):
+        pass
+
+
+if __name__ == "__main__":
+    port, bind = int(sys.argv[1]), sys.argv[2]
+    root = sys.argv[3] if len(sys.argv) > 3 else os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "out")
+    os.chdir(root)
+    http.server.ThreadingHTTPServer((bind, port), RangeHandler).serve_forever()
diff --git a/Probes/DolbyVisionPulse/Scripts/sim_recording.py b/Probes/DolbyVisionPulse/Scripts/sim_recording.py
new file mode 100755
index 000000000..22c85e286
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Scripts/sim_recording.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Fake phone recording for testing analyze.py: the l2 clip filmed at 30 fps with perspective,
+vignetting and noise. Runs are given as 'pulse' (B phases darken, 3-frame latency) or 'steady'.
+
+Needs pulse_l2.mp4 from build.sh (in $PULSE_OUT, default ../out).
+
+Usage: sim_recording.py out.mp4 pulse,steady
+"""
+import os
+import subprocess
+import sys
+
+import numpy as np
+
+import gen_pulse as G
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+OUT = os.environ.get("PULSE_OUT", os.path.join(HERE, "..", "out"))
+OW, OH = 1280, 720
+CAM_FPS = 30.0
+
+
+def clip_luma():
+    cmd = ["ffmpeg", "-v", "error", "-i", os.path.join(OUT, "pulse_l2.mp4"), "-vf", "scale=960:540", "-pix_fmt", "gray",
+           "-f", "rawvideo", "-"]
+    raw = subprocess.check_output(cmd)
+    return np.frombuffer(raw, np.uint8).reshape(-1, 540, 960).astype(np.float32) / 255.0
+
+
+def warp_maps():
+    # Camera sees the screen slightly rotated and keystoned.
+    src = np.array([[0, 0], [960, 0], [0, 540], [960, 540]], float)
+    dst = np.array([[150, 110], [1150, 80], [170, 650], [1130, 690]], float)
+    A = []
+    for (x, y), (u, v) in zip(dst, src):
+        A.append([x, y, 1, 0, 0, 0, -u * x, -u * y, -u])
+        A.append([0, 0, 0, x, y, 1, -v * x, -v * y, -v])
+    Hm = np.linalg.svd(np.array(A))[2][-1].reshape(3, 3)
+    gx, gy = np.meshgrid(np.arange(OW), np.arange(OH))
+    P = Hm @ np.stack([gx.ravel(), gy.ravel(), np.ones(gx.size)])
+    u = (P[0] / P[2]).reshape(OH, OW)
+    v = (P[1] / P[2]).reshape(OH, OW)
+    inside = (u >= 0) & (u < 959) & (v >= 0) & (v < 539)
+    return np.clip(u, 0, 959).astype(int), np.clip(v, 0, 539).astype(int), inside
+
+
+def main():
+    out, runs = sys.argv[1], sys.argv[2].split(",")
+    clip = clip_luma()
+    u, v, inside = warp_maps()
+    vign = 1 - 0.25 * (((np.arange(OW) - OW / 2) / OW) ** 2 + ((np.arange(OH)[:, None] - OH / 2) / OH) ** 2)
+    rng = np.random.default_rng(1)
+    enc = subprocess.Popen(["ffmpeg", "-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "gray", "-s", f"{OW}x{OH}",
+                            "-r", "30", "-i", "-", "-c:v", "libx264", "-crf", "18", "-pix_fmt", "yuv420p", out],
+                           stdin=subprocess.PIPE)
+
+    def emit(img):
+        img = img * vign + rng.normal(0, 0.01, img.shape) + 0.02
+        enc.stdin.write((np.clip(img, 0, 1) * 255).astype(np.uint8).tobytes())
+
+    for kind in runs:
+        for _ in range(60):  # 2 s of UI slate
+            emit(np.full((OH, OW), 0.3))
+        clip_fps = G.FPS_NUM / G.FPS_DEN
+        for k in range(int(G.N_FRAMES / clip_fps * CAM_FPS)):
+            i = min(int(k / CAM_FPS * clip_fps), G.N_FRAMES - 1)
+            frame = clip[i]
+            if kind == "pulse" and G.phase_of(max(i - 3, 0)) == "B":
+                frame = 0.85 * frame ** 1.2
+            img = np.where(inside, frame[v, u], 0.0)
+            emit(img)
+    enc.stdin.close()
+    enc.wait()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index c17f6a2a1..43647cd72 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -212,8 +212,7 @@ switching into a Dolby Vision mode, is answered by a pulse test that anyone with
 television and a phone can repeat: clips whose pixels are constant while only the RPU (or the
 enhancement-layer residual) switches, played through AVPlayer, VideoToolbox and the FEL route, and
 filmed. Clip generator, device host, harness scripts and analysis are in
-[`Probes/DolbyVisionPulse`](../Probes/DolbyVisionPulse/README.md), which arrives with the pulse-probe PR
-that follows this one; the link resolves once it has landed.
+[`Probes/DolbyVisionPulse`](../Probes/DolbyVisionPulse/README.md).
 
 ### 4.6 Caveat on the numbers
 

From 8c954fbc37d6ba35801b6b8533fe829d44d73c48 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 7 Oct 2026 10:39:30 +0100
Subject: [PATCH 017/132] feat(aetherctl): FEL playback, survey and diagnostics
 tooling

The command-line and probe side of the dual-layer Dolby Vision work. Nothing
here is host API: the probes are @_spi(Diagnostics), outside the SemVer
contract, and the host surface of the FEL route stays
LoadOptions.preferDualLayerDolbyVision alone.

- aetherctl play: --cycle-el flips the residual on a timer over a visible
  surface, --no-fel plays the same file on the native route, --surface
  presents it, and --dv-pin (DEBUG builds only) arms the consumption pin test.
- aetherctl dvsurvey: reports a title's L1 / L2 display-metadata
  distribution straight from its RPUs (DoviRpuSurvey: no decode, no GPU).
- aetherctl feltest: decodes real Profile 7 files through the FEL path and
  checks the result (AetherEngine+FelProbe: felDecodeProbe, felResidualEnabled).
- DoviDisplayMetadataDebug and AetherEngine+DolbyVisionTest: a DEBUG-only
  hook that substitutes a captured RPU on a duty cycle, the on-device
  consumption test. It compiles out of Release; DoviDisplayMetadata.attach
  gains one #if DEBUG call and is otherwise unchanged.
- docs/cli.md, the docs/api.md "public but not host API" bullet, and the
  docs/architecture.md entries for these files.

No behaviour change for a host: the SPI is unreachable without
@_spi(Diagnostics) and the DEBUG hook is off unless armed. Not in this PR:
anything on the route or the decoder.

Tests: DoviRpuSurveyResultTests (the survey's pure summaries), DoviPinTestTests
(the pin-spec grammar), and the DEBUG pin hook's disarm test in
DualLayerVideoDecoderTests.
---
 CHANGELOG.md                                  |   1 +
 .../Video/AetherEngine+DolbyVisionTest.swift  |  45 +++
 .../Video/AetherEngine+FelProbe.swift         | 249 ++++++++++++++
 .../Video/DoviDisplayMetadata.swift           |   5 +
 .../Video/DoviDisplayMetadataDebug.swift      | 304 ++++++++++++++++++
 .../AetherEngine/Video/DoviRpuSurvey.swift    | 226 +++++++++++++
 Sources/aetherctl/DvSurvey.swift              | 124 +++++++
 Sources/aetherctl/FelTest.swift               |  68 ++++
 Sources/aetherctl/PlaybackCmd.swift           |  56 +++-
 Sources/aetherctl/main.swift                  | 116 ++++++-
 .../AetherEngineTests/DoviPinTestTests.swift  |  86 +++++
 .../DoviRpuSurveyResultTests.swift            | 100 ++++++
 docs/api.md                                   |   3 +-
 docs/architecture.md                          |   4 +
 docs/cli.md                                   |  27 +-
 docs/dolby-vision-fel.md                      |  10 +-
 16 files changed, 1408 insertions(+), 16 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
 create mode 100644 Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
 create mode 100644 Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
 create mode 100644 Sources/AetherEngine/Video/DoviRpuSurvey.swift
 create mode 100644 Sources/aetherctl/DvSurvey.swift
 create mode 100644 Sources/aetherctl/FelTest.swift
 create mode 100644 Tests/AetherEngineTests/DoviPinTestTests.swift
 create mode 100644 Tests/AetherEngineTests/DoviRpuSurveyResultTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f767bc611..763d1a57c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ the public-API contract.
 
 - **Dolby Vision Profile 7 FEL plays as Dolby Vision on the software path.** Opt-in: with `LoadOptions.preferDualLayerDolbyVision` set to `true` (default `false`) and `dolbyVisionHandling` `.automatic`, `SoftwarePlaybackHost` routes a Profile 7 file whose enhancement layer is FEL through `DualLayerVideoDecoder`: the base layer and the enhancement layer (typically 4K and 1080p) decode on VideoToolbox, `DoviFelComposer` rebuilds the 12-bit picture on Metal, and each frame carries its RPU converted to Profile 8.1 (`DolbyVisionRPUData`, `DolbyCompatibilityID`, the latter a `CFString` `"1"`: tvOS parses it with `CFStringGetIntValue` and a `CFNumber` aborts the render server). A MEL enhancement layer keeps the native route. An `hev1` source whose `hvcC` carries no VPS / SPS / PPS (the usual Dolby Vision MP4 recipes) is classified from the parameter sets at the head of the stream, the rebuild the native path already does for its init.mp4 (#19). What the route gives up against the native one (system Picture in Picture, the I-frame playlist's scrub thumbnails, WebVTT renditions, AirPlay picture) is listed in the document. Details in [docs/dolby-vision-fel.md](docs/dolby-vision-fel.md).
 - **The Profile 7 dual-layer route is FEL only and capability gated, and says why.** `DualLayerRouteDecision` adds a real-time budget to the route: the base and enhancement layers together may need at most UHD 3840x2160 at 30 fps plus a 1920x1080 enhancement layer at 30 fps (a 24p UHD master uses 80%), otherwise the file keeps the native route, as MEL does and as does a box without hardware HEVC decode (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not). Every Profile 7 load logs one `DV P7 dual-layer route: taken (...)` or `not taken (<reason>)` line; the line is new, and with the preference off it is the only change.
+- **`aetherctl play --fel`, `--surface`, `--cycle-el`; `aetherctl dvsurvey`, `feltest`.** Flip the residual on a timer over a visible surface, report a title's L1 display-metadata distribution, and check the FEL decode against real files. The probes behind them are `@_spi(Diagnostics)`, outside the SemVer contract. `play` runs the dual-layer route only with `--fel` (off by default, like the engine option); `--no-fel` is accepted and does nothing.
 - **`AETHER_FEL_MEASURE` reports the signed FEL-minus-MEL mean per plane and luma band.** The diagnostic composes every Nth frame a second time with the residual off and compares the two; the signed mean says whether the residual brightens or darkens, which the absolute difference could not. It runs one sample at a time and skips a frame that arrives while one is in flight. Off by default; it is an environment-variable diagnostic, not API.
 - **The dual-layer decoder pairs the two layers by picture order.** `DualLayerPictureAlignment` derives each layer's display slot from its POC (`HEVCPictureOrderCount`, no decoding) and stamps each enhancement-layer packet with the time of the base-layer picture in the same slot, so a stream whose enhancement layer is coded with B-frames over a base layer without them pairs the right pictures. A stream whose layers share one GOP keeps every packet's own time. After a seek a layer pairs by access unit until its next sequence-opening IRAP.
 - **`Probes/DolbyVisionPulse`, a reproducible Dolby Vision pulse test.** Clips whose pixels are constant while only the RPU (or, for the enhancement-layer clip, only the residual) switches every 72 frames, counter clips whose base and enhancement layers each carry their own frame number (so a dropped or mispaired residual shows on screen), a tvOS host app that plays them through AVPlayer, VideoToolbox, and the FEL route, and scripts that build the clips, cut a phone recording per arm and read back whether the panel followed the metadata. It is the measurement behind [the FEL consumption evidence](docs/dolby-vision-fel.md#45-consumption-test-assets); the host builds in CI, the rest needs a television and a phone.
diff --git a/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift b/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
new file mode 100644
index 000000000..686c37f82
--- /dev/null
+++ b/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
@@ -0,0 +1,45 @@
+#if DEBUG
+import Foundation
+
+/// Diagnostic controls (SPI, not host API) for the on-device Dolby Vision consumption test.
+///
+/// The pinned-RPU test holds the decoded pixels constant and changes only the metadata,
+/// so a pulse on the panel is evidence regardless of where the composition happens.
+///
+/// Debug-only.
+extension AetherEngine {
+
+    /// Arms (or disarms) the pinned-RPU test.
+    ///
+    /// Drive it from a debug menu; `aetherctl play --fel --dv-pin` takes the same spec on the Mac.
+    /// `aetherctl dvsurvey` prints a spec tuned to the title you intend to play.
+    ///
+    /// - Parameter spec: e.g. `"darkest:240,period:2"`, or nil to disarm.
+    /// - Returns: false if `spec` carried no recognisable capture rule, in which case nothing was
+    ///   armed — a typo leaves playback alone rather than pinning something arbitrary.
+    @discardableResult
+    @_spi(Diagnostics)
+    public static func armDolbyVisionPinTest(_ spec: String?) -> Bool {
+        guard let spec else {
+            DoviDisplayMetadataDebug.configure(nil)
+            return true
+        }
+        guard let config = DoviDisplayMetadataDebug.parse(spec: spec) else {
+            EngineLog.emit("dv-pin: could not parse '\(spec)' — expected something like "
+                           + "'darkest:240,period:2' or 'avgpq<=1200,period:2'. Not armed.",
+                           category: .engine)
+            return false
+        }
+        DoviDisplayMetadataDebug.configure(config)
+        return true
+    }
+
+    /// True once the pin test has captured a frame and is substituting metadata.
+    @_spi(Diagnostics)
+    public static var dolbyVisionPinIsActive: Bool { DoviDisplayMetadataDebug.isPinned }
+
+    /// True while the pin test is armed (scanning or actively substituting).
+    @_spi(Diagnostics)
+    public static var dolbyVisionPinIsArmed: Bool { DoviDisplayMetadataDebug.isArmed }
+}
+#endif
diff --git a/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift b/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
new file mode 100644
index 000000000..d39426662
--- /dev/null
+++ b/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
@@ -0,0 +1,249 @@
+import Foundation
+import CoreMedia
+import CoreVideo
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+
+/// Diagnostic probe result for Dolby Vision Profile 7 FEL dual-layer Metal reconstruction.
+@_spi(Diagnostics)
+public struct FelProbeResult: Sendable {
+    public let packetsProcessed: Int
+    /// Frames delivered, composed or not: a frame that bypassed the composer comes out as its base layer.
+    public let framesReconstructed: Int
+    /// Frames the composer actually reconstructed. Zero means the stream never composed (a bypass on
+    /// every frame, a failed shader, a stream that is not FEL), whatever `framesReconstructed` says.
+    public let composedFrames: Int
+    public let width: Int
+    public let height: Int
+    public let pixelFormat: String
+    public let isFEL: Bool
+    public let durationSeconds: Double
+    public let fps: Double
+    public let avgLuma: Double
+    public let avgCb: Double
+    public let avgCr: Double
+    public let stdDevCb: Double
+    public let stdDevCr: Double
+    public let isChromaValid: Bool
+    /// Frames that came out carrying a `DolbyVisionRPUData` attachment (per-frame L1/L2 display
+    /// metadata). Should equal `framesReconstructed` on a Profile 7 source.
+    public let framesWithDVMetadata: Int
+    /// Distinct RPU payloads seen. Dolby Vision L1 is usually per-frame, so a healthy stream produces
+    /// a value close to `framesWithDVMetadata`; a single distinct payload means static metadata,
+    /// which a static-metadata clip legitimately has, or something upstream collapsed it.
+    public let distinctDVPayloads: Int
+    /// Byte length of the first RPU payload attached, for eyeballing against the bitstream.
+    public let firstDVPayloadBytes: Int
+    /// Leading bytes of the first RPU payload, hex. A well-formed payload starts `19` — the
+    /// Dolby Vision RPU prefix — because the `unspec62` NAL's 2-byte header has been stripped.
+    public let firstDVPayloadPrefix: String
+}
+
+extension AetherEngine {
+
+    /// Diagnostic probe that decodes both the base layer and the enhancement layer (typically 1080p) in hardware,
+    /// evaluates inverse NLQ and reshaping curves on Apple GPU via Metal, and produces 10-bit P010 frames.
+    @_spi(Diagnostics)
+    public nonisolated static func felDecodeProbe(
+        url: URL,
+        maxPackets: Int = 100,
+        options: LoadOptions = .init()
+    ) throws -> FelProbeResult {
+        let demuxer = Demuxer()
+        try demuxer.open(url: url, extraHeaders: options.httpHeaders)
+        defer { demuxer.close() }
+
+        let videoIdx = demuxer.videoStreamIndex
+        guard videoIdx >= 0, demuxer.stream(at: videoIdx) != nil else {
+            throw AetherEngineError.noVideoStream
+        }
+        // An `hev1` file with in-band parameter sets has an empty hvcC; the load path completes it
+        // from the head of the stream before routing, and the probe must open the decoders on the
+        // same record or it reports a failure the real route does not have. Seeks back to 0.
+        VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: demuxer, streamIndex: videoIdx)
+        guard let stream = demuxer.stream(at: videoIdx) else {
+            throw AetherEngineError.noVideoStream
+        }
+
+        final class Accum: @unchecked Sendable {
+            var framesReconstructed = 0
+            var width = 0
+            var height = 0
+            var pixelFormat = ""
+            var isFEL = false
+            var sumLuma: Double = 0
+            var sumCb: Double = 0
+            var sumCr: Double = 0
+            var sumSqCb: Double = 0
+            var sumSqCr: Double = 0
+            var pixelSampleCount: Int = 0
+            var framesWithDVMetadata = 0
+            var dvPayloads = Set<Data>()
+            var firstDVPayloadBytes = 0
+            var firstDVPayloadPrefix = ""
+            let lock = NSLock()
+        }
+
+        let accum = Accum()
+        let startTime = CFAbsoluteTimeGetCurrent()
+
+        let dualDecoder = DualLayerVideoDecoder()
+        try dualDecoder.open(stream: stream) { pixelBuffer, pts, _ in
+            accum.lock.lock()
+            defer { accum.lock.unlock() }
+            if accum.framesReconstructed == 0 {
+                accum.width = CVPixelBufferGetWidth(pixelBuffer)
+                accum.height = CVPixelBufferGetHeight(pixelBuffer)
+                let code = CVPixelBufferGetPixelFormatType(pixelBuffer)
+                let b0 = Character(UnicodeScalar((code >> 24) & 0xff) ?? " ")
+                let b1 = Character(UnicodeScalar((code >> 16) & 0xff) ?? " ")
+                let b2 = Character(UnicodeScalar((code >> 8) & 0xff) ?? " ")
+                let b3 = Character(UnicodeScalar(code & 0xff) ?? " ")
+                accum.pixelFormat = "\(b0)\(b1)\(b2)\(b3)"
+            }
+
+            // Per-frame Dolby Vision display metadata: check the attachment actually rode out
+            // with the frame rather than trusting that it was set.
+            if let rpu = CVBufferCopyAttachment(pixelBuffer, DoviDisplayMetadata.rpuDataKey as CFString, nil) as? Data {
+                accum.framesWithDVMetadata += 1
+                accum.dvPayloads.insert(rpu)
+                if accum.firstDVPayloadBytes == 0 {
+                    accum.firstDVPayloadBytes = rpu.count
+                    accum.firstDVPayloadPrefix = rpu.prefix(12).map { String(format: "%02x", $0) }.joined()
+                }
+            }
+
+            // Sample pixels across center region to compute pixel stats
+            CVPixelBufferLockBaseAddress(pixelBuffer, .readOnly)
+            let w = CVPixelBufferGetWidth(pixelBuffer)
+            let h = CVPixelBufferGetHeight(pixelBuffer)
+            if let yPlane = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0),
+               let uvPlane = CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 1) {
+                let y16 = yPlane.assumingMemoryBound(to: UInt16.self)
+                let uv16 = uvPlane.assumingMemoryBound(to: UInt16.self)
+                let yStride = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0) / 2
+                let uvStride = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 1) / 2
+
+                // Sample 512 points across active center 50%
+                let stepX = max(1, (w / 2) / 32)
+                let stepY = max(1, (h / 2) / 16)
+                let startX = (w / 4)
+                let startY = (h / 4)
+                for sy in stride(from: startY, to: startY + h / 2, by: stepY) {
+                    for sx in stride(from: startX, to: startX + w / 2, by: stepX) {
+                        let lumaVal = Double(y16[sy * yStride + sx] >> 6)
+                        let cbVal = Double(uv16[(sy / 2) * uvStride + (sx / 2) * 2] >> 6)
+                        let crVal = Double(uv16[(sy / 2) * uvStride + (sx / 2) * 2 + 1] >> 6)
+
+                        accum.sumLuma += lumaVal
+                        accum.sumCb += cbVal
+                        accum.sumCr += crVal
+                        accum.sumSqCb += cbVal * cbVal
+                        accum.sumSqCr += crVal * crVal
+                        accum.pixelSampleCount += 1
+                    }
+                }
+            }
+            CVPixelBufferUnlockBaseAddress(pixelBuffer, .readOnly)
+
+            accum.framesReconstructed += 1
+        }
+        defer { dualDecoder.close() }
+
+        var packetsProcessed = 0
+
+        while packetsProcessed < maxPackets {
+            let maybePacket: UnsafeMutablePointer<AVPacket>?
+            do {
+                maybePacket = try demuxer.readPacket()
+            } catch {
+                break
+            }
+            guard let packet = maybePacket else { break }
+
+            if packet.pointee.stream_index == videoIdx {
+                packetsProcessed += 1
+                dualDecoder.decode(packet: packet)
+            }
+
+            av_packet_unref(packet)
+            var opt: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&opt)
+        }
+
+        // Not drained: `flush()` retires the frames still in flight rather than delivering them, so the
+        // last few packets' frames are not counted. The decoder has no drain-and-deliver call, and the
+        // verdicts are over a hundred frames, so the tail is left as it is.
+        dualDecoder.flush()
+
+        // A frame already in flight can still reach the callback on the decoder's delivery queue
+        // while this thread reads the totals, so every read goes through one snapshot under the lock.
+        accum.lock.lock()
+        let framesReconstructed = accum.framesReconstructed
+        let width = accum.width
+        let height = accum.height
+        let pixelFormat = accum.pixelFormat
+        let sumLuma = accum.sumLuma
+        let sumCb = accum.sumCb
+        let sumCr = accum.sumCr
+        let sumSqCb = accum.sumSqCb
+        let sumSqCr = accum.sumSqCr
+        let pixelSampleCount = accum.pixelSampleCount
+        let framesWithDVMetadata = accum.framesWithDVMetadata
+        let distinctDVPayloads = accum.dvPayloads.count
+        let firstDVPayloadBytes = accum.firstDVPayloadBytes
+        let firstDVPayloadPrefix = accum.firstDVPayloadPrefix
+        accum.lock.unlock()
+
+        let elapsed = max(CFAbsoluteTimeGetCurrent() - startTime, 0.001)
+        let fps = Double(framesReconstructed) / elapsed
+
+        let n = Double(max(1, pixelSampleCount))
+        let meanLuma = sumLuma / n
+        let meanCb = sumCb / n
+        let meanCr = sumCr / n
+        let varCb = max(0, (sumSqCb / n) - (meanCb * meanCb))
+        let varCr = max(0, (sumSqCr / n) - (meanCr * meanCr))
+        let stdDevCb = sqrt(varCb)
+        let stdDevCr = sqrt(varCr)
+
+        // Chroma is invalid if collapsed to flat 64 (stdDev < 1.0 and mean ~64)
+        let isChromaFlat64 = (abs(meanCb - 64.0) < 1.0 && stdDevCb < 1.0)
+        let isChromaValid = !isChromaFlat64 && (meanCb > 100.0)
+
+        return FelProbeResult(
+            packetsProcessed: packetsProcessed,
+            framesReconstructed: framesReconstructed,
+            composedFrames: dualDecoder.composedFrameCount,
+            width: width,
+            height: height,
+            pixelFormat: pixelFormat,
+            isFEL: dualDecoder.streamClassification == .fel,
+            durationSeconds: elapsed,
+            fps: fps,
+            avgLuma: meanLuma,
+            avgCb: meanCb,
+            avgCr: meanCr,
+            stdDevCb: stdDevCb,
+            stdDevCr: stdDevCr,
+            isChromaValid: isChromaValid,
+            framesWithDVMetadata: framesWithDVMetadata,
+            distinctDVPayloads: distinctDVPayloads,
+            firstDVPayloadBytes: firstDVPayloadBytes,
+            firstDVPayloadPrefix: firstDVPayloadPrefix
+        )
+    }
+
+}
+
+extension AetherEngine {
+    /// Off composes every Profile 7 FEL frame without its residual, which is what a MEL stream
+    /// decodes to; on is the full FEL result. For A/B viewing (`aetherctl play --cycle-el`): it
+    /// takes effect from the next composed frame and applies to every session in the process.
+    @_spi(Diagnostics)
+    public nonisolated static var felResidualEnabled: Bool {
+        get { DoviFelComposer.residualEnabled }
+        set { DoviFelComposer.residualEnabled = newValue }
+    }
+}
diff --git a/Sources/AetherEngine/Video/DoviDisplayMetadata.swift b/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
index 5443014b1..546bab9da 100644
--- a/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
+++ b/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
@@ -98,6 +98,11 @@ enum DoviDisplayMetadata {
     /// - Parameter nal: the Profile 8.1 `unspec62` NAL *including* its 2-byte header, as
     ///   returned by `dovi_write_unspec62_nalu`. The header is stripped here.
     static func attach(rpuNAL nal: [UInt8]?, to buffer: CVPixelBuffer) {
+        #if DEBUG
+        // Compiles out of Release entirely. Substitutes a pinned RPU when the consumption test
+        // is armed; a no-op returning `nal` unchanged otherwise. See `DoviDisplayMetadataDebug`.
+        let nal = DoviDisplayMetadataDebug.substitute(nal)
+        #endif
         guard let payload = payload(fromNAL: nal) else {
             CVBufferRemoveAttachment(buffer, rpuDataKey as CFString)
             CVBufferRemoveAttachment(buffer, compatibilityIDKey as CFString)
diff --git a/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift b/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
new file mode 100644
index 000000000..477517397
--- /dev/null
+++ b/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
@@ -0,0 +1,304 @@
+#if DEBUG
+import Foundation
+import Dovi
+
+/// Arms the on-device Dolby Vision consumption test: pins the attached RPU to one captured frame's
+/// metadata, optionally toggling back to the live RPU on a fixed period.
+///
+/// ## What the test proves
+/// Everything up to the `CVPixelBuffer` is verified on the host — the attachment is set, it carries
+/// the right bytes, it propagates to the `IOSurface`, it survives into the `CMSampleBuffer`. What no
+/// host test can reach is the last link: whether the tvOS compositor *reads* it off a client-supplied
+/// buffer on the `AVSampleBufferDisplayLayer` path (see `dolby-vision-fel.md §4.1`).
+///
+/// So: hold the pixels constant and change only the metadata. This substitution happens after the GPU
+/// composer has already run and *only* touches the attachment — `rpuCache`, the reshaping
+/// coefficients, the composed frame itself are all untouched, so the decoded pixels stay bit-identical
+/// whichever phase the toggle is in. Any brightness or saturation shift visible on the panel therefore
+/// came from the metadata and nothing else. Pinned to a frame with extreme L1 statistics — the darkest
+/// or brightest frame in the title, which `aetherctl dvsurvey` finds — the TV's display mapping is
+/// told the wrong thing about the scene and should visibly misjudge it.
+///
+/// A steady, in-sync 2-second pulse on the panel while the pixels are provably unchanged is the
+/// consumption proof. A flat picture across both phases means the attachment is being ignored.
+///
+/// ## Arming it
+/// `AetherEngine.armDolbyVisionPinTest(_:)` from the host app (a debug menu), or `aetherctl play
+/// --dv-pin`. Grammar is comma-separated `key:value`, in any order:
+///
+/// - `darkest:N` / `brightest:N` — watch the first `N` frames, keep the one with the lowest
+///   (`darkest`) or highest (`brightest`) L1 `avg_pq`, pin to it. Self-calibrating and robust to
+///   starting playback anywhere in the title.
+/// - `avgpq<=V` / `avgpq>=V` / `maxpq<=V` / `maxpq>=V` — pin to the first frame whose L1 `avg_pq`
+///   or `max_pq` crosses `V` (a 12-bit PQ code). Use when `dvsurvey` has already told you the
+///   title's range and you want a specific frame.
+/// - `period:S` — seconds per phase, alternating pinned/live. `period:0` pins permanently. Defaults
+///   to 2. A positive value below `minimumPeriod` (a pulse faster than a panel can show) is raised
+///   to it, and a value that is not a finite number is ignored.
+///
+/// `darkest:240,period:2` is the usual starting point: scan ten seconds, pin the
+/// darkest frame found, pulse every two seconds.
+///
+/// Never reachable in Release — the whole file is `#if DEBUG`, and a private-framework-adjacent
+/// diagnostic that rewrites what the display sees has no business in a shipping build.
+///
+/// The state lives in a `DoviPinTest` instance. The engine uses one process-wide instance
+/// (`DoviDisplayMetadataDebug.shared`); a test makes its own with a local log sink, so it neither
+/// arms the shared one (which every decoder in the process feeds) nor needs `EngineLog.handler`.
+final class DoviPinTest: @unchecked Sendable {
+
+    /// Log sink. The default writes to `EngineLog`; it is only ever called with the lock released.
+    private let emit: @Sendable (String) -> Void
+
+    init(emit: @escaping @Sendable (String) -> Void = { EngineLog.emit($0, category: .engine) }) {
+        self.emit = emit
+    }
+
+    /// Shortest phase `period:` may name. Below this the toggle is not visible on a panel anyway, and
+    /// a tiny value would only make `elapsed / period` overflow an `Int`.
+    static let minimumPeriod: TimeInterval = 0.1
+    /// Longest phase `period:` may name (an hour); beyond it the pulse would never be seen.
+    static let maximumPeriod: TimeInterval = 3600
+
+    // MARK: - Configuration
+
+    enum Capture: Equatable {
+        /// Scan `frames` attachments, keep the one with the lowest L1 `avg_pq`.
+        case darkest(frames: Int)
+        /// Scan `frames` attachments, keep the one with the highest L1 `avg_pq`.
+        case brightest(frames: Int)
+        /// Keep the first frame whose L1 field is at or below this 12-bit PQ code.
+        case atMost(Field, UInt16)
+        /// Keep the first frame whose L1 field is at or above this 12-bit PQ code.
+        case atLeast(Field, UInt16)
+
+        /// Which L1 statistic a threshold rule tests. `avg_pq` anchors the display-mapping curve's
+        /// mid-tone and usually has the widest range across a title, so it is the stronger lever;
+        /// `max_pq` drives highlight roll-off.
+        enum Field: String, Equatable {
+            case avgPQ = "avgpq"
+            case maxPQ = "maxpq"
+        }
+    }
+
+    struct Config: Equatable {
+        var capture: Capture
+        /// Seconds per phase. Zero pins permanently once captured.
+        var period: TimeInterval = 2
+    }
+
+    /// Arms or disarms the test. Passing `nil` disarms and drops any captured pin.
+    func configure(_ config: Config?) {
+        lock.lock()
+        state = config.map { State(config: $0) }
+        lock.unlock()
+        if let config {
+            emit("dv-pin: armed \(config.capture), period \(config.period)s")
+        } else {
+            emit("dv-pin: disarmed")
+        }
+    }
+
+    /// True once a pin has been captured and substitution is live.
+    var isPinned: Bool {
+        lock.lock(); defer { lock.unlock() }
+        return state?.pinned != nil
+    }
+
+    /// True while the pin test is armed (scanning or actively substituting).
+    var isArmed: Bool {
+        lock.lock(); defer { lock.unlock() }
+        return state != nil
+    }
+
+    // MARK: - The substitution
+
+    /// Returns the RPU NAL that should actually be attached to this frame.
+    ///
+    /// Called on the decode thread for every emitted frame. Returns `nal` unchanged — the only
+    /// behaviour that exists in an unarmed build — until a pin has been captured and the toggle is in
+    /// its pinned phase.
+    func substitute(_ nal: [UInt8]?) -> [UInt8]? {
+        // Lines are collected under the lock and emitted after it: a log handler is arbitrary host
+        // code, and `EngineLog.emit` must not run while this lock is held.
+        var logs: [String] = []
+        lock.lock()
+        let result = substituteLocked(nal, logs: &logs)
+        lock.unlock()
+        for line in logs { emit(line) }
+        return result
+    }
+
+    private func substituteLocked(_ nal: [UInt8]?, logs: inout [String]) -> [UInt8]? {
+        guard var st = state else { return nal }
+
+        if st.pinned == nil {
+            if let nal { considerForCapture(nal, into: &st) }
+            logs.append(contentsOf: st.pendingLogs)
+            st.pendingLogs.removeAll()
+            if st.isDisarmed {
+                state = nil
+            } else {
+                state = st
+            }
+            return nal
+        }
+        defer { state = st }
+        guard let pinned = st.pinned else { return nal }
+
+        // A frame with no RPU stays without one. Substituting into a gap would attach metadata to a
+        // frame the stream says has none, which is a different bug's symptom, not this test's signal.
+        guard nal != nil else { return nil }
+
+        let usePin: Bool
+        if st.config.period <= 0 {
+            usePin = true
+        } else {
+            let elapsed = CFAbsoluteTimeGetCurrent() - st.armedAt
+            // `period` is clamped to `minimumPeriod` or more when parsed; a `Config` built by hand
+            // gets the same floor here, so the division cannot overflow an `Int`.
+            let phases = elapsed / max(st.config.period, Self.minimumPeriod)
+            usePin = phases.isFinite && Int(phases) % 2 == 1
+        }
+        if usePin != st.lastPhaseWasPinned {
+            st.lastPhaseWasPinned = usePin
+            let pinDesc = st.pinnedL1.map { "frame \(st.pinnedSourceIndex), L1 max \($0.max) avg \($0.avg)" } ?? "frame \(st.pinnedSourceIndex)"
+            logs.append("dv-pin: phase -> \(usePin ? "PINNED (\(pinDesc))" : "LIVE")")
+        }
+        return usePin ? pinned : nal
+    }
+
+    // MARK: - Capture
+
+    private func considerForCapture(_ nal: [UInt8], into st: inout State) {
+        st.scanned += 1
+        guard let l1 = Self.parseL1(ofNAL: nal) else {
+            st.unparseableCount += 1
+            switch st.config.capture {
+            case .darkest(let frames), .brightest(let frames):
+                if st.scanned >= frames { commit(&st) }
+            case .atMost, .atLeast:
+                if st.unparseableCount >= 300 && st.bestL1 == nil { commit(&st) }
+            }
+            return
+        }
+
+        func keep() { st.best = nal; st.bestL1 = l1; st.bestIndex = st.scanned - 1 }
+        func field(_ f: Capture.Field) -> UInt16 { f == .avgPQ ? l1.avg : l1.max }
+
+        switch st.config.capture {
+        case .darkest(let frames):
+            if st.bestL1 == nil || l1.avg < st.bestL1!.avg { keep() }
+            if st.scanned >= frames { commit(&st) }
+        case .brightest(let frames):
+            if st.bestL1 == nil || l1.avg > st.bestL1!.avg { keep() }
+            if st.scanned >= frames { commit(&st) }
+        case .atMost(let f, let v):
+            if field(f) <= v { keep(); commit(&st) }
+        case .atLeast(let f, let v):
+            if field(f) >= v { keep(); commit(&st) }
+        }
+    }
+
+    private func commit(_ st: inout State) {
+        guard let best = st.best, let l1 = st.bestL1 else {
+            st.pendingLogs.append("dv-pin: scan of \(st.scanned) frame(s) (\(st.unparseableCount) unparseable) found no parseable L1; test not armed")
+            st.isDisarmed = true
+            return
+        }
+        st.pinned = best
+        st.pinnedL1 = l1
+        st.pinnedSourceIndex = st.bestIndex
+        st.armedAt = CFAbsoluteTimeGetCurrent()
+        st.pendingLogs.append(String(format: "dv-pin: captured frame %d after %d scanned — L1 min %d max %d avg %d (%.1f / %.1f nits max/avg), %d byte NAL; toggling every %.1fs",
+                              st.bestIndex, st.scanned, Int(l1.min), Int(l1.max), Int(l1.avg),
+                              DoviRpuSurvey.pqCodeToNits(l1.max), DoviRpuSurvey.pqCodeToNits(l1.avg),
+                              best.count, st.config.period))
+    }
+
+    struct L1: Equatable { let min: UInt16; let max: UInt16; let avg: UInt16 }
+
+    /// L1 statistics out of an `unspec62` NAL. Only called during the capture scan, which ends
+    /// after at most `frames` parses — the steady state does no libdovi work per frame.
+    private static func parseL1(ofNAL nal: [UInt8]) -> L1? {
+        nal.withUnsafeBufferPointer { buf -> L1? in
+            guard let base = buf.baseAddress else { return nil }
+            guard let rpu = DoviRpuGuard.parse(base, buf.count) else { return nil }
+            defer { dovi_rpu_free(rpu) }
+            guard let dm = dovi_rpu_get_vdr_dm_data(rpu) else { return nil }
+            defer { dovi_rpu_free_vdr_dm_data(dm) }
+            guard let l1 = dm.pointee.dm_data.level1 else { return nil }
+            return L1(min: l1.pointee.min_pq, max: l1.pointee.max_pq, avg: l1.pointee.avg_pq)
+        }
+    }
+
+    // MARK: - State
+
+    private struct State {
+        let config: Config
+        var scanned = 0
+        var unparseableCount = 0
+        var isDisarmed = false
+        var best: [UInt8]?
+        var bestL1: L1?
+        var bestIndex = 0
+        var pinned: [UInt8]?
+        var pinnedL1: L1?
+        var pinnedSourceIndex = 0
+        var armedAt: CFAbsoluteTime = 0
+        var lastPhaseWasPinned = false
+        /// Lines to emit once the lock is released.
+        var pendingLogs: [String] = []
+    }
+
+    private let lock = NSLock()
+    private var state: State?
+
+    // MARK: - Spec
+
+    /// Parses the pin-test grammar above. Returns nil if no capture rule is present, which is what
+    /// makes a typo fail loudly-ish (nothing arms) rather than silently pinning something arbitrary.
+    static func parse(spec: String) -> Config? {
+        var capture: Capture?
+        var period: TimeInterval = 2
+
+        for rawField in spec.split(separator: ",") {
+            let field = rawField.trimmingCharacters(in: .whitespaces)
+            if let v = value(of: field, after: "darkest:"), let n = Int(v) {
+                capture = .darkest(frames: max(1, n))
+            } else if let v = value(of: field, after: "brightest:"), let n = Int(v) {
+                capture = .brightest(frames: max(1, n))
+            } else if let v = value(of: field, after: "maxpq<="), let n = UInt16(v) {
+                capture = .atMost(.maxPQ, n)
+            } else if let v = value(of: field, after: "maxpq>="), let n = UInt16(v) {
+                capture = .atLeast(.maxPQ, n)
+            } else if let v = value(of: field, after: "avgpq<="), let n = UInt16(v) {
+                capture = .atMost(.avgPQ, n)
+            } else if let v = value(of: field, after: "avgpq>="), let n = UInt16(v) {
+                capture = .atLeast(.avgPQ, n)
+            } else if let v = value(of: field, after: "period:"), let s = TimeInterval(v) {
+                guard s.isFinite else { continue }
+                period = s <= 0 ? 0 : min(max(s, minimumPeriod), maximumPeriod)
+            }
+        }
+        guard let capture else { return nil }
+        return Config(capture: capture, period: period)
+    }
+
+    private static func value(of field: String, after prefix: String) -> String? {
+        guard field.lowercased().hasPrefix(prefix) else { return nil }
+        return String(field.dropFirst(prefix.count))
+    }
+}
+
+/// The engine's process-wide pin test, the one `DoviDisplayMetadata.attach` consults for every frame.
+enum DoviDisplayMetadataDebug {
+    static let shared = DoviPinTest()
+
+    static func configure(_ config: DoviPinTest.Config?) { shared.configure(config) }
+    static var isPinned: Bool { shared.isPinned }
+    static var isArmed: Bool { shared.isArmed }
+    static func substitute(_ nal: [UInt8]?) -> [UInt8]? { shared.substitute(nal) }
+    static func parse(spec: String) -> DoviPinTest.Config? { DoviPinTest.parse(spec: spec) }
+}
+#endif
diff --git a/Sources/AetherEngine/Video/DoviRpuSurvey.swift b/Sources/AetherEngine/Video/DoviRpuSurvey.swift
new file mode 100644
index 000000000..d0e66df8c
--- /dev/null
+++ b/Sources/AetherEngine/Video/DoviRpuSurvey.swift
@@ -0,0 +1,226 @@
+import Foundation
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+import Dovi
+
+/// The display-metadata content of one frame's RPU, as libdovi parses it.
+///
+/// This is the *other half* of an RPU from what `DoviMetalParams` carries. `DoviMetalParams` has
+/// the reshaping coefficients the GPU composer needs to rebuild pixels; this has the display
+/// metadata a Dolby Vision TV acts on — L1 frame statistics and L2 creative trims. Nothing here
+/// feeds playback; it exists so `aetherctl dvsurvey` can tell an operator which frame of a title
+/// carries the most extreme metadata, which is the frame worth pinning for the on-device
+/// consumption test (see `DoviDisplayMetadataDebug`).
+@_spi(Diagnostics)
+public struct DoviRpuFrameSurvey: Sendable {
+    public let frameIndex: Int
+    /// Non-zero on the first frame of a new scene. Dolby Vision DM resets its temporal filters here.
+    public let sceneRefresh: Bool
+    /// 12-bit PQ codes (0...4095) describing the frame's luminance distribution.
+    public let l1MinPQ: UInt16
+    public let l1AvgPQ: UInt16
+    public let l1MaxPQ: UInt16
+    /// Creative trims, one entry per target display peak brightness present in this RPU.
+    public let l2Trims: [Trim]
+    /// Source mastering range, from the RPU header rather than an L1 block.
+    public let sourceMinPQ: UInt16
+    public let sourceMaxPQ: UInt16
+    /// Byte length of the Profile 8.1 payload that would be attached for this frame.
+    public let payloadBytes: Int
+
+    public struct Trim: Sendable {
+        public let targetMaxPQ: UInt16
+        public let slope: UInt16
+        public let offset: UInt16
+        public let power: UInt16
+        public let chromaWeight: UInt16
+        public let saturationGain: UInt16
+        public let msWeight: Int16
+    }
+
+    /// L1 max as display luminance. The PQ codes are what the TV consumes; nits are for reading.
+    public var l1MaxNits: Double { DoviRpuSurvey.pqCodeToNits(l1MaxPQ) }
+    public var l1AvgNits: Double { DoviRpuSurvey.pqCodeToNits(l1AvgPQ) }
+    public var l1MinNits: Double { DoviRpuSurvey.pqCodeToNits(l1MinPQ) }
+}
+
+/// Whole-title survey plus the frame picks that matter for the consumption test.
+@_spi(Diagnostics)
+public struct DoviRpuSurveyResult: Sendable {
+    public let frames: [DoviRpuFrameSurvey]
+    public let packetsProcessed: Int
+    /// Frames whose RPU failed to parse or convert. Non-zero means the survey is incomplete.
+    public let rpuFailures: Int
+    public let enhancementLayerType: String?
+
+    /// Frame with the lowest L1 `avg_pq` — the darkest frame in the survey. Ranked on `avg_pq`
+    /// rather than `max_pq` because `avg_pq` is what anchors the display-mapping curve's mid-tone,
+    /// and because it is typically the field with the widest range in a title: a frame can hold a
+    /// bright specular highlight (high `max_pq`) while being almost entirely black. Pinning this
+    /// one while a bright scene plays tells the TV the scene is nearly dark, which should visibly
+    /// crush it if the metadata is reaching the panel.
+    public var darkestFrame: DoviRpuFrameSurvey? { frames.min { $0.l1AvgPQ < $1.l1AvgPQ } }
+    /// Frame with the highest L1 `avg_pq` — the brightest. The complementary poison: pinned over a
+    /// dark scene the TV should stop protecting shadows and lift them.
+    public var brightestFrame: DoviRpuFrameSurvey? { frames.max { $0.l1AvgPQ < $1.l1AvgPQ } }
+
+    /// The pin that puts the largest total distance between its L1 and this title's own median
+    /// frame, with that distance in PQ codes and which field carries most of it.
+    ///
+    /// Scored across all three L1 fields, not just one: the display-mapping curve is fitted to
+    /// `min`/`max`/`avg` together, so a frame that disagrees with the scene on two of them
+    /// misleads the TV more than one that disagrees harder on a single field.
+    public var strongestPoison: (frame: DoviRpuFrameSurvey, deltaPQ: Int, dominantField: String)? {
+        guard !frames.isEmpty else { return nil }
+        func median(_ v: [UInt16]) -> Int { Int(v.sorted()[v.count / 2]) }
+        let mMin = median(frames.map(\.l1MinPQ))
+        let mMax = median(frames.map(\.l1MaxPQ))
+        let mAvg = median(frames.map(\.l1AvgPQ))
+        func deltas(_ f: DoviRpuFrameSurvey) -> (min: Int, max: Int, avg: Int) {
+            (abs(Int(f.l1MinPQ) - mMin), abs(Int(f.l1MaxPQ) - mMax), abs(Int(f.l1AvgPQ) - mAvg))
+        }
+        func score(_ f: DoviRpuFrameSurvey) -> Int { let d = deltas(f); return d.min + d.max + d.avg }
+        guard let pick = frames.max(by: { score($0) < score($1) }) else { return nil }
+        let d = deltas(pick)
+        let dominant = d.avg >= d.max && d.avg >= d.min ? "avg_pq" : (d.max >= d.min ? "max_pq" : "min_pq")
+        return (pick, score(pick), dominant)
+    }
+
+    /// Median L1 of the surveyed frames, for reporting what a pin is being measured against.
+    public var medianL1: (min: UInt16, max: UInt16, avg: UInt16)? {
+        guard !frames.isEmpty else { return nil }
+        func med(_ v: [UInt16]) -> UInt16 { v.sorted()[v.count / 2] }
+        return (med(frames.map(\.l1MinPQ)), med(frames.map(\.l1MaxPQ)), med(frames.map(\.l1AvgPQ)))
+    }
+}
+
+@_spi(Diagnostics)
+public enum DoviRpuSurvey {
+
+    /// Parses the display metadata out of one `unspec62` NAL.
+    ///
+    /// The NAL is converted to Profile 8.1 first, so what comes back is what would actually be
+    /// attached to the frame rather than what the Profile 7 bitstream held — the two agree on
+    /// L1/L2 by construction (`dovi_convert_rpu_with_mode` rewrites only the profile container),
+    /// and surveying the converted form means a surprise there shows up here instead of on the TV.
+    public static func parse(nal: UnsafePointer<UInt8>, length: Int, frameIndex: Int) -> DoviRpuFrameSurvey? {
+        guard let rpu = DoviRpuGuard.parse(nal, length) else { return nil }
+        defer { dovi_rpu_free(rpu) }
+        guard let out = DoviRpuConverter.convertedUnspec62(rpu) else { return nil }
+        // Minus the 2-byte NAL header, which `DoviDisplayMetadata` strips before attaching.
+        let payloadBytes = max(0, out.pointee.len - 2)
+        dovi_data_free(out)
+
+        guard let dm = dovi_rpu_get_vdr_dm_data(rpu) else { return nil }
+        defer { dovi_rpu_free_vdr_dm_data(dm) }
+
+        var minPQ: UInt16 = 0, avgPQ: UInt16 = 0, maxPQ: UInt16 = 0
+        if let l1 = dm.pointee.dm_data.level1 {
+            minPQ = l1.pointee.min_pq
+            avgPQ = l1.pointee.avg_pq
+            maxPQ = l1.pointee.max_pq
+        }
+
+        var trims: [DoviRpuFrameSurvey.Trim] = []
+        let l2 = dm.pointee.dm_data.level2
+        if let list = l2.list, l2.len > 0 {
+            for i in 0..<Int(l2.len) {
+                guard let t = list[i] else { continue }
+                trims.append(.init(targetMaxPQ: t.pointee.target_max_pq,
+                                   slope: t.pointee.trim_slope,
+                                   offset: t.pointee.trim_offset,
+                                   power: t.pointee.trim_power,
+                                   chromaWeight: t.pointee.trim_chroma_weight,
+                                   saturationGain: t.pointee.trim_saturation_gain,
+                                   msWeight: t.pointee.ms_weight))
+            }
+        }
+
+        return DoviRpuFrameSurvey(
+            frameIndex: frameIndex,
+            sceneRefresh: dm.pointee.scene_refresh_flag != 0,
+            l1MinPQ: minPQ,
+            l1AvgPQ: avgPQ,
+            l1MaxPQ: maxPQ,
+            l2Trims: trims,
+            sourceMinPQ: dm.pointee.source_min_pq,
+            sourceMaxPQ: dm.pointee.source_max_pq,
+            payloadBytes: payloadBytes
+        )
+    }
+
+    /// ST.2084 (PQ) EOTF on a 12-bit code value, in cd/m². Reporting only.
+    public static func pqCodeToNits(_ code: UInt16) -> Double {
+        let e = min(1.0, max(0.0, Double(code) / 4095.0))
+        let m1 = 2610.0 / 16384.0
+        let m2 = 2523.0 / 4096.0 * 128.0
+        let c1 = 3424.0 / 4096.0
+        let c2 = 2413.0 / 4096.0 * 32.0
+        let c3 = 2392.0 / 4096.0 * 32.0
+        let ep = pow(e, 1.0 / m2)
+        let num = max(ep - c1, 0.0)
+        let den = c2 - c3 * ep
+        guard den > 0 else { return 0 }
+        return pow(num / den, 1.0 / m1) * 10000.0
+    }
+}
+
+extension AetherEngine {
+
+    /// Walks a title's video stream and surveys every frame's Dolby Vision display metadata.
+    ///
+    /// Runs the demuxer and `DoviRpuConverter` only — no decoders, no GPU — so it is fast enough to
+    /// sweep thousands of frames. Its purpose is picking the pin for the on-device consumption test:
+    /// the operator arms `AetherEngine.armDolbyVisionPinTest(_:)` with `strongestPoison`'s frame.
+    @_spi(Diagnostics)
+    public nonisolated static func doviRpuSurvey(
+        url: URL,
+        maxFrames: Int = 2000,
+        options: LoadOptions = .init()
+    ) throws -> DoviRpuSurveyResult {
+        let demuxer = Demuxer()
+        try demuxer.open(url: url, extraHeaders: options.httpHeaders)
+        defer { demuxer.close() }
+
+        let videoIdx = demuxer.videoStreamIndex
+        guard videoIdx >= 0 else { throw AetherEngineError.noVideoStream }
+
+        var frames: [DoviRpuFrameSurvey] = []
+        var packetsProcessed = 0
+        var failures = 0
+        var elType: String?
+
+        while frames.count < maxFrames {
+            let maybePacket: UnsafeMutablePointer<AVPacket>?
+            do { maybePacket = try demuxer.readPacket() } catch { break }
+            guard let packet = maybePacket else { break }
+
+            if packet.pointee.stream_index == videoIdx {
+                packetsProcessed += 1
+                if elType == nil { elType = DoviRpuConverter.enhancementLayerType(packet) }
+                // extractEL: false — the survey never touches pixels, so the EL is dead weight.
+                let layers = DoviRpuConverter.separateDualLayers(packet, extractEL: false)
+                if let raw = layers.rpuData {
+                    let idx = frames.count
+                    let parsed: DoviRpuFrameSurvey? = raw.withUnsafeBufferPointer { buf in
+                        guard let base = buf.baseAddress else { return nil }
+                        return DoviRpuSurvey.parse(nal: base, length: buf.count, frameIndex: idx)
+                    }
+                    if let parsed { frames.append(parsed) } else { failures += 1 }
+                }
+            }
+
+            av_packet_unref(packet)
+            var opt: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&opt)
+        }
+
+        return DoviRpuSurveyResult(
+            frames: frames,
+            packetsProcessed: packetsProcessed,
+            rpuFailures: failures,
+            enhancementLayerType: elType
+        )
+    }
+}
diff --git a/Sources/aetherctl/DvSurvey.swift b/Sources/aetherctl/DvSurvey.swift
new file mode 100644
index 000000000..d8236e544
--- /dev/null
+++ b/Sources/aetherctl/DvSurvey.swift
@@ -0,0 +1,124 @@
+import Foundation
+@_spi(Diagnostics) import AetherEngine
+
+/// Surveys a title's Dolby Vision display metadata and names the frame worth pinning for the
+/// on-device consumption test. See `DoviDisplayMetadataDebug` for what the pin is for.
+func runDvSurvey(url: URL, maxFrames: Int, listFrames: Int) -> Int32 {
+    print("aetherctl dvsurvey: \(url.path)")
+    print("Scanning up to \(maxFrames) RPU-bearing frames...")
+    print("")
+
+    let result: DoviRpuSurveyResult
+    do {
+        result = try AetherEngine.doviRpuSurvey(url: url, maxFrames: maxFrames)
+    } catch {
+        print("ERROR: doviRpuSurvey failed: \(error)")
+        return 1
+    }
+
+    guard !result.frames.isEmpty else {
+        print("VERDICT: no Dolby Vision RPUs found in \(result.packetsProcessed) video packet(s).")
+        print("         Either this is not a Dolby Vision source, or the RPUs failed to parse")
+        print("         (\(result.rpuFailures) failure(s) recorded).")
+        return 2
+    }
+
+    let maxPQs = result.frames.map(\.l1MaxPQ).sorted()
+    let avgPQs = result.frames.map(\.l1AvgPQ).sorted()
+    func pct(_ sorted: [UInt16], _ p: Double) -> UInt16 { sorted[min(sorted.count - 1, Int(Double(sorted.count - 1) * p))] }
+    func nits(_ code: UInt16) -> String { String(format: "%.1f", DoviRpuSurvey.pqCodeToNits(code)) }
+
+    print("=== TITLE SUMMARY ===")
+    print("Video packets:        \(result.packetsProcessed)")
+    print("Frames with RPU:      \(result.frames.count)")
+    print("RPU parse failures:   \(result.rpuFailures)")
+    print("Enhancement layer:    \(result.enhancementLayerType ?? "n/a (not profile 7)")")
+    print("Scene changes:        \(result.frames.filter(\.sceneRefresh).count)")
+    print("L2 trims per frame:   \(Set(result.frames.map(\.l2Trims.count)).sorted().map(String.init).joined(separator: "/"))")
+    print("Attached payload:     \(Set(result.frames.map(\.payloadBytes)).sorted().map(String.init).joined(separator: "/")) bytes")
+    if let first = result.frames.first {
+        print("Source mastering:     min_pq \(first.sourceMinPQ) (\(nits(first.sourceMinPQ)) nits), max_pq \(first.sourceMaxPQ) (\(nits(first.sourceMaxPQ)) nits)")
+    }
+    print("")
+
+    // `String(format:)` with %s takes a C string, not a Swift String, so pad by hand.
+    func col(_ s: String, _ w: Int) -> String { String(repeating: " ", count: max(0, w - s.count)) + s }
+    func row(_ label: String, _ v: [UInt16]) -> String {
+        ([label.padding(toLength: 10, withPad: " ", startingAt: 0)]
+         + [v.first!, pct(v, 0.1), pct(v, 0.5), pct(v, 0.9), v.last!].map { col(String($0), 8) }).joined(separator: " ")
+    }
+    print("=== L1 DISTRIBUTION (12-bit PQ codes) ===")
+    print((["field".padding(toLength: 10, withPad: " ", startingAt: 0)]
+           + ["min", "p10", "median", "p90", "max"].map { col($0, 8) }).joined(separator: " "))
+    print(row("max_pq", maxPQs))
+    print(row("avg_pq", avgPQs))
+    print("           in nits: \(nits(maxPQs.first!)) ... \(nits(maxPQs.last!)) (max_pq)")
+    print("")
+
+    if listFrames > 0 {
+        print("=== FIRST \(min(listFrames, result.frames.count)) FRAMES ===")
+        print([col("frame", 6), col("sc", 3), col("min_pq", 7), col("max_pq", 7), col("avg_pq", 7)]
+              .joined(separator: " ") + "   L2 trims (target_max_pq: slope/offset/power)")
+        for f in result.frames.prefix(listFrames) {
+            let trims = f.l2Trims.map { "\($0.targetMaxPQ): \($0.slope)/\($0.offset)/\($0.power)" }.joined(separator: "  ")
+            print([col(String(f.frameIndex), 6), col(f.sceneRefresh ? "*" : "", 3),
+                   col(String(f.l1MinPQ), 7), col(String(f.l1MaxPQ), 7), col(String(f.l1AvgPQ), 7)]
+                  .joined(separator: " ") + "   " + trims)
+        }
+        print("")
+    }
+
+    print("=== PIN CANDIDATES FOR THE CONSUMPTION TEST ===")
+    if let dark = result.darkestFrame {
+        print("Darkest   frame \(dark.frameIndex): avg_pq \(dark.l1AvgPQ) (\(nits(dark.l1AvgPQ)) nits), max_pq \(dark.l1MaxPQ)")
+    }
+    if let bright = result.brightestFrame {
+        print("Brightest frame \(bright.frameIndex): avg_pq \(bright.l1AvgPQ) (\(nits(bright.l1AvgPQ)) nits), max_pq \(bright.l1MaxPQ)")
+    }
+    print("")
+
+    guard let poison = result.strongestPoison, let median = result.medianL1 else {
+        print("VERDICT: surveyed \(result.frames.count) frame(s) but could not pick a pin.")
+        return 3
+    }
+
+    // Name the pin by whichever field carries most of its distance from the median, so the
+    // threshold rule below selects the same frame the scan would.
+    let onAvg = poison.dominantField == "avg_pq"
+    let pinnedValue = onAvg ? poison.frame.l1AvgPQ : poison.frame.l1MaxPQ
+    let medianValue = onAvg ? median.avg : median.max
+    let isDark = pinnedValue < medianValue
+    let rule = "\(onAvg ? "avgpq" : "maxpq")\(isDark ? "<=" : ">=")\(pinnedValue)"
+    // The scan window has to reach the frame it is being told to find. Playback frame order is
+    // presentation order and the survey counts in decode order, so leave headroom for reordering.
+    let scanWindow = max(240, poison.frame.frameIndex + 60)
+    let scanRule = "\(isDark ? "darkest" : "brightest"):\(scanWindow)"
+
+    print("Strongest pin is frame \(poison.frame.frameIndex):")
+    print("  L1      min \(poison.frame.l1MinPQ)  max \(poison.frame.l1MaxPQ)  avg \(poison.frame.l1AvgPQ)")
+    print("  median  min \(median.min)  max \(median.max)  avg \(median.avg)")
+    print("  total distance \(poison.deltaPQ) PQ codes, mostly in \(poison.dominantField)")
+    print("  (\(nits(pinnedValue)) nits vs \(nits(medianValue)) nits on \(poison.dominantField))")
+    print("")
+    print("Arm the device with either of:")
+    print("    aetherctl play --fel --surface --dv-pin '\(scanRule),period:2' <url>")
+    print("        scans the first \(scanWindow) frames as they play and pins the most extreme one it saw")
+    print("    aetherctl play --fel --surface --dv-pin '\(rule),period:2' <url>")
+    print("        pins the first frame matching this exact threshold")
+    print("")
+    print("Then play this title on the Apple TV and watch the panel. The decoded pixels are")
+    print("bit-identical in both phases, so a 2-second brightness or saturation pulse means the")
+    print("attachment reached the panel. A flat picture means it did not.")
+    print("")
+
+    // Below roughly a quarter-stop of combined L1 movement the panel's own tone mapping absorbs the
+    // difference, so say so rather than sending the operator to stare at a TV for nothing.
+    if poison.deltaPQ < 300 {
+        print("VERDICT: WEAK - the strongest pin moves L1 by only \(poison.deltaPQ) PQ codes in total.")
+        print("         This title is too flat for a reliable visual test; pick one with a")
+        print("         dark-to-bright range, or survey more frames with --frames.")
+        return 4
+    }
+    print("VERDICT: surveyed \(result.frames.count) frame(s); strongest pin moves L1 by \(poison.deltaPQ) PQ codes.")
+    return 0
+}
diff --git a/Sources/aetherctl/FelTest.swift b/Sources/aetherctl/FelTest.swift
new file mode 100644
index 000000000..ba9dfb237
--- /dev/null
+++ b/Sources/aetherctl/FelTest.swift
@@ -0,0 +1,68 @@
+import Foundation
+@_spi(Diagnostics) import AetherEngine
+
+/// Standalone test runner for Dolby Vision Profile 7 FEL dual-layer decoding and Metal reconstruction.
+func runFelTest(url: URL, maxFrames: Int = 100) -> Int32 {
+    print("==================================================")
+    print("aetherctl feltest: Dolby Vision Profile 7 FEL Engine")
+    print("Source: \(url.path)")
+    print("Max frames to test: \(maxFrames)")
+    print("==================================================")
+
+    let result: FelProbeResult
+    do {
+        result = try AetherEngine.felDecodeProbe(url: url, maxPackets: maxFrames)
+    } catch {
+        print("ERROR: felDecodeProbe failed: \(error)")
+        return 1
+    }
+
+    print("")
+    print("=== DOLBY VISION FEL TEST RESULTS ===")
+    print("Stream Classification:    \(result.isFEL ? "Profile 7 FEL" : "Not FEL (MEL / single-layer)")")
+    print("Packets processed:        \(result.packetsProcessed)")
+    print("Frames output:            \(result.framesReconstructed)")
+    print("Frames composed on GPU:   \(result.composedFrames)")
+    print("Dimensions:               \(result.width) x \(result.height)")
+    print("Pixel Format:             \(result.pixelFormat)")
+    print("Elapsed time:             \(String(format: "%.3f", result.durationSeconds)) seconds")
+    print("Reconstruction Throughput: \(String(format: "%.2f", result.fps)) FPS")
+    print("--- Pixel Quality Audit ---")
+    print("Avg Luma (Y):             \(String(format: "%.1f", result.avgLuma)) [10-bit code]")
+    print("Avg Chroma Cb:            \(String(format: "%.1f", result.avgCb)) (std dev: \(String(format: "%.2f", result.stdDevCb)))")
+    print("Avg Chroma Cr:            \(String(format: "%.1f", result.avgCr)) (std dev: \(String(format: "%.2f", result.stdDevCr)))")
+    print("Chroma Validity Check:    \(result.isChromaValid ? "PASS (active picture)" : "FAIL (collapsed to 64)")")
+    print("--- Dolby Vision Display Metadata ---")
+    print("Frames w/ RPU attachment: \(result.framesWithDVMetadata) / \(result.framesReconstructed)")
+    print("Distinct RPU payloads:    \(result.distinctDVPayloads)")
+    print("First payload size:       \(result.firstDVPayloadBytes) bytes")
+    print("First payload prefix:     \(result.firstDVPayloadPrefix)... (expect leading 19)")
+    print("=====================================")
+
+    if result.framesReconstructed > 0 {
+        if !result.isFEL {
+            print("VERDICT: NOT FEL - Stream classified as MEL or non-FEL; enhancement layer was not engaged.")
+            return 0
+        }
+        if !result.isChromaValid {
+            print("VERDICT: FAILED - Chroma collapsed to flat 64 (the known green-picture failure)!")
+            return 3
+        }
+        if result.framesWithDVMetadata < result.framesReconstructed {
+            print("VERDICT: FAILED - \(result.framesReconstructed - result.framesWithDVMetadata) frame(s) emitted without per-frame Dolby Vision display metadata.")
+            return 4
+        }
+        if result.composedFrames == 0 {
+            print("VERDICT: FAILED - \(result.framesReconstructed) frame(s) came out but none was composed; every frame bypassed to its base layer.")
+            return 5
+        }
+        if result.distinctDVPayloads <= 1 && result.framesReconstructed > 1 {
+            print("WARNING: the RPU payload is static across \(result.framesReconstructed) frames. L1 is usually per-frame, but a static-metadata clip is valid; check the source if this one should vary.")
+        }
+        print("VERDICT: SUCCESS - Dolby Vision Profile 7 dual-layer Metal reconstruction verified.")
+        return 0
+    } else {
+        print("VERDICT: FAILED - No frames were reconstructed.")
+        return 2
+    }
+}
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 4f7bafd7f..0f3826b82 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -6,6 +6,9 @@ import AVFoundation
 import ImageIO
 import UniformTypeIdentifiers
 import AetherEngine
+#if canImport(AppKit)
+import AppKit
+#endif
 
 /// #544: the still drill writes what it decoded, because a hit count says the call returned an image
 /// and only the file says it is the right picture.
@@ -65,6 +68,7 @@ enum LoadOptionChange {
     case preferredAudioLanguages([String])
     case decodePath(DecodePath)
     case dolbyVisionHandling(DolbyVisionHandling)
+    case preferDualLayerDolbyVision(Bool)
     case isLive(Bool)
     case autoplay(Bool)
 
@@ -75,6 +79,7 @@ enum LoadOptionChange {
         case .preferredAudioLanguages(let langs): return "preferredAudioLanguages=\(langs.joined(separator: ","))"
         case .decodePath(let path): return "preferredDecodePath=\(path.rawValue)"
         case .dolbyVisionHandling(let handling): return "dolbyVisionHandling=\(handling.rawValue)"
+        case .preferDualLayerDolbyVision(let flag): return "preferDualLayerDolbyVision=\(flag)"
         case .isLive(let value): return "isLive=\(value)"
         case .autoplay(let value): return "autoplay=\(value)"
         }
@@ -87,6 +92,7 @@ enum LoadOptionChange {
         case .preferredAudioLanguages(let langs): options.preferredAudioLanguages = langs
         case .decodePath(let path): options.preferredDecodePath = path
         case .dolbyVisionHandling(let handling): options.dolbyVisionHandling = handling
+        case .preferDualLayerDolbyVision(let flag): options.preferDualLayerDolbyVision = flag
         case .isLive(let value): options.isLive = value
         case .autoplay(let value): options.autoplay = value
         }
@@ -110,7 +116,8 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
                     deinterlaceFieldRate: DeinterlaceFieldRate = .field,
                     assertDolbyVision: Bool = false,
                     preserveASSMarkup: Bool = false,
-                    dolbyVisionHandling: DolbyVisionHandling = .automatic, record: URL? = nil) -> Int32 {
+                    dolbyVisionHandling: DolbyVisionHandling = .automatic, preferDualLayerDolbyVision: Bool = false,
+                    attachSurface: Bool = false, record: URL? = nil) -> Int32 {
     EngineLog.handler = { print($0) }
     if mallocCensus {
         AetherEngine.setLargeAllocationCensusEnabled(
@@ -132,7 +139,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, servedURL: servedURL, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, nativeVideoFrameDiagnostics: nativeVideoFrameDiagnostics, nativeVideoFrameRecovery: nativeVideoFrameRecovery, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, progressiveSegments: progressiveSegments, 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, nativeVideoFrameDiagnostics: nativeVideoFrameDiagnostics, nativeVideoFrameRecovery: nativeVideoFrameRecovery, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, progressiveSegments: progressiveSegments, preferDualLayerDolbyVision: preferDualLayerDolbyVision, attachSurface: attachSurface, declaredDuration: declaredDuration, httpHeaders: httpHeaders, deinterlaceFieldRate: deinterlaceFieldRate, assertDolbyVision: assertDolbyVision, preserveASSMarkup: preserveASSMarkup, dolbyVisionHandling: dolbyVisionHandling, record: record)
         CFRunLoopStop(CFRunLoopGetMain())
     }
     CFRunLoopRun()
@@ -453,7 +460,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, servedURL: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0, nativeVideoFrameDiagnostics: Bool = false, nativeVideoFrameRecovery: Bool = false, 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, progressiveSegments: 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, nativeVideoFrameDiagnostics: Bool = false, nativeVideoFrameRecovery: Bool = false, 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, progressiveSegments: Bool = false, preferDualLayerDolbyVision: Bool = false, attachSurface: 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()
@@ -549,6 +556,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         // The base layer of a Dolby Vision source, the Dolby Vision left out of the container: the
         // harness for a record the bitstream contradicts.
         dolbyVisionHandling: dolbyVisionHandling,
+        preferDualLayerDolbyVision: preferDualLayerDolbyVision,
         panelPresentsDolbyVision: assertDolbyVision,
         isLive: live,
         dvrWindowSeconds: dvrWindow,
@@ -616,6 +624,44 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         }
     }
 
+    #if canImport(AppKit)
+    var surfaceWindow: NSWindow?
+    var surfaceView: AetherPlayerView?
+    if attachSurface {
+        _ = NSApplication.shared
+        let pv = AetherPlayerView(frame: NSRect(x: 0, y: 0, width: 1280, height: 720))
+        let win = NSWindow(
+            contentRect: NSRect(x: 0, y: 0, width: 1280, height: 720),
+            styleMask: [.titled, .closable, .miniaturizable, .resizable],
+            backing: .buffered,
+            defer: false
+        )
+        win.title = "AetherEngine Dolby Vision FEL Playback"
+        win.contentView = pv
+        // `--cycle-el` posts the current mode here; shown as a large label over the picture and in the title.
+        let label = NSTextField(labelWithString: "")
+        label.font = .systemFont(ofSize: 44, weight: .heavy)
+        label.textColor = .white
+        label.drawsBackground = true
+        label.backgroundColor = NSColor.black.withAlphaComponent(0.7)
+        label.isHidden = true
+        label.frame = NSRect(x: 24, y: 24, width: 640, height: 64)
+        label.autoresizingMask = [.maxXMargin, .maxYMargin]
+        pv.addSubview(label)
+        NotificationCenter.default.addObserver(forName: Notification.Name("aetherctl.elmode"), object: nil, queue: .main) { note in
+            let text = (note.object as? String) ?? ""
+            label.stringValue = " " + text + " "
+            label.isHidden = false
+            win.title = "AetherEngine: " + text
+        }
+        win.orderFront(nil)
+        engine.bind(view: pv)
+        surfaceView = pv
+        surfaceWindow = win
+        print("  SURFACE attached: 1280x720 window active for display layer")
+    }
+    #endif
+
     do {
         let probe: SourceProbe?
         if liveIngest {
@@ -1541,6 +1587,10 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             print("recording: \(bytes) B at \(record.path)")
         }
     }
+    #if canImport(AppKit)
+    _ = surfaceWindow
+    _ = surfaceView
+    #endif
     print("VERDICT: OK")
     return 0
 }
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index e13751005..7bf2af389 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -24,7 +24,7 @@
 
 import Foundation
 import Darwin
-import AetherEngine
+@_spi(Diagnostics) import AetherEngine
 
 // MARK: - RSS / footprint samplers (keeper for regression tracking)
 
@@ -70,7 +70,7 @@ func printUsage() {
       aetherctl serve [--no-dv] [--force-dv] [--dv-base-layer] [--start-position S] [--iframes] [--atmos-bed 7.1.4] [--audio-index N] <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>]
+      aetherctl play [--fel] [--surface | --window] [--cycle-el SECONDS] [--dv-pin SPEC] [--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]]
@@ -80,7 +80,11 @@ func printUsage() {
                  [--sequential-origin] [--declared-duration S]
              [--max-concurrent-requests N]
                      [--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
+                     (full load+play session smoke test; --fel opts into the Profile 7
+                      FEL dual-layer route (off by default, as in the engine; --no-fel
+                      is accepted and does nothing); --surface (or --window) presents
+                      into a window; --cycle-el S flips the FEL residual every S
+                      seconds, which needs --fel and a surface; --subs activates the first
                       matching embedded subtitle track and logs overlay cues;
                       --audio-stats taps decoded PCM and prints per-second audio lead
                       plus PTS-continuity gaps; seekback rewinds 20 s at t=15 and
@@ -97,7 +101,7 @@ func printUsage() {
                       --reload-applying corrects a LoadOption on the playing
                       session through #460's session-preserving reload, repeatable;
                       keys header.<Name>, audio-bridge, preferred-audio,
-                      decode-path, dolby-vision, is-live
+                      decode-path, dolby-vision, prefer-dual-layer-dv, is-live
                       (is-live is there to show the refusal: a field that names the
                       session is refused, not silently ignored), default +20 s;
                       --sequential-origin declares a fake-range origin (one unranged
@@ -107,6 +111,8 @@ func printUsage() {
                           (#92: SW-decode each segment in isolation; framesDecoded==0 => not independent)
       aetherctl disc-inspect <disc.iso>
       aetherctl dovitest [--out PATH.hevc] <file>
+      aetherctl feltest [--frames N] <file>
+      aetherctl dvsurvey [--frames N] [--list K] <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>
@@ -243,6 +249,18 @@ func printUsage() {
                 that to `dovi_tool extract-rpu` + `info` to validate
                 the rewritten RPU against ground truth.
 
+      dvsurvey  Survey every frame's Dolby Vision display metadata (L1
+                frame statistics, L2 creative trims) with libdovi and
+                report the distribution. Names the frame whose L1 is
+                furthest from the title's median -- the strongest
+                "poison" for the on-device consumption test -- and
+                prints the --dv-pin spec that pins it. Pinning
+                changes only the attached metadata, never the decoded
+                pixels, so a visible pulse on the TV is proof the
+                attachment is being consumed. --list K also dumps the
+                first K frames. Exit 4 if the title's L1 range is too
+                flat for the test to be visible.
+
       swdecode  Open SoftwareVideoDecoder for the source's video
                 stream, feed packets, report counters + first-frame
                 metadata. Tests the SW-pipeline path without needing
@@ -460,6 +478,35 @@ if first == "dovitest" {
     exit(runDoviTest(url: parseSourceURL(urlArg), outputPath: outPath))
 }
 
+// Dolby Vision Profile 7 FEL dual-layer Metal reconstruction test.
+if first == "feltest" {
+    var rest = Array(args.dropFirst(2))
+    let frames = takeIntFlag("--frames", from: &rest) ?? 100
+    guard let urlArg = rest.first(where: { !$0.hasPrefix("--") }) else {
+        print("ERROR: feltest requires a <file> argument")
+        print("Usage: aetherctl feltest [--frames N] <file>")
+        exit(64)
+    }
+    rest.removeAll { $0 == urlArg }
+    rejectStrayFlags(rest, subcommand: "feltest")
+    exit(runFelTest(url: parseSourceURL(urlArg), maxFrames: frames))
+}
+
+// Dolby Vision display-metadata survey: picks the pin for the on-device consumption test.
+if first == "dvsurvey" {
+    var rest = Array(args.dropFirst(2))
+    let frames = takeIntFlag("--frames", from: &rest) ?? 2000
+    let list = takeIntFlag("--list", from: &rest) ?? 0
+    guard let urlArg = rest.first(where: { !$0.hasPrefix("--") }) else {
+        print("ERROR: dvsurvey requires a <file> argument")
+        print("Usage: aetherctl dvsurvey [--frames N] [--list K] <file>")
+        exit(64)
+    }
+    rest.removeAll { $0 == urlArg }
+    rejectStrayFlags(rest, subcommand: "dvsurvey")
+    exit(runDvSurvey(url: parseSourceURL(urlArg), maxFrames: frames, listFrames: list))
+}
+
 // #93 post-recovery judder: raw video packet timing per demuxer open profile.
 if first == "pktdump" {
     var rest = Array(args.dropFirst(2))
@@ -652,6 +699,57 @@ if first == "play" {
     let playDVHandling: DolbyVisionHandling = takeFlag("--dv-base-layer", from: &rest) ? .baseLayerOnly : .automatic
     // AE#560: record the live source to a file from the session's existing connection.
     let playRecord = takeStringFlag("--record", from: &rest).map { URL(fileURLWithPath: $0) }
+    // Dolby Vision Profile 7 FEL dual-layer decoding, opt-in like the engine's own
+    // `preferDualLayerDolbyVision` (default false): `--fel` turns it on, so a plain `play` runs the
+    // route a host gets by default. `--no-fel` / `--no-dual-layer` are accepted as no-ops for the
+    // scripts written when `play` turned it on by itself. Each spelling is taken separately, so
+    // passing two leaves neither behind in `rest`.
+    let playFel = takeFlag("--fel", from: &rest)
+    _ = takeFlag("--no-fel", from: &rest)
+    _ = takeFlag("--no-dual-layer", from: &rest)
+    let playPreferDualLayerDV = playFel
+    let playSurfaceFlag = takeFlag("--surface", from: &rest)
+    let playWindowFlag = takeFlag("--window", from: &rest)
+    let playAttachSurface = playSurfaceFlag || playWindowFlag
+    // `--cycle-el <seconds>`: flip the FEL residual off and on every N seconds (starting with full FEL), so a
+    // `--surface` window shows MEL-equivalent output (base layer + RPU mapping) against the full result.
+    if let spec = takeStringFlag("--cycle-el", from: &rest) {
+        guard let period = Double(spec), period.isFinite, period > 0 else {
+            print("ERROR: --cycle-el takes a period in seconds, got '\(spec)'")
+            exit(64)
+        }
+        if !playFel {
+            print("[aetherctl] note: --cycle-el only changes a session on the dual-layer route; add --fel")
+        }
+        let t = Thread {
+            var on = true
+            func announce() {
+                let name = on ? "FEL (full)" : "MEL (no residual)"
+                print("[aetherctl] cycle-el: \(name)")
+                DispatchQueue.main.async { NotificationCenter.default.post(name: Notification.Name("aetherctl.elmode"), object: name) }
+            }
+            announce()
+            while true {
+                Thread.sleep(forTimeInterval: period)
+                on.toggle()
+                AetherEngine.felResidualEnabled = on
+                announce()
+            }
+        }
+        t.start()
+    }
+    // `--dv-pin <spec>`: arm the Dolby Vision pin test (DEBUG builds), same grammar `dvsurvey` prints.
+    if let spec = takeStringFlag("--dv-pin", from: &rest) {
+        #if DEBUG
+        guard AetherEngine.armDolbyVisionPinTest(spec) else {
+            print("ERROR: --dv-pin '\(spec)' carries no capture rule (e.g. 'darkest:240,period:2')")
+            exit(64)
+        }
+        #else
+        print("ERROR: --dv-pin needs a DEBUG build of aetherctl")
+        exit(64)
+        #endif
+    }
     // AE#492: `LoadOptions.deinterlaceFieldRate`. `send_field` (the default) emits one frame per
     // FIELD, so a 29.97i source hands the layer 59.94 frames per second against 23.976 for a
     // progressive one. That is the confound in every per-seek drop count taken across the two, and
@@ -811,6 +909,12 @@ if first == "play" {
                 exit(64)
             }
             optionChanges.append(.dolbyVisionHandling(handling))
+        } else if key == "prefer-dual-layer-dv" || key == "fel-mode" {
+            guard let flag = Bool(value) else {
+                print("ERROR: --reload-applying \(key) takes true|false, got '\(value)'")
+                exit(64)
+            }
+            optionChanges.append(.preferDualLayerDolbyVision(flag))
         } else if key == "is-live" {
             guard let flag = Bool(value) else {
                 print("ERROR: --reload-applying is-live takes true|false, got '\(value)'")
@@ -824,7 +928,7 @@ if first == "play" {
             }
             optionChanges.append(.autoplay(flag))
         } else {
-            print("ERROR: --reload-applying key '\(key)' is not one of header.<Name>, audio-bridge, preferred-audio, decode-path, dolby-vision, is-live, autoplay")
+            print("ERROR: --reload-applying key '\(key)' is not one of header.<Name>, audio-bridge, preferred-audio, decode-path, dolby-vision, prefer-dual-layer-dv, fel-mode, is-live, autoplay")
             exit(64)
         }
     }
@@ -904,6 +1008,8 @@ if first == "play" {
                  assertDolbyVision: playAssertDV,
                  preserveASSMarkup: preserveASSMarkup,
                  dolbyVisionHandling: playDVHandling,
+                 preferDualLayerDolbyVision: playPreferDualLayerDV,
+                 attachSurface: playAttachSurface,
                  record: playRecord))
 }
 
diff --git a/Tests/AetherEngineTests/DoviPinTestTests.swift b/Tests/AetherEngineTests/DoviPinTestTests.swift
new file mode 100644
index 000000000..bc0f9c442
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviPinTestTests.swift
@@ -0,0 +1,86 @@
+#if DEBUG
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// The DEBUG pin test (`DoviPinTest`) holds its state in an instance, so these tests build their
+/// own with a local log sink. They never arm `DoviDisplayMetadataDebug.shared`, which every decoder
+/// in the process feeds, and never touch `EngineLog.handler`, so they cannot race another suite.
+@Suite("Dolby Vision pin test")
+struct DoviPinTestTests {
+
+    private final class Sink: @unchecked Sendable {
+        private let lock = NSLock()
+        private var storage: [String] = []
+        func append(_ line: String) { lock.lock(); storage.append(line); lock.unlock() }
+        var lines: [String] { lock.lock(); defer { lock.unlock() }; return storage }
+    }
+
+    @Test("disarms cleanly, logging once, when the scan window ends without a parseable L1")
+    func disarmsWhenScanWindowEndsWithoutL1() throws {
+        let sink = Sink()
+        let pin = DoviPinTest(emit: { sink.append($0) })
+        let config = try #require(DoviPinTest.parse(spec: "darkest:2,period:2"))
+        pin.configure(config)
+        #expect(pin.isArmed)
+
+        let junkNAL: [UInt8] = [0x00, 0x00, 0x01, 0xFF]
+        _ = pin.substitute(junkNAL)
+        #expect(pin.isArmed)
+
+        // The second unparseable frame ends the scan window: it must disarm.
+        _ = pin.substitute(junkNAL)
+        #expect(!pin.isArmed)
+        #expect(!pin.isPinned)
+
+        // Later frames neither re-enter the scan nor log again.
+        _ = pin.substitute(junkNAL)
+        _ = pin.substitute(junkNAL)
+
+        let failures = sink.lines.filter { $0.contains("found no parseable L1") }
+        #expect(failures.count == 1, "Expected exactly 1 disarm log line, got: \(failures)")
+    }
+
+    @Test("an unarmed pin test returns every frame's RPU unchanged")
+    func unarmedIsTransparent() {
+        let pin = DoviPinTest(emit: { _ in })
+        let nal: [UInt8] = [1, 2, 3]
+        #expect(pin.substitute(nal) == nal)
+        #expect(pin.substitute(nil) == nil)
+    }
+
+    @Test("period: is clamped, so a tiny or non-finite value cannot overflow the phase arithmetic")
+    func periodIsClamped() throws {
+        func period(_ spec: String) throws -> TimeInterval {
+            try #require(DoviPinTest.parse(spec: spec)).period
+        }
+        #expect(try period("darkest:5,period:0") == 0)
+        #expect(try period("darkest:5,period:0.0000001") == DoviPinTest.minimumPeriod)
+        #expect(try period("darkest:5,period:2") == 2)
+        #expect(try period("darkest:5,period:1e9") == DoviPinTest.maximumPeriod)
+        #expect(try period("darkest:5,period:nan") == 2)
+        #expect(try period("darkest:5,period:inf") == 2)
+    }
+
+    @Test("the capture rules dvsurvey prints parse back to the capture they name")
+    func surveyPrintedSpecsParse() throws {
+        func capture(_ spec: String) throws -> DoviPinTest.Capture {
+            try #require(DoviPinTest.parse(spec: spec)).capture
+        }
+        #expect(try capture("darkest:300,period:2") == .darkest(frames: 300))
+        #expect(try capture("brightest:240,period:2") == .brightest(frames: 240))
+        #expect(try capture("avgpq<=312,period:2") == .atMost(.avgPQ, 312))
+        #expect(try capture("maxpq>=4095,period:2") == .atLeast(.maxPQ, 4095))
+        // A window of zero frames is raised to one so the scan can still capture something.
+        #expect(try capture("darkest:0") == .darkest(frames: 1))
+    }
+
+    @Test("a spec without a capture rule arms nothing")
+    func specWithoutCaptureRuleIsRejected() {
+        #expect(DoviPinTest.parse(spec: "period:2") == nil)
+        #expect(DoviPinTest.parse(spec: "") == nil)
+        #expect(DoviPinTest.parse(spec: "darkest:abc") == nil)
+        #expect(DoviPinTest.parse(spec: "maxpq>=99999") == nil)
+    }
+}
+#endif
diff --git a/Tests/AetherEngineTests/DoviRpuSurveyResultTests.swift b/Tests/AetherEngineTests/DoviRpuSurveyResultTests.swift
new file mode 100644
index 000000000..89855a654
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviRpuSurveyResultTests.swift
@@ -0,0 +1,100 @@
+import Testing
+import Foundation
+@_spi(Diagnostics) @testable import AetherEngine
+
+/// The pure half of `aetherctl dvsurvey`: what `DoviRpuSurveyResult` makes of a list of frames, and
+/// the PQ-to-nits conversion it reports with. The RPU parsing itself needs libdovi and a real
+/// bitstream and is covered by the real-clip suites.
+@Suite("Dolby Vision RPU survey aggregation")
+struct DoviRpuSurveyResultTests {
+
+    private func frame(_ index: Int, min: UInt16, avg: UInt16, max: UInt16) -> DoviRpuFrameSurvey {
+        DoviRpuFrameSurvey(frameIndex: index, sceneRefresh: false,
+                           l1MinPQ: min, l1AvgPQ: avg, l1MaxPQ: max,
+                           l2Trims: [], sourceMinPQ: 0, sourceMaxPQ: 4095, payloadBytes: 100)
+    }
+
+    private func result(_ frames: [DoviRpuFrameSurvey]) -> DoviRpuSurveyResult {
+        DoviRpuSurveyResult(frames: frames, packetsProcessed: frames.count, rpuFailures: 0,
+                            enhancementLayerType: nil)
+    }
+
+    @Test("an empty survey picks nothing")
+    func emptySurvey() {
+        let r = result([])
+        #expect(r.darkestFrame == nil)
+        #expect(r.brightestFrame == nil)
+        #expect(r.strongestPoison == nil)
+        #expect(r.medianL1 == nil)
+    }
+
+    @Test("darkest and brightest rank on avg_pq, not max_pq")
+    func darkestAndBrightestRankOnAverage() throws {
+        // Frame 1 has the highest max_pq and the lowest avg_pq: a bright highlight in a near-black frame.
+        let r = result([frame(0, min: 0, avg: 1500, max: 2500),
+                        frame(1, min: 0, avg: 300, max: 4000),
+                        frame(2, min: 0, avg: 2200, max: 2600)])
+        #expect(try #require(r.darkestFrame).frameIndex == 1)
+        #expect(try #require(r.brightestFrame).frameIndex == 2)
+    }
+
+    @Test("the median is taken per field")
+    func medianPerField() throws {
+        let r = result([frame(0, min: 10, avg: 900, max: 3000),
+                        frame(1, min: 30, avg: 100, max: 2000),
+                        frame(2, min: 20, avg: 500, max: 4000)])
+        let m = try #require(r.medianL1)
+        #expect(m.min == 20)
+        #expect(m.avg == 500)
+        #expect(m.max == 3000)
+    }
+
+    @Test("the strongest pin is the frame furthest from the median across all three fields")
+    func strongestPoisonScoresAllFields() throws {
+        // Median is (min 0, avg 1000, max 2000). Frame 3 sits 100 off on avg and 1900 off on max;
+        // frame 4 sits 1500 off on avg alone, so the total (2000 against 1500) decides.
+        let r = result([frame(0, min: 0, avg: 1000, max: 2000),
+                        frame(1, min: 0, avg: 1000, max: 2000),
+                        frame(2, min: 0, avg: 1000, max: 2000),
+                        frame(3, min: 0, avg: 1100, max: 3900),
+                        frame(4, min: 0, avg: 2500, max: 2000)])
+        let p = try #require(r.strongestPoison)
+        #expect(p.frame.frameIndex == 3)
+        #expect(p.deltaPQ == 2000)
+        #expect(p.dominantField == "max_pq")
+    }
+
+    @Test("the dominant field breaks ties toward avg_pq, then max_pq")
+    func dominantFieldTieBreak() throws {
+        let flat = (0..<5).map { frame($0, min: 100, avg: 1000, max: 2000) }
+        func dominant(of outlier: DoviRpuFrameSurvey) throws -> String {
+            try #require(result(flat + [outlier]).strongestPoison).dominantField
+        }
+        #expect(try dominant(of: frame(9, min: 100, avg: 1500, max: 2500)) == "avg_pq")
+        #expect(try dominant(of: frame(9, min: 100, avg: 1000, max: 2500)) == "max_pq")
+        #expect(try dominant(of: frame(9, min: 600, avg: 1000, max: 2000)) == "min_pq")
+    }
+
+    @Test("a flat title scores zero distance")
+    func flatTitleHasNoDistance() throws {
+        let r = result((0..<8).map { frame($0, min: 0, avg: 1000, max: 2000) })
+        #expect(try #require(r.strongestPoison).deltaPQ == 0)
+    }
+
+    @Test("PQ codes convert to nits at the anchors and clamp outside the range")
+    func pqCodeToNits() {
+        #expect(DoviRpuSurvey.pqCodeToNits(0) == 0)
+        #expect(abs(DoviRpuSurvey.pqCodeToNits(4095) - 10000) < 1)
+        // PQ 0.508 is 100 nits; code 2081 of 4095 is 0.5081.
+        #expect(abs(DoviRpuSurvey.pqCodeToNits(2081) - 100) < 2)
+        // The curve is monotonic.
+        var previous = -1.0
+        for code in stride(from: 0, through: 4095, by: 64) {
+            let nits = DoviRpuSurvey.pqCodeToNits(UInt16(code))
+            #expect(nits > previous)
+            previous = nits
+        }
+        // Codes above 12 bits clamp to the peak instead of producing NaN.
+        #expect(abs(DoviRpuSurvey.pqCodeToNits(UInt16.max) - 10000) < 1)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index a779d6d5e..aa656e860 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1256,11 +1256,12 @@ All flags default to safe values; the table is the full set. Depth for the media
 
 ## Public but not host API
 
-Public for the CLI, the test suite, or a diagnostic overlay, and outside the shape this reference documents. They stay source-compatible under semver like everything else, but nothing here should carry playback logic:
+Public for the CLI, the test suite, or a diagnostic overlay, and outside the shape this reference documents. Nothing here should carry playback logic. The `@_spi(Diagnostics)` entries below are outside the SemVer contract and may change in any release; the other entries stay source-compatible like the rest of the public surface:
 
 - **Test hooks**: `setForceSoftwarePathForTesting`, `setSourceThrottleKbpsForTesting`, `setSoftwareBackgroundAudioOnlyForTesting`, `softwareVideoFramesEnqueuedForTesting`, `invalidateSoftwareVideoSessionForTesting`, `setLargeAllocationCensusEnabled`, `forceStalledConsumerReloadForTesting`, `stallRendererClockForTesting`, `rendererClockRateForTesting`.
 - **`playbackBackend`**: the internal rendering backend, exposed read-only for overlays. Hosts must not branch on it; `videoRoute` is the surface that answers the same question honestly.
 - **`HLSVideoEngine`** and its `DiagnosticStats`: the loopback session's own machinery, public because `aetherctl` drives it directly.
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
+- **Dolby Vision Profile 7 FEL tooling** (`@_spi(Diagnostics)`): `FelProbeResult` / `felDecodeProbe` (`aetherctl feltest`), `DoviRpuSurvey` / `DoviRpuSurveyResult` / `DoviRpuFrameSurvey` / `doviRpuSurvey` (`aetherctl dvsurvey`), `felResidualEnabled` (`aetherctl play --cycle-el`), and, in `DEBUG` builds only, `armDolbyVisionPinTest` / `dolbyVisionPinIsArmed` / `dolbyVisionPinIsActive` (`aetherctl play --dv-pin`). Hosts import none of them; the host surface of the FEL route is `LoadOptions.preferDualLayerDolbyVision` and, in `SessionReloadRefusal`, the new case `.dualLayerRouteNeedsFreshLoad`. See [Dolby Vision FEL](dolby-vision-fel.md) and [CLI](cli.md).
 - **`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.
diff --git a/docs/architecture.md b/docs/architecture.md
index 297cfe309..2af79931a 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -544,6 +544,10 @@ Sources/AetherEngine/
 │   ├── DoviRpuConverter.swift               libdovi RPU surgery for both routes. Native path: per-packet Profile 7 → 8.1 rewrite (convert type-62 RPU, drop type-63 EL). SW FEL path: `separateDualLayers` also lifts the EL into its own packet and returns the composer's reshaping parameters plus the 8.1 RPU attached as display metadata
 │   ├── DoviRpuConverter+Probe.swift         Diagnostic DV-conversion probe (`doviConvertProbe` / `DoviConvertProbeResult`), backs `aetherctl dovitest`
 │   ├── DoviDisplayMetadata.swift            SW FEL path: sets `DolbyVisionRPUData` (the Profile 8.1 RPU minus its NAL header) and `DolbyCompatibilityID` (the CFString "1", never a number) on every emitted buffer, or clears both; tvOS consumes them in backboardd
+│   ├── DoviDisplayMetadataDebug.swift       DEBUG-only pin test: substitutes a captured RPU on a duty cycle, the on-device consumption test
+│   ├── DoviRpuSurvey.swift                  L1 / L2 display-metadata survey over a title's RPUs (no decode, no GPU); backs `aetherctl dvsurvey`
+│   ├── AetherEngine+FelProbe.swift          FEL decode probe backing `aetherctl feltest`, and the `--cycle-el` residual switch
+│   ├── AetherEngine+DolbyVisionTest.swift   DEBUG-only `@_spi(Diagnostics)` hook (not host API) that arms the pin test from a debug menu or `aetherctl play --dv-pin`
 │   ├── Metal/
 │   │   ├── DoviFelComposer.swift            BL + EL + RPU composition: runtime-compiled pipelines, pooled P010 output, `composeAsync` bounded at `maxFramesInFlight` with completions on its own serial queue; RPU → `DoviMetalParams` parsing
 │   │   ├── DoviShaderSource.swift           Luma / chroma compose kernels (reshaping, inverse NLQ, bilinear EL upsampling, ordered dither) and the ABI layout probe, compiled at runtime
diff --git a/docs/cli.md b/docs/cli.md
index 8dbaa2baa..4412a12ff 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,6 +10,8 @@ swift run aetherctl segverify <url>      # SW-decode each loopback segment in is
 swift run aetherctl swdecode <url>       # open SoftwareVideoDecoder, decode N packets, report
 swift run aetherctl play <url>           # full load+play session smoke test: 1 Hz telemetry, cue log, host-call mimicry
 swift run aetherctl dovitest <url>       # convert a DV Profile 7 stream to 8.1, dump for dovi_tool
+swift run aetherctl feltest <url>        # test Dolby Vision Profile 7 FEL dual-layer Metal reconstruction
+swift run aetherctl dvsurvey <url>       # survey per-frame Dolby Vision L1 / L2 metadata, pick a --dv-pin frame
 swift run aetherctl pktdump <url>        # dump raw demuxer packet timing (dts/pts/keyframe) per open profile
 swift run aetherctl dualsubs <file> ...  # dual subtitle-track render probe (--primary / --secondary stream index)
 swift run aetherctl extract <url>        # FrameExtractor still-image extraction + leak testing
@@ -27,7 +29,7 @@ swift run aetherctl smbtest <smb-url>    # play a file off an SMB2/3 share via t
 swift run aetherctl <url>                # alias for serve (backwards compat)
 ```
 
-Twenty-one subcommands plus the bare-URL `serve` alias.
+Twenty-three subcommands plus the bare-URL `serve` alias.
 
 ## probe
 
@@ -105,6 +107,9 @@ swift run aetherctl play --live --dvr-window 1800 --audio-stats <url>
 swift run aetherctl play --live --native-hls <master.m3u8>      # nativeRemoteHLS bypass (carriage watchdog + #293 probe)
 swift run aetherctl play --sidecar de=/tmp/de.srt --subs de <master.m3u8>   # declare a sidecar at load (#316)
 swift run aetherctl play --native-hls --trust-any-certificate <https master.m3u8>  # the AE#495 origin relay
+swift run aetherctl play --fel <p7-file.mkv>                    # opt in to the Profile 7 FEL dual-layer route (off by default, like LoadOptions.preferDualLayerDolbyVision; --no-fel / --no-dual-layer are accepted and do nothing)
+swift run aetherctl play --fel --surface --cycle-el 10 <p7-file.mkv>   # flip the residual off and on every 10 s over a visible window (--window is the same flag)
+swift run aetherctl play --fel --surface --dv-pin 'darkest:240,period:2' <url>   # DEBUG: pulse a pinned frame's DV metadata (from dvsurvey)
 ```
 
 `--host-calls nativesubs,nativerender@N,subsoff@N,subson@N` drives the NATIVE SUBTITLE RENDITION path
@@ -249,12 +254,14 @@ gate: `AE#464: audio delay = +150 ms stands, but this session cannot re-anchor a
 re-anchor and re-cuts. Before round 2 the gate read `liveWindow != nil`, which is true for both, so the
 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`).
+`--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`, `prefer-dual-layer-dv` (alias `fel-mode`, `true|false`: `LoadOptions.preferDualLayerDolbyVision`, so a running session can be moved on or off the Profile 7 FEL route), `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 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.
 
+`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route. It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` (a release build refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
+
 `--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.
@@ -477,6 +484,22 @@ 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
 ```
 
+## feltest
+
+Runs the Dolby Vision Profile 7 FEL dual-layer pipeline over a real clip: demuxes, splits each packet into the base layer, the enhancement layer (typically 1080p) and the RPU, decodes both layers in hardware `VTDecompressionSession`s, composes each frame with `DoviFelComposer` on Metal, and audits the output twice. The pixel audit reports mean and standard deviation of Y / Cb / Cr, so a black picture or collapsed chroma fails. The metadata audit checks that every delivered frame carries a `DolbyVisionRPUData` attachment, and warns (without failing) when the payload never changes, since a static-metadata clip is valid. The verdict also requires at least one frame the composer actually reconstructed: a bypassed frame comes out as its base layer and counts as output but not as composed. Exit codes: `0` verified, `1` probe error, `2` no frames output, `3` chroma collapsed to a flat 64, `4` frames emitted without per-frame Dolby Vision metadata, `5` no frame was composed. See [dolby-vision-fel.md](dolby-vision-fel.md).
+
+```bash
+swift run aetherctl feltest [--frames N] <p7-source>
+```
+
+## dvsurvey
+
+Walks a title's RPUs with no decoders and no GPU, converts each to Profile 8.1 exactly as the FEL path attaches it, and reports the L1 distribution (`min_pq`, `max_pq`, `avg_pq`), the scene cuts, and the frame whose L1 sits furthest from the title's median, together with the `aetherctl play --dv-pin` spec that pins it (a host app passes the same spec to `armDolbyVisionPinTest`) for the on-device consumption test. Candidates rank on distance from the median across all three L1 fields, not `max_pq` alone. `--frames N` bounds the scan (default 2000) and `--list K` also dumps the first K frames. Exit codes: `0` ok, `1` probe error, `2` no RPUs, `3` no pin candidate, `4` the title's L1 range is too flat for a pinned frame to be visible on a panel.
+
+```bash
+swift run aetherctl dvsurvey --frames 6000 <p7-source>
+```
+
 ## pktdump
 
 Opens the demuxer under a selectable open profile, optionally seeks, and dumps raw video packet timing exactly as the demuxer delivers it (before any producer-side dts repair and before muxing): per-packet dts / pts / duration / keyframe flag samples, NOPTS and non-monotonic dts counts, and dts-delta / duration histograms. Also prints the resolved stream fields that `find_stream_info` fills (`avg_frame_rate`, `codecpar.video_delay`).
diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index 43647cd72..49476974d 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -202,7 +202,7 @@ reproduces the exact lock shape; against the old handler it hung past a 300 s ti
 
 ### 4.5 Consumption test assets
 
-`aetherctl dvsurvey` (in the tooling PR that follows this one) ranks frames by L1 distance from the title's median so that the pin test can
+`aetherctl dvsurvey` ranks frames by L1 distance from the title's median so that the pin test can
 pin a frame whose metadata is a large lie. On the three local test clips: a CMv4.0 4000-nit clip pins
 frame 247 (`max_pq` 4095 against a median of 2081, distance 3876, the best asset); a scene clip gives
 distance 1391, usable; a credits clip has static L1 (distance 0) and is correctly rejected as `WEAK`.
@@ -573,7 +573,7 @@ swift test --filter "Dovi|DualLayer|OrderedDelivery|FrameSideDataRing"
 | `DoviShaderSyncTests` | every kernel present, parameter block size, one pipeline per process |
 | `DoviRpuConverterTests` | NAL surgery, framing, degradation to HDR10 |
 
-**CLI** ([cli.md](cli.md); these subcommands arrive with the tooling PR that follows this one): `aetherctl feltest` (pixel and metadata verdicts, exit codes 0–5),
+**CLI** ([cli.md](cli.md)): `aetherctl feltest` (pixel and metadata verdicts, exit codes 0–5),
 `dvsurvey`, `dovitest`, and `play --cycle-el` to flip the residual on a timer.
 
 **Device.** With `DEVELOPER_DIR` pointing at an Xcode that has `devicectl`:
@@ -591,9 +591,9 @@ log stream --predicate 'subsystem == "de.superuser404.AetherEngine" AND category
 `info files` takes `--subdirectory` and accepts `--username`; `copy from` takes `--source` and rejects
 `--username`. The absence of a `JetsamEvent` for the day rules out a memory kill.
 
-**Consumption test** (the tooling and the pin hook arrive with the tooling PR that follows this one). Pick a pin with `aetherctl dvsurvey`, arm a DEBUG build with
+**Consumption test.** Pick a pin with `aetherctl dvsurvey`, arm a DEBUG build with
 `AetherEngine.armDolbyVisionPinTest("maxpq>=4095,period:2")` (an `@_spi(Diagnostics)` hook; on the
-Mac, `aetherctl play --dv-pin`) against that asset, and watch the panel with its own dynamic
+Mac, `aetherctl play --fel --surface --dv-pin`) against that asset, and watch the panel with its own dynamic
 picture processing switched off. The substitution happens after composition, so a visible pulse can
 only come from the metadata.
 
@@ -654,4 +654,4 @@ bit depths, and the display metadata (carried into the converted Profile 8.1 RPU
 | this file | design, implementation, evidence, verification |
 | [formats.md](formats.md#dolby-vision-signaling) | Profile 7 behaviour as a host sees it |
 | [api.md](api.md) | `preferDualLayerDolbyVision`, `dolbyVisionHandling` |
-| [cli.md](cli.md) | `feltest`, `dvsurvey`, `dovitest`, `play --cycle-el` (with the tooling PR) |
+| [cli.md](cli.md) | `feltest`, `dvsurvey`, `dovitest`, `play --cycle-el` |

From ef2a130758171ff8670b660e38a37231b5a639b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Santos?= <slotted.clean-0a@icloud.com>
Date: Wed, 14 Oct 2026 01:12:40 +0200
Subject: [PATCH 018/132] fix(errors): a refused live join says so, instead of
 reading as an unreadable source

When the live HLS ingest's playlist was refused at the join, the probe saw no bytes and the load
published customSourceProbeFailed, which a host reads as a stream it cannot play; one that falls back
to another route on it moved the channel there for the rest of its session, over a 509 an IPTV panel
gives while another device holds the account's last slot.

The load now publishes the origin's answer, as an HTTP reader's failed open does: sourceRateLimited
(429/503/509) or sourceRefused with the status in underlyingCode, or liveSourceUnavailable when the
playlist could not be reached. docs/api.md says so beside customSourceProbeFailed.

Tests: PlaybackErrorInfoTests (refused join for 509 and 403, unreachable join).
---
 CHANGELOG.md                                  |  8 +++
 Sources/AetherEngine/AetherEngine.swift       | 19 ++++-
 .../PlaybackErrorInfoTests.swift              | 72 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 4 files changed, 99 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c97a6da1d..66c1a7536 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,14 @@ the public-API contract.
   a fresh seal; the consumer item swaps to it in place, keeping source, cache, position (also behind
   live) and play/pause intent. A media playlist failure no longer counts as evidence against the HDR
   master (#748, thanks @yucelokan).
+- **A refused live join says so, instead of reading as an unreadable source.** When the live HLS
+  ingest's playlist was refused at the join, the probe saw no bytes and the load published
+  `customSourceProbeFailed`, which a host reads as a stream it cannot play: one that falls back to
+  another route on it moved the channel there for the rest of its session over a 509 an IPTV panel
+  gives while another device holds the account's last slot. The load now publishes the origin's
+  answer, as an HTTP reader's failed open does: `sourceRateLimited` (429/503/509) or `sourceRefused`
+  with the status in `underlyingCode`, or `liveSourceUnavailable` when the playlist could not be
+  reached.
 
 ## [7.36.0] - 2026-10-13
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5a5629242..eb203a469 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4548,7 +4548,24 @@ public final class AetherEngine: ObservableObject {
         }
 
         // Custom sources have no URL to reopen from: a failed probe is fatal.
-        if case .custom = source, !probeOpened {
+        if case .custom(let reader, _) = source, !probeOpened {
+            // The engine's own live HLS ingest knows why it handed the probe nothing: its playlist
+            // was refused or could not be reached. That is the source's answer, typed as an HTTP
+            // reader's is (`publishLoadFailure`), not a stream the probe could not read: a host that
+            // takes a custom probe failure to mean the format moves the channel to another route for
+            // good, over a 509 an IPTV panel gives while another device holds the account's last slot.
+            if let ingest = reader as? HLSLiveIngestReader,
+               case .playlistUnreachable(let status)? = ingest.terminalError {
+                if status > 0 {
+                    let kind: PlaybackErrorKind = AVIOReader.isRateLimitStatus(status) ? .sourceRateLimited : .sourceRefused
+                    publishError(PlaybackErrorInfo(kind: kind,
+                                                   message: "Failed to load: the live playlist answered HTTP \(status)",
+                                                   underlyingCode: status))
+                } else {
+                    publishError(.liveSourceUnavailable, "Failed to load: the live playlist could not be reached")
+                }
+                throw DemuxerError.openFailed(code: -1)
+            }
             publishError(.customSourceProbeFailed, "Failed to load: custom source probe failed", underlying: probeFailure)
             throw DemuxerError.openFailed(code: -1)
         }
diff --git a/Tests/AetherEngineTests/PlaybackErrorInfoTests.swift b/Tests/AetherEngineTests/PlaybackErrorInfoTests.swift
index 2e7da3b88..ba1d387cd 100644
--- a/Tests/AetherEngineTests/PlaybackErrorInfoTests.swift
+++ b/Tests/AetherEngineTests/PlaybackErrorInfoTests.swift
@@ -30,6 +30,78 @@ struct PlaybackErrorInfoTests {
         }
     }
 
+    @MainActor
+    @Test("A live HLS join the origin refuses publishes its answer, not a probe failure",
+          .timeLimit(.minutes(1)),
+          arguments: [(509, PlaybackErrorKind.sourceRateLimited), (403, .sourceRefused)])
+    func refusedLiveJoinPublishesTheOriginsAnswer(status: Int, kind: PlaybackErrorKind) async throws {
+        let origin = try #require(RefusingOrigin(status: status))
+        defer { origin.stop() }
+        let observed = try await failedLiveIngestLoad(
+            try #require(URL(string: "http://127.0.0.1:\(origin.port)/live/1.m3u8")))
+        #expect(observed?.kind == kind)
+        #expect(observed?.underlyingCode == status)
+    }
+
+    @MainActor
+    @Test("A live HLS join that reaches nothing publishes an unavailable live source", .timeLimit(.minutes(1)))
+    func unreachableLiveJoinIsUnavailable() async throws {
+        let observed = try await failedLiveIngestLoad(try #require(URL(string: "http://127.0.0.1:1/live/1.m3u8")))
+        #expect(observed?.kind == .liveSourceUnavailable)
+    }
+
+    /// Loads `url` live through the engine's own HLS ingest, as a known HLS playlist on the live path
+    /// is, and returns the failure the load published.
+    @MainActor
+    private func failedLiveIngestLoad(_ url: URL) async throws -> PlaybackErrorInfo? {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        var observed: PlaybackErrorInfo?
+        let token = engine.$state.sink { state in
+            if case .error = state { observed = engine.errorInfo }
+        }
+        defer { token.cancel() }
+        var options = LoadOptions()
+        options.isLive = true
+        do {
+            _ = try await engine.load(
+                source: .custom(HLSLiveIngestReader(playlistURL: url), formatHint: "mpegts"), options: options)
+            Issue.record("A refused live playlist must fail the load")
+        } catch {}
+        return observed
+    }
+
+    /// Answers every request with `status` and an empty body, one response per connection.
+    private final class RefusingOrigin: @unchecked Sendable {
+        let port: UInt16
+        private let listener: LoopbackListener
+
+        init?(status: Int) {
+            guard let listener = LoopbackListener(backlog: 8) else { return nil }
+            self.listener = listener
+            port = listener.port
+            listener.start { conn in
+                Thread.detachNewThread {
+                    defer { close(conn) }
+                    var request = Data()
+                    var buffer = [UInt8](repeating: 0, count: 4096)
+                    while request.range(of: Data("\r\n\r\n".utf8)) == nil {
+                        let n = read(conn, &buffer, buffer.count)
+                        guard n > 0 else { return }
+                        request.append(contentsOf: buffer[0..<n])
+                    }
+                    let response = "HTTP/1.1 \(status) Refused\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+                    _ = response.withCString { write(conn, $0, strlen($0)) }
+                }
+                return true
+            }
+        }
+
+        func stop() {
+            listener.stop()
+        }
+    }
+
     @Test("An underlying NSError contributes its domain and code")
     func capturesUnderlying() {
         let underlying = NSError(domain: "CoreMediaErrorDomain", code: -12939)
diff --git a/docs/api.md b/docs/api.md
index ceadecb95..7975a1d2a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -49,7 +49,7 @@ The message inside `.error` is worth logging verbatim, and it comes from two dif
 
 So the string is a payload, not a key, and `$errorInfo` is the key. It publishes a `PlaybackErrorInfo` beside the state: a `PlaybackErrorKind` naming what failed in a form that survives a locale and a release, plus the underlying `NSError` domain and code wherever a Foundation / AVFoundation failure is involved. A non-nil `underlyingDomain` also marks the messages whose text the OS has localized.
 
-A failed custom-source probe publishes `.customSourceProbeFailed` with the probe error's `underlyingDomain` and `underlyingCode` when available. That information is set before the terminal `.error` state is delivered, so a state observer can read the cause from `errorInfo` without parsing the message.
+A failed custom-source probe publishes `.customSourceProbeFailed` with the probe error's `underlyingDomain` and `underlyingCode` when available. That information is set before the terminal `.error` state is delivered, so a state observer can read the cause from `errorInfo` without parsing the message. The engine's own live HLS ingest (`HLSLiveIngestReader`, which a known HLS playlist URL on the live path loads through) is the exception: when the probe failed because the live playlist was refused, the load publishes the origin's answer the way an HTTP reader's failed open does, `.sourceRateLimited` (429/503/509) or `.sourceRefused` with the status in `underlyingCode`, and `.liveSourceUnavailable` when the playlist could not be reached at all, so a host does not read a refusal as a stream it cannot play.
 
 Two kinds carry a number a host will want to read, and both mean the same thing happened: the origin answered the source request with an HTTP status instead of media, and `underlyingCode` is that status. `.sourceRefused` is the origin's verdict on the resource or on itself (a 401/403 refusal, which on a connection-capped IPTV panel most often means "the slot is still held", a 404, a 5xx). `.sourceRateLimited` is the same answer in the rate-limit shapes (429/503/509), split off because the recovery differs: the source is being metered, not lost, so the same request is expected to work later and a handoff to a second player meets the same meter (AE#377). Both are distinct from `.sourceOpenFailed`, which is what a corrupt or unreadable source produces; before `.sourceRefused` existed a refusal and a corrupt file arrived alike as "Invalid data found when processing input".
 

From c886baf8669cdd185e21026b51c6865fafd9327d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Santos?= <slotted.clean-0a@icloud.com>
Date: Wed, 14 Oct 2026 01:10:21 +0200
Subject: [PATCH 019/132] fix(live): the HLS ingest rides out an origin's
 refusals instead of ending the session

An IPTV panel that limits an account's connections answers a live playlist refresh with 509 while
another device holds the last slot, and goes on refusing a session it evicted while a fresh session
from the loaded URL is admitted at once. The ingest retried 1, 2 and 4 s apart and went terminal at
12 s (on the software path, the end of the session), and each refusal armed the origin's request
pacer, so the host's reload waited up to 10 s for its first request.

- A refused or unreachable refresh (429, 5xx, transport) is asked again every second, or after the
  origin's Retry-After up to 5 s, for up to 60 s; a refused segment likewise, after its two quick
  retries.
- A session URL the loaded URL led to through redirects is asked for afresh through the loaded URL
  once refused twice in a row, or at once when it answers as gone (a 4xx other than 429 and 408).
  The tracker follows MEDIA-SEQUENCE, so the segments continue where they left off.
- The live ingest's refusals no longer arm OriginRequestBudget's pacer or lower its request budget;
  a ceiling the host declares or another path learns still binds it.

Tests: HLSLiveIngestRefusalTests.
---
 CHANGELOG.md                                  |  12 +
 .../IO/HLSIngest/HLSLiveIngestReader.swift    | 174 +++++++--
 .../HLSLiveIngestRefusalTests.swift           | 346 ++++++++++++++++++
 3 files changed, 499 insertions(+), 33 deletions(-)
 create mode 100644 Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c97a6da1d..0ec570781 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,18 @@ the public-API contract.
 
 ### Fixed
 
+- **A live HLS source refused for a while keeps its session.** An IPTV panel that limits an account's
+  connections answers a live playlist refresh with 509 while another device holds the last slot, and
+  goes on refusing a session it evicted, while a fresh session from the loaded URL is admitted at
+  once. The ingest retried 1, 2 and 4 s apart and went terminal at 12 s, which on the software path
+  ended the session, and each refusal armed the origin's request pacer, so the host's reload then
+  waited up to 10 s for its first request. A refused or unreachable refresh is now asked again every
+  second, or after the origin's Retry-After up to 5 s, for up to 60 s, and so is a refused segment. A
+  session URL the loaded URL led to through redirects is asked for afresh through the loaded URL once
+  it has been refused twice, or at once when it answers as gone (a 4xx other than 429 and 408); the
+  playlist tracker follows MEDIA-SEQUENCE, so the segments continue where they left off. The live
+  ingest's refusals no longer arm the pacer or lower the origin's request budget; its own steady retry
+  is its pacing, and a ceiling the host declares or another path learns still binds it.
 - **A live GOP longer than the sealed target duration no longer breaks the playlist.** RFC 8216 keeps
   `TARGETDURATION` fixed for a playlist's life, so a later segment above it made the playlist invalid
   for AVPlayer (-12642). The engine now retires that playlist URL with its original target and an
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index aa7e63ec9..9880a3b9c 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -56,6 +56,8 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     /// "mpegts" or "aac", classified from the first segment's leading bytes, written before that segment's first FIFO byte.
     private var _segmentFormatHint: String?
     private var _packedAudioTimestampOffset90k: Int64?
+    /// The Retry-After of the last refused playlist request, taken by the refresh loop as it waits.
+    private var _playlistRetryAfter: TimeInterval?
 
     /// `formatResolved` flips after classification OR on any ingest exit, so `resolveSegmentFormatHint` never outwait a dead ingest.
     private let formatCondition = NSCondition()
@@ -282,7 +284,11 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
             wakeFormatResolveWaiters() // wake any pending format resolve regardless of exit path
         }
         do {
-            let (mediaURL, seedPlaylist) = try await resolveMediaPlaylistURL()
+            let (resolvedURL, seedPlaylist) = try await resolveMediaPlaylistURL()
+            var mediaURL = resolvedURL
+            // A media playlist the host's URL led to directly (through redirects, as an IPTV panel's
+            // tokenized session URL), which that URL can lead to afresh when the session expires.
+            let mediaURLIsReresolvable = seedPlaylist != nil && mediaURL != playlistURL
             var tracker = HLSPlaylistTracker()
             var loggedEncryptedDirectPlay = false
             var refreshInterval: Double = 2
@@ -294,10 +300,9 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     media = seeded // reuse playlist parsed during resolve to avoid a redundant fetch
                     pendingPlaylist = nil
                 } else {
-                    let (playlist, _) = try await fetchPlaylistWithRetry(mediaURL)
-                    guard case .media(let fetched) = playlist else {
-                        throw HLSIngestError.playlistInvalid(reason: "expected media playlist on refresh")
-                    }
+                    let (fetched, refreshedURL) = try await refreshMediaPlaylist(
+                        mediaURL, canReresolve: mediaURLIsReresolvable)
+                    mediaURL = refreshedURL
                     media = fetched
                 }
                 startLock.withLock { // publish before any segment byte reaches the FIFO; first write wins
@@ -580,46 +585,135 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         }
     }
 
-    /// 12s: FIFO + producer buffer give ~10-20s slack; past that, going terminal beats stretching a stall the buffer can no longer hide.
-    private static let refreshRetryBudget: TimeInterval = 12
-
-    /// Playlist refresh with bounded exponential backoff (1s, 2s, 4s). Device repro: a single -1001 CDN timeout used to force a visible ~10s retune; now bridged invisibly inside `refreshRetryBudget`. Parse errors and 4xx throw immediately. Initial join stays single-shot (fast spinner fallback beats slow retry).
-    private func fetchPlaylistWithRetry(_ url: URL) async throws -> (HLSPlaylist, URL) {
-        let deadline = Date().addingTimeInterval(Self.refreshRetryBudget)
-        var attempt = 0
+    /// How long a live refresh is retried while the origin refuses it (429, 5xx including 509) or
+    /// cannot be reached. It outlasts what a session holds ahead of the playhead, so a refusal that
+    /// ends while the picture is still playing from it is never seen: the host's own stall handling
+    /// steps in once that runs dry. A connection-limited IPTV panel answers 509 for as long as another
+    /// device on the account holds its last slot, which is seconds to tens of seconds when that device
+    /// changes channels, and then serves again at once. The 7.36.0 ladder (1, 2, 4 s within 12 s) went
+    /// terminal well inside such a window, and on the software path that ended the session.
+    static let refreshRetryBudget: TimeInterval = 60
+
+    /// The steady wait between those retries. One small request a second, never growing: a refusal of
+    /// this kind lifts the moment the other device lets its slot go, and a growing backoff only adds
+    /// to the wait after that. An origin's own Retry-After stretches it, up to `maximumRetryWait`.
+    static let refusedRefreshRetryInterval: TimeInterval = 1
+    static let maximumRetryWait: TimeInterval = 5
+
+    /// Failed refreshes that are each logged; past these, one line every `retryLogStride`.
+    private static let loggedRetries = 3
+    private static let retryLogStride = 10
+
+    /// Refusals of a session URL after which it is asked for again through the URL the host loaded.
+    /// An IPTV panel that let another device's connection take the account's last slot keeps refusing
+    /// the session it evicted, for as long as that lasts, while a fresh session from the loaded URL is
+    /// admitted at once. Two lets a refusal that lifts by itself within a second or two keep the
+    /// session it has.
+    static let sessionURLRefusalsBeforeReresolve = 2
+
+    /// The live refresh, retried steadily while the origin refuses it or cannot be reached. When the
+    /// URL the host loaded led to this media playlist through redirects (`canReresolve`: an IPTV
+    /// panel's tokenized session URL), a playlist that answers as gone (a 4xx other than 429 and 408:
+    /// the session expired or was revoked) is asked for again through the loaded URL at once, and one
+    /// refused `sessionURLRefusalsBeforeReresolve` times in a row after that, for a fresh session URL;
+    /// the loaded URL is then asked at the same steady pace. The playlist tracker follows
+    /// MEDIA-SEQUENCE, so the segments it hands out continue where they left off. Parse errors throw at
+    /// once. Returns the playlist and the URL it was read from, which later refreshes use.
+    private func refreshMediaPlaylist(_ mediaURL: URL, canReresolve: Bool) async throws -> (HLSMediaPlaylist, URL) {
+        let startedAt = Date()
+        let deadline = startedAt.addingTimeInterval(Self.refreshRetryBudget)
+        var url = mediaURL
+        var failures = 0
         while true {
             try Task.checkCancellation()
             do {
-                return try await fetchPlaylist(url)
+                let (playlist, finalURL) = try await fetchPlaylist(url)
+                guard case .media(let media) = playlist else {
+                    throw HLSIngestError.playlistInvalid(reason: "expected media playlist on refresh")
+                }
+                if failures > 0 || url != mediaURL {
+                    EngineLog.emit(
+                        "[HLSIngest] playlist refresh recovered after \(failures) failed attempt(s) in "
+                        + "\(String(format: "%.1f", Date().timeIntervalSince(startedAt)))s"
+                        + (url != mediaURL ? " through the loaded URL" : ""),
+                        category: .engine
+                    )
+                }
+                return (media, finalURL)
             } catch let error as HLSIngestError {
-                guard case .playlistUnreachable(let status) = error,
-                      status >= 500 || status == 429 else {
-                    throw error
+                guard case .playlistUnreachable(let status) = error else { throw error }
+                if Self.isGoneStatus(status) {
+                    guard canReresolve, url == mediaURL else { throw error }
+                    EngineLog.emit(
+                        "[HLSIngest] media playlist answered \(status); asking the loaded URL for a fresh one",
+                        category: .engine
+                    )
+                    url = playlistURL
+                    continue
                 }
-                try await backoffOrRethrow(error, attempt: &attempt, deadline: deadline)
+                failures += 1
+                try await waitBeforeRetrying(error, failures: failures, deadline: deadline)
+                url = Self.nextRefreshURL(after: failures, current: url, sessionURL: mediaURL,
+                                          loadedURL: playlistURL, canReresolve: canReresolve)
             } catch is CancellationError {
                 throw CancellationError()
             } catch {
                 if (error as? URLError)?.code == .cancelled { throw error }
-                try await backoffOrRethrow(error, attempt: &attempt, deadline: deadline)
+                failures += 1
+                try await waitBeforeRetrying(error, failures: failures, deadline: deadline)
+                url = Self.nextRefreshURL(after: failures, current: url, sessionURL: mediaURL,
+                                          loadedURL: playlistURL, canReresolve: canReresolve)
             }
         }
     }
 
-    private func backoffOrRethrow(_ error: Error, attempt: inout Int, deadline: Date) async throws {
-        attempt += 1
-        let delay = min(4.0, pow(2.0, Double(attempt - 1)))
-        guard Date().addingTimeInterval(delay) < deadline else { throw error }
+    /// Where the next refresh goes after `failures` in a row: the loaded URL, for a fresh session,
+    /// once the session URL has been refused `sessionURLRefusalsBeforeReresolve` times; otherwise
+    /// where the last one went.
+    static func nextRefreshURL(after failures: Int, current: URL, sessionURL: URL, loadedURL: URL,
+                               canReresolve: Bool) -> URL {
+        guard canReresolve, current == sessionURL, failures >= sessionURLRefusalsBeforeReresolve else {
+            return current
+        }
         EngineLog.emit(
-            "[HLSIngest] playlist refresh failed (attempt \(attempt): \(error.localizedDescription)); retrying in \(Int(delay))s",
+            "[HLSIngest] session URL refused \(failures) times; asking the loaded URL for a fresh one",
             category: .engine
         )
+        return loadedURL
+    }
+
+    /// A status that says the playlist will not be served at this URL again, rather than not now:
+    /// any 4xx but 429 (Too Many Requests) and 408 (Request Timeout).
+    static func isGoneStatus(_ status: Int) -> Bool {
+        (400..<500).contains(status) && status != 429 && status != 408
+    }
+
+    /// The wait before the next retry, or the error once the budget would be overrun.
+    static func retryWait(retryAfter: TimeInterval?) -> TimeInterval {
+        min(max(retryAfter ?? refusedRefreshRetryInterval, refusedRefreshRetryInterval), maximumRetryWait)
+    }
+
+    private func waitBeforeRetrying(_ error: Error, failures: Int, deadline: Date) async throws {
+        let retryAfter = startLock.withLock { () -> TimeInterval? in
+            defer { _playlistRetryAfter = nil }
+            return _playlistRetryAfter
+        }
+        let delay = Self.retryWait(retryAfter: retryAfter)
+        guard Date().addingTimeInterval(delay) < deadline else { throw error }
+        if failures <= Self.loggedRetries || failures % Self.retryLogStride == 0 {
+            EngineLog.emit(
+                "[HLSIngest] playlist refresh failed (attempt \(failures): \(EngineLog.summary(of: error))); "
+                + "retrying in \(String(format: "%.1f", delay))s",
+                category: .engine
+            )
+        }
         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.
+    /// so the host's declared ceiling, and a ceiling or pacer learned from another path's refusal, bind
+    /// this path too. Its own refusals are not charged (see below). 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) {
@@ -637,10 +731,15 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
             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))
+            // A refusal here is not charged to the origin's books. A live ingest asks at most once a
+            // second while refused (`refusedRefreshRetryInterval`), and a connection-limited IPTV panel
+            // refuses on behalf of another device holding the account's last slot, not of our request
+            // rate. Charged, its 509 armed a quiet period of up to 15 s and halved the request budget
+            // for the rest of the process, so the refresh that would have been served the moment the
+            // slot freed, and every reopen or reload after it, waited up to 10 s for the pacer instead.
+            if Self.refusalStatuses.contains(http.statusCode), label == "ingest-playlist" {
+                let retryAfter = http.value(forHTTPHeaderField: "Retry-After").flatMap(TimeInterval.init)
+                startLock.withLock { _playlistRetryAfter = retryAfter }
             }
         }
         return (data, response)
@@ -681,8 +780,11 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     private func fetchSegment(_ url: URL, duration: Double) async throws -> Data {
         var lastStatus = -1
         let limit = BoundedFetch.segmentLimit(forDuration: duration)
-        for attempt in 0..<3 {
+        let deadline = Date().addingTimeInterval(Self.refreshRetryBudget)
+        var attempt = 0
+        while true {
             if Task.isCancelled { throw CancellationError() }
+            var retryAfter: TimeInterval?
             do {
                 let (data, response): (Data, URLResponse)
                 do {
@@ -699,13 +801,19 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                 if (400..<500).contains(lastStatus) && lastStatus != 429 {
                     throw HLSIngestError.playlistUnreachable(status: lastStatus)
                 }
+                retryAfter = (response as? HTTPURLResponse)?
+                    .value(forHTTPHeaderField: "Retry-After").flatMap(TimeInterval.init)
             } catch let error as HLSIngestError { throw error }
             catch { /* transport blip: retry */ }
-            if attempt < 2 {
-                try await Task.sleep(nanoseconds: UInt64(0.5 * Double(attempt + 1) * 1_000_000_000))
+            attempt += 1
+            // Two quick retries for a blip, as before; then the steady pace of a refused refresh,
+            // for as long as the refresh itself would keep trying.
+            let delay = attempt <= 2 ? 0.5 * Double(attempt) : Self.retryWait(retryAfter: retryAfter)
+            guard Date().addingTimeInterval(delay) < deadline else {
+                throw HLSIngestError.playlistUnreachable(status: lastStatus)
             }
+            try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
         }
-        throw HLSIngestError.playlistUnreachable(status: lastStatus)
     }
 
     private func decryptSegment(_ ciphertext: Data, crypt: HLSSegmentCrypt, against base: URL) async throws -> Data {
diff --git a/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift b/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift
new file mode 100644
index 000000000..32f0f3d57
--- /dev/null
+++ b/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift
@@ -0,0 +1,346 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// A live HLS source refused for a while, as a connection-limited IPTV panel refuses an account's
+/// sessions with 509 while another device holds its last slot, keeps its session: the ingest asks
+/// again every second and carries on the moment it is served, and the refusals arm no pacer, which
+/// would hold the requests after them. A session URL the panel keeps refusing, or revoked, is asked
+/// for afresh through the URL the host loaded.
+@Suite("Live HLS ingest rides out refusals", .offCooperativePool, .timeLimit(.minutes(2)))
+struct HLSLiveIngestRefusalTests {
+
+    // MARK: - Loopback origin
+
+    /// One HTTP/1.1 response per connection (Connection: close), scripted per request.
+    private final class ScriptedOrigin: @unchecked Sendable {
+        struct Response {
+            var status: Int
+            var headers: [String: String] = [:]
+            var body = Data()
+        }
+
+        let port: UInt16
+        private let listener: LoopbackListener
+        private let respond: @Sendable (_ path: String, _ index: Int) -> Response
+        private let lock = NSLock()
+        private var counts: [String: Int] = [:]
+
+        /// `respond` gets each request's path and how many requests for that path came before it.
+        init?(respond: @escaping @Sendable (_ path: String, _ index: Int) -> Response) {
+            self.respond = respond
+            guard let listener = LoopbackListener(backlog: 16) else { return nil }
+            self.listener = listener
+            port = listener.port
+            listener.start { [weak self] conn in
+                guard let self else { close(conn); return false }
+                Thread.detachNewThread { [weak self] in
+                    self?.serve(conn)
+                }
+                return true
+            }
+        }
+
+        func stop() {
+            listener.stop()
+        }
+
+        func requestCount(_ path: String) -> Int {
+            lock.withLock { counts[path] ?? 0 }
+        }
+
+        func url(_ path: String) -> URL {
+            URL(string: "http://127.0.0.1:\(port)\(path)")!
+        }
+
+        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 requestLine = head.components(separatedBy: "\r\n").first else { return }
+            let parts = requestLine.components(separatedBy: " ")
+            guard parts.count >= 2 else { return }
+            let path = parts[1]
+
+            let index: Int = lock.withLock {
+                let index = counts[path] ?? 0
+                counts[path] = index + 1
+                return index
+            }
+            let response = respond(path, index)
+            var header = "HTTP/1.1 \(response.status) \(response.status == 200 ? "OK" : "Status")\r\n"
+            for (field, value) in response.headers {
+                header += "\(field): \(value)\r\n"
+            }
+            header += "Content-Length: \(response.body.count)\r\nConnection: close\r\n\r\n"
+            _ = header.withCString { write(conn, $0, strlen($0)) }
+            response.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
+                }
+            }
+        }
+    }
+
+    // MARK: - Media
+
+    /// Valid sync bytes at 188-byte cadence, the payload stamped with the segment's index, so the
+    /// order the bytes leave the FIFO in is checkable.
+    private static func segment(_ index: Int) -> Data {
+        var data = Data(capacity: 4 * 188)
+        for packet in 0..<4 {
+            var ts = [UInt8](repeating: UInt8(truncatingIfNeeded: index), count: 188)
+            ts[0] = 0x47
+            ts[1] = UInt8(truncatingIfNeeded: packet)
+            data.append(contentsOf: ts)
+        }
+        return data
+    }
+
+    /// 1 s segments `0..<count`, segment URIs relative to the playlist.
+    private static func playlist(count: Int, endList: Bool) -> Data {
+        var lines = ["#EXTM3U", "#EXT-X-VERSION:3", "#EXT-X-TARGETDURATION:1", "#EXT-X-MEDIA-SEQUENCE:0"]
+        for index in 0..<count {
+            lines.append("#EXTINF:1.0,")
+            lines.append("seg\(index).ts")
+        }
+        if endList { lines.append("#EXT-X-ENDLIST") }
+        return Data(lines.joined(separator: "\n").utf8)
+    }
+
+    private static func segmentIndex(_ path: String) -> Int? {
+        guard let name = path.components(separatedBy: "/").last,
+              name.hasPrefix("seg"), name.hasSuffix(".ts") else { return nil }
+        return Int(name.dropFirst(3).dropLast(3))
+    }
+
+    /// Everything the reader hands out until EOF or `expectedBytes`. No deadline of its own; the
+    /// suite's `.timeLimit` catches a hang (see `TestWaiting`).
+    private func drain(_ reader: HLSLiveIngestReader, expectedBytes: Int) async throws -> Data {
+        final class Box: @unchecked Sendable {
+            let lock = NSLock()
+            var data = Data()
+            var done = false
+        }
+        let box = Box()
+        Thread.detachNewThread {
+            var buf = [UInt8](repeating: 0, count: 32 * 1024)
+            while true {
+                let n = buf.withUnsafeMutableBufferPointer {
+                    reader.read($0.baseAddress, size: Int32($0.count))
+                }
+                if n <= 0 { break }
+                box.lock.lock()
+                box.data.append(contentsOf: buf[0..<Int(n)])
+                let enough = box.data.count >= expectedBytes
+                box.lock.unlock()
+                if enough { break }
+            }
+            box.lock.withLock { box.done = true }
+        }
+        try await waitFor { box.lock.withLock { box.done } }
+        return box.lock.withLock { box.data }
+    }
+
+    // MARK: - Tests
+
+    @Test("a refused refresh is asked again until it is served, and arms no pacer")
+    func refusedRefreshRetriesSteadily() async throws {
+        // The join reads seg0..7 and takes seg1..7; the next four refreshes are refused with 509, as
+        // a panel refuses while another device holds the account's last slot; the fifth lists
+        // seg0..15 with ENDLIST. The 7.36.0 ladder waited 1, 2 and 4 s between them, and its 12 s
+        // budget had no room for the fifth.
+        let refusals = 4
+        let origin = try #require(ScriptedOrigin { path, index in
+            if path == "/media.m3u8" {
+                switch index {
+                case 0: return .init(status: 200, body: Self.playlist(count: 8, endList: false))
+                case 1...refusals: return .init(status: 509)
+                default: return .init(status: 200, body: Self.playlist(count: 16, endList: true))
+                }
+            }
+            if let segment = Self.segmentIndex(path) { return .init(status: 200, body: Self.segment(segment)) }
+            return .init(status: 404)
+        })
+        defer { origin.stop() }
+
+        let url = origin.url("/media.m3u8")
+        let reader = HLSLiveIngestReader(playlistURL: url)
+        defer { reader.close() }
+        #expect(reader.resolveSegmentFormatHint() == "mpegts")
+
+        let expected = (1..<16).map(Self.segment).reduce(Data(), +)
+        let got = try await drain(reader, expectedBytes: expected.count)
+
+        #expect(reader.terminalError == nil)
+        #expect(got == expected)
+        #expect(origin.requestCount("/media.m3u8") == refusals + 2)
+        // The refusals were not charged to the origin, so nothing after them waits on a pacer.
+        #expect(!OriginRequestBudget.shared.isPaced(url))
+    }
+
+    @Test("a refused segment is fetched again at the same pace")
+    func refusedSegmentRetriesSteadily() async throws {
+        // seg9 is refused four times before it is served. The 7.36.0 fetch made three attempts and
+        // went terminal.
+        let refusals = 4
+        let origin = try #require(ScriptedOrigin { path, index in
+            if path == "/media.m3u8" {
+                return .init(status: 200, body: Self.playlist(count: index == 0 ? 8 : 16, endList: index > 0))
+            }
+            if let segment = Self.segmentIndex(path) {
+                if segment == 9, index < refusals { return .init(status: 509) }
+                return .init(status: 200, body: Self.segment(segment))
+            }
+            return .init(status: 404)
+        })
+        defer { origin.stop() }
+
+        let url = origin.url("/media.m3u8")
+        let reader = HLSLiveIngestReader(playlistURL: url)
+        defer { reader.close() }
+
+        let expected = (1..<16).map(Self.segment).reduce(Data(), +)
+        let got = try await drain(reader, expectedBytes: expected.count)
+
+        #expect(reader.terminalError == nil)
+        #expect(got == expected)
+        #expect(origin.requestCount("/seg9.ts") == refusals + 1)
+        #expect(!OriginRequestBudget.shared.isPaced(url))
+    }
+
+    @Test("a session URL that stays refused is asked for again through the loaded URL")
+    func refusedSessionURLIsResolvedAfresh() async throws {
+        // The loaded URL redirects to a session URL, as an IPTV panel's does. Once another device
+        // has taken the account's last slot, the panel goes on refusing the session it evicted with
+        // 509, while a fresh session from the loaded URL is admitted at once.
+        let origin = try #require(ScriptedOrigin { path, index in
+            switch path {
+            case "/live/1.m3u8":
+                return .init(status: 302, headers: ["Location": "/hls/session\(index + 1)/media.m3u8"])
+            case "/hls/session1/media.m3u8":
+                return index == 0
+                    ? .init(status: 200, body: Self.playlist(count: 8, endList: false))
+                    : .init(status: 509)
+            case "/hls/session2/media.m3u8":
+                return .init(status: 200, body: Self.playlist(count: 16, endList: true))
+            default:
+                if let segment = Self.segmentIndex(path) { return .init(status: 200, body: Self.segment(segment)) }
+                return .init(status: 404)
+            }
+        })
+        defer { origin.stop() }
+
+        let url = origin.url("/live/1.m3u8")
+        let reader = HLSLiveIngestReader(playlistURL: url)
+        defer { reader.close() }
+
+        let expected = (1..<16).map(Self.segment).reduce(Data(), +)
+        let got = try await drain(reader, expectedBytes: expected.count)
+
+        #expect(reader.terminalError == nil)
+        #expect(got == expected)
+        #expect(origin.requestCount("/hls/session1/media.m3u8")
+                == 1 + HLSLiveIngestReader.sessionURLRefusalsBeforeReresolve)
+        #expect(origin.requestCount("/live/1.m3u8") == 2)
+        #expect(origin.requestCount("/hls/session2/seg15.ts") == 1)
+        #expect(!OriginRequestBudget.shared.isPaced(url))
+    }
+
+    @Test("a revoked session URL is asked for again through the loaded URL")
+    func revokedSessionURLIsResolvedAfresh() async throws {
+        // The loaded URL redirects to a session URL, as an IPTV panel's does. The first session's
+        // playlist then answers 403, revoked; the loaded URL hands out a second session, whose
+        // playlist lists on with ENDLIST, and whose segments resolve against it.
+        let origin = try #require(ScriptedOrigin { path, index in
+            switch path {
+            case "/live/1.m3u8":
+                return .init(status: 302, headers: ["Location": "/hls/session\(index + 1)/media.m3u8"])
+            case "/hls/session1/media.m3u8":
+                return index == 0
+                    ? .init(status: 200, body: Self.playlist(count: 8, endList: false))
+                    : .init(status: 403)
+            case "/hls/session2/media.m3u8":
+                return .init(status: 200, body: Self.playlist(count: 16, endList: true))
+            default:
+                if let segment = Self.segmentIndex(path) { return .init(status: 200, body: Self.segment(segment)) }
+                return .init(status: 404)
+            }
+        })
+        defer { origin.stop() }
+
+        let reader = HLSLiveIngestReader(playlistURL: origin.url("/live/1.m3u8"))
+        defer { reader.close() }
+
+        let expected = (1..<16).map(Self.segment).reduce(Data(), +)
+        let got = try await drain(reader, expectedBytes: expected.count)
+
+        #expect(reader.terminalError == nil)
+        #expect(got == expected)
+        #expect(origin.requestCount("/live/1.m3u8") == 2)
+        #expect(origin.requestCount("/hls/session1/media.m3u8") == 2)
+        #expect(origin.requestCount("/hls/session2/media.m3u8") == 1)
+        // The second session's segments were fetched from it.
+        #expect(origin.requestCount("/hls/session2/seg15.ts") == 1)
+    }
+
+    @Test("a source without a separate session URL still ends on a gone playlist")
+    func goneDirectPlaylistIsTerminal() async throws {
+        let origin = try #require(ScriptedOrigin { path, index in
+            if path == "/media.m3u8" {
+                return index == 0
+                    ? .init(status: 200, body: Self.playlist(count: 8, endList: false))
+                    : .init(status: 404)
+            }
+            if let segment = Self.segmentIndex(path) { return .init(status: 200, body: Self.segment(segment)) }
+            return .init(status: 404)
+        })
+        defer { origin.stop() }
+
+        let reader = HLSLiveIngestReader(playlistURL: origin.url("/media.m3u8"))
+        defer { reader.close() }
+
+        let joined = (1..<8).map(Self.segment).reduce(Data(), +)
+        _ = try await drain(reader, expectedBytes: joined.count + 1)
+        #expect(reader.terminalError == .playlistUnreachable(status: 404))
+        #expect(origin.requestCount("/media.m3u8") == 2)
+    }
+
+    @Test("the wait between retries is a second, or what the origin asks for up to five")
+    func retryWaits() {
+        #expect(HLSLiveIngestReader.retryWait(retryAfter: nil) == 1)
+        #expect(HLSLiveIngestReader.retryWait(retryAfter: 0) == 1)
+        #expect(HLSLiveIngestReader.retryWait(retryAfter: 3) == 3)
+        #expect(HLSLiveIngestReader.retryWait(retryAfter: 120) == 5)
+        #expect(HLSLiveIngestReader.isGoneStatus(403))
+        #expect(HLSLiveIngestReader.isGoneStatus(404))
+        #expect(!HLSLiveIngestReader.isGoneStatus(429))
+        #expect(!HLSLiveIngestReader.isGoneStatus(408))
+        #expect(!HLSLiveIngestReader.isGoneStatus(509))
+        #expect(!HLSLiveIngestReader.isGoneStatus(503))
+    }
+
+    @Test("a refused session URL gives way to the loaded URL after two refusals, and only a session URL does")
+    func refreshURLChoice() {
+        let session = URL(string: "http://127.0.0.1:1/hls/s1/media.m3u8")!
+        let loaded = URL(string: "http://127.0.0.1:1/live/1.m3u8")!
+        func next(_ failures: Int, from current: URL, canReresolve: Bool = true) -> URL {
+            HLSLiveIngestReader.nextRefreshURL(after: failures, current: current, sessionURL: session,
+                                               loadedURL: loaded, canReresolve: canReresolve)
+        }
+        #expect(next(1, from: session) == session)
+        #expect(next(2, from: session) == loaded)
+        #expect(next(5, from: loaded) == loaded)
+        #expect(next(9, from: session, canReresolve: false) == session)
+    }
+}

From 7acbf23343626f9ce87a5114c273e2898a4f1556 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Santos?= <slotted.clean-0a@icloud.com>
Date: Wed, 14 Oct 2026 02:46:16 +0200
Subject: [PATCH 020/132] fix(airplay): a live session on the HLS ingest moves
 to the receiver by swapping its item

The wireless-AirPlay route change rebuilt the session to serve it on the device's LAN
address. A live session on the HLS ingest stands on a forward-only custom source, whose
rebuild is refused (#526), and the refusal was dropped: the receiver stayed on 127.0.0.1,
which it cannot reach, and played nothing while the sender reported external playback.

Such a session now swaps the player's item onto the receiver's address, and back onto the
loopback when the receiver lets go, as a sequential origin already did. The session, its
ingest and its segment cache carry on, so the source is asked for nothing again. The
swapped item rejoins its live playlist at the player's join point, as a live reload does.
On-demand sessions cross as before.

AirPlayPlaylistDecision.routeChangeHop decides which sessions swap, with tests.
docs/formats.md (Wireless AirPlay) and docs/architecture.md say how each kind crosses.
---
 CHANGELOG.md                                  | 10 +++++
 Sources/AetherEngine/AetherEngine.swift       | 43 +++++++++++++------
 .../Native/AirPlayPlaylistDecision.swift      | 23 ++++++++++
 .../AirPlayPlaylistDecisionTests.swift        | 25 +++++++++++
 docs/architecture.md                          |  2 +-
 docs/formats.md                               |  2 +-
 6 files changed, 90 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c97a6da1d..685465a7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,16 @@ the public-API contract.
   live) and play/pause intent. A media playlist failure no longer counts as evidence against the HDR
   master (#748, thanks @yucelokan).
 
+- **A live channel on the HLS ingest follows a wireless AirPlay route change.** The ingest hands the
+  pipeline a forward-only custom source, and the route change rebuilt the session to serve it on the
+  device's LAN address. That rebuild is refused for such a source (#526) and the refusal was dropped,
+  so the receiver stayed on 127.0.0.1, which it cannot reach, and played nothing while the sender
+  reported external playback. The route change now swaps the player's item onto the receiver's
+  address (and back onto the loopback when the receiver lets go), as it already did for a sequential
+  origin. The session, its ingest and its segment cache carry on, so the source is asked for nothing
+  again; the swapped item rejoins its live playlist at the player's join point, as a live reload does
+  (`AirPlayPlaylistDecision.routeChangeHop`).
+
 ## [7.36.0] - 2026-10-13
 
 ### Added
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5a5629242..934414f93 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -6836,28 +6836,45 @@ public final class AetherEngine: ObservableObject {
         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).
+    /// A session that cannot be reopened where it is crosses an AirPlay edge by swapping the item, not by
+    /// rebuilding the session (`AirPlayPlaylistDecision.routeChangeHop`). Nothing about the session has to
+    /// change for the hop. 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).
+    ///
+    /// - A sequential origin 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. It resumes at the playhead.
+    /// - A live session on a forward-only custom source (the live HLS ingest) cannot be rebuilt at all, so
+    ///   the reload was refused (#526) and the receiver stayed on an address it cannot reach. It rejoins its
+    ///   own live playlist the way a live reload does (`LiveReloadPolicy`): the player picks the join point.
     @MainActor
     private func swapsItemForAirPlayEdge() -> Bool {
-        guard loadedOptions.sequentialOrigin, !loadedOptions.isLive, !loadedOptions.nativeRemoteHLS,
+        let hop = AirPlayPlaylistDecision.routeChangeHop(
+            sequentialOrigin: loadedOptions.sequentialOrigin,
+            isLive: loadedOptions.isLive,
+            isCustomSource: isCustomSource,
+            customSourceIsSeekable: customSourceIsSeekable)
+        guard hop == .swapItem, !loadedOptions.nativeRemoteHLS,
               let host = nativeHost, let session = nativeVideoSession,
               let loopback = session.servingMasterPlaylist
                 ? session.masterPlaylistURL : session.mediaPlaylistURL else { return false }
-        let position = currentTime
+        // Live: no position, as for any live rejoin (a playhead taken here would be on the outgoing
+        // item's axis). On demand: the playhead, as the sequential hop always did.
+        let position: Double? = loadedOptions.isLive ? nil : currentTime
         let served = airPlayAdjustedPlayback(url: loopback, session: session)
         nativeSubtitleRenditionsServed = served.subtitleRenditionsServed
+        let reason = loadedOptions.isLive
+            ? "a live session on a forward-only source cannot be rebuilt, #526"
+            : "the source cannot be reopened past byte 0"
         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)",
+            "[AirPlay] external playback \(airPlayActive ? "active (wireless)" : "ended") -> item swap to "
+            + "\(served.url.absoluteString) "
+            + (position.map { "at \(String(format: "%.2f", $0))s" } ?? "at the player's live join point")
+            + " (\(reason))",
             category: .engine)
-        host.swapItem(url: served.url, startPosition: position)
-        armAirPlayProgressWatchdog(gen: loadGeneration, position: position)
+        host.swapItem(url: served.url, startPosition: position,
+                      skipInitialSeek: LiveReloadPolicy.skipInitialSeek(isLive: loadedOptions.isLive, isRejoin: true))
+        armAirPlayProgressWatchdog(gen: loadGeneration, position: position ?? 0)
         return true
     }
 
diff --git a/Sources/AetherEngine/Native/AirPlayPlaylistDecision.swift b/Sources/AetherEngine/Native/AirPlayPlaylistDecision.swift
index 324a0c4f1..f081bae25 100644
--- a/Sources/AetherEngine/Native/AirPlayPlaylistDecision.swift
+++ b/Sources/AetherEngine/Native/AirPlayPlaylistDecision.swift
@@ -92,6 +92,29 @@ enum AirPlayPlaylistDecision {
         return bypassServesLoopbackOrigin
     }
 
+    /// How a session crosses a wireless-AirPlay route change onto its new playback URL.
+    enum RouteChangeHop: Equatable {
+        /// `reloadAtCurrentPosition`: the session is rebuilt at the playhead, which reopens the source.
+        case rebuild
+        /// The player's item is swapped onto the new address while the session goes on serving.
+        case swapItem
+    }
+
+    /// A rebuild reopens the source, and two kinds of session cannot be reopened where they are. A
+    /// sequential origin can only be read again from byte 0. A forward-only custom source, which is what
+    /// the live HLS ingest hands the pipeline, cannot be rebuilt at all: `reloadAtCurrentPosition`
+    /// refuses it (#526), so the route change did nothing and the receiver was left on 127.0.0.1, which
+    /// it cannot reach, and played nothing. Neither needs a rebuild. The loopback server listens on every
+    /// interface and keeps the segments it cut, so only the address the player is handed has to change.
+    static func routeChangeHop(sequentialOrigin: Bool,
+                               isLive: Bool,
+                               isCustomSource: Bool,
+                               customSourceIsSeekable: Bool) -> RouteChangeHop {
+        if sequentialOrigin && !isLive { return .swapItem }
+        if isCustomSource && !customSourceIsSeekable { return .swapItem }
+        return .rebuild
+    }
+
     /// The loopback URL rewritten for the receiver: same port and query, the device's LAN IP for the host
     /// (the receiver cannot reach 127.0.0.1), and the path of the chosen playlist. `.master` keeps whatever
     /// the session resolved. The playlists' `EXT-X-MEDIA` and segment URIs are relative, so everything
diff --git a/Tests/AetherEngineTests/AirPlayPlaylistDecisionTests.swift b/Tests/AetherEngineTests/AirPlayPlaylistDecisionTests.swift
index 22a99dfc3..0a7b6a0d9 100644
--- a/Tests/AetherEngineTests/AirPlayPlaylistDecisionTests.swift
+++ b/Tests/AetherEngineTests/AirPlayPlaylistDecisionTests.swift
@@ -90,4 +90,29 @@ struct AirPlayPlaylistDecisionTests {
         #expect(!AirPlayPlaylistDecision.routeChangeNeedsReload(
             isRemoteHLSBypass: true, bypassServesLoopbackOrigin: false))
     }
+
+    @Test("#526: a live session on a forward-only source swaps its item, as its rebuild is refused")
+    func forwardOnlyLiveSessionSwapsItsItem() {
+        #expect(AirPlayPlaylistDecision.routeChangeHop(
+            sequentialOrigin: false, isLive: true,
+            isCustomSource: true, customSourceIsSeekable: false) == .swapItem)
+    }
+
+    @Test("A sequential origin swaps its item; every session that can be reopened where it is is rebuilt")
+    func otherSessionsKeepTheirHop() {
+        #expect(AirPlayPlaylistDecision.routeChangeHop(
+            sequentialOrigin: true, isLive: false,
+            isCustomSource: false, customSourceIsSeekable: false) == .swapItem)
+        #expect(AirPlayPlaylistDecision.routeChangeHop(
+            sequentialOrigin: false, isLive: false,
+            isCustomSource: false, customSourceIsSeekable: false) == .rebuild)
+        // A seekable custom source rebuilds on its retained reader.
+        #expect(AirPlayPlaylistDecision.routeChangeHop(
+            sequentialOrigin: false, isLive: true,
+            isCustomSource: true, customSourceIsSeekable: true) == .rebuild)
+        // A live URL source rebuilds and rejoins at the edge.
+        #expect(AirPlayPlaylistDecision.routeChangeHop(
+            sequentialOrigin: false, isLive: true,
+            isCustomSource: false, customSourceIsSeekable: false) == .rebuild)
+    }
 }
diff --git a/docs/architecture.md b/docs/architecture.md
index 51cadd49a..e76fffeb4 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -496,7 +496,7 @@ Sources/AetherEngine/
 │   ├── SoftwarePathEscalation.swift         Native path: the last rung. A CoreMedia-domain failure (AVPlayer refusing the MEDIA, not the source) is offered to the engine's own decoder once per session instead of ending it, since every recovery above reloads the same bytes (AE#561)
 │   ├── RemoteHLSMediaSelection.swift        Remote-HLS bypass (#154): pure loopback→bypass reroute decision for non-live m3u8 sources (FFmpeg has no network) + legible AVMediaSelectionGroup → `subtitleTracks` mapping (synthetic ids from 200000)
 │   ├── SoftwarePlaybackHost.swift           SW path: demux loop + decoders + renderer + synchronizer orchestration
-│   ├── 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)
+│   ├── AirPlayPlaylistDecision.swift        Pure decisions for the wireless-AirPlay loopback rewrite: which of master / media a receiver is handed, and whether a route change rebuilds the session or swaps its item (a sequential origin, a forward-only live source), kept separate and testable offline like `MasterFallbackDecision` (#86, #227, #526)
 │   ├── 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)
diff --git a/docs/formats.md b/docs/formats.md
index e1de54ebf..5ce944584 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -406,7 +406,7 @@ Host-rendered subtitle overlays are invisible in Picture-in-Picture, AirPlay, an
 
 **Routing scope.** A `SUBTITLES` rendition can only live in a master playlist, so native subtitles ride the master-routing rules: SDR sources on any panel, HDR / DV sources on HDR-ready panels. HDR-on-SDR-panel and DV Profile 5 on non-DV panels stay media-direct (no master, hence no native subtitles there); the host overlay still covers fullscreen. Bitmap subtitles (PGS / DVB / DVD) join as OCR-fed renditions: while a bitmap track is selected, a worker decodes its harvested packets ahead of the playhead (composition ends resolved at the next composition/clear event, the 5.14.1 sidecar semantics) and recognizes them on-device (Vision, track-language hinted) into plain-text cues for the track's rendition. Recognition is lossy by design; a failed or empty read drops that line from the rendition while fullscreen keeps the pixel-accurate bitmap overlay. External .sup sidecars fill their store from the selection-time sidecar decode's own image cues (no second fetch). Two shapes are out of scope for the loopback renditions entirely: live sources, whose own `SUBTITLES` renditions reach the host through the overlay instead ([below](#live-hls-subtitle-renditions-host-overlay)), and the software decode path (AV1 without hardware decode, VP9), which has no `AVPlayerItem` for a legible group to live on, so `prepareNativeSubtitles` is inert there and the host overlay owns subtitles on every surface.
 
-**Wireless AirPlay (#86, #227).** While an iOS session plays to a wireless AirPlay receiver, the engine reloads its loopback over the device's LAN IP: the receiver fetches the stream for itself and cannot reach `127.0.0.1`. It keeps the master there, so the `SUBTITLES` renditions travel and `setNativeSubtitleSelected(track:)` has a legible group to select against; the `EXT-X-MEDIA` URIs are relative, so they resolve against the LAN base with no further work.
+**Wireless AirPlay (#86, #227).** While an iOS session plays to a wireless AirPlay receiver, the engine reloads its loopback over the device's LAN IP: the receiver fetches the stream for itself and cannot reach `127.0.0.1`. It keeps the master there, so the `SUBTITLES` renditions travel and `setNativeSubtitleSelected(track:)` has a legible group to select against; the `EXT-X-MEDIA` URIs are relative, so they resolve against the LAN base with no further work. How the session gets onto the LAN address depends on whether it can be reopened where it is: one that can is rebuilt at the playhead, while a sequential origin, which could only be read again from byte 0, and a live session on the engine's own HLS ingest, a forward-only source that cannot be rebuilt at all (#526), swap the player's item onto the new address instead and carry on serving. The live one rejoins its playlist at the player's join point, as a live reload does. Both cross back onto the loopback the same way when the receiver lets go.
 
 Whether an HDR or Dolby Vision master is accepted is the receiver's decision, and it turns on the receiver's own output mode (measured 2026-07-27, iPhone 17 Pro to an Apple TV 4K, DV P8.1 4K source). With the Apple TV's video format fixed to 4K Dolby Vision it takes the DV master and plays it with subtitles. With the format at 4K SDR it refuses every HDR master, and Match Dynamic Range does not help: that setting switches only when tvOS decides the content warrants it, which it evidently never does for AirPlay content. This is the same rule the engine already applies locally, where an HDR source on a panel that is not in HDR mode is served the media playlist, and it is what DrHurt described in #86. Dressing the manifest up does not move it either: against a parked receiver, dropping the DV `SUPPLEMENTAL-CODECS`, clamping the declared `BANDWIDTH`, omitting `RESOLUTION` and declaring `HDCP-LEVEL=TYPE-1` each changed nothing, and declaring the range as SDR was already disproven in #98.
 

From a905385a1ebc22130664c700239e63b68532bde6 Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Wed, 14 Oct 2026 16:06:06 +0800
Subject: [PATCH 021/132] fix(software): preserve valid residency and honor
 bounded positioning outcomes

---
 CHANGELOG.md                                  |   5 +
 Sources/AetherEngine/AetherEngine.swift       |  13 ++
 Sources/AetherEngine/Demuxer/AVIOReader.swift |   7 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    |   6 +-
 .../Native/SoftwarePacketReadAhead.swift      |  51 +++++-
 .../Native/SoftwarePlaybackHost.swift         |  71 +++++---
 .../Native/SoftwareVideoPacketCoverage.swift  |   9 +-
 Sources/AetherEngine/SeekEvent.swift          |   5 +-
 .../DetourOriginTicketTests.swift             |  50 ++++++
 .../DocumentedConstantsTests.swift            |   5 +
 .../Issue613PacketCoverageTests.swift         | 108 ++++++++++++-
 .../SoftwareRepositionResultTests.swift       | 152 ++++++++++++++++++
 .../SoftwareResidentRangesTests.swift         | 118 ++++++++++++++
 docs/api.md                                   |  21 ++-
 14 files changed, 583 insertions(+), 38 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SoftwareRepositionResultTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d02c73bff..06f1cb524 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,11 @@ the public-API contract.
   gaps and disk eviction. Cached seeks keep the same spans; cold seeks and teardown clear them.
   Sampling continues while paused and runs off the main actor, with stale seek/stop results
   discarded. Hosts no longer need to infer a cache band's start from the moving playhead.
+  VC-1 uses verified successor timestamps rather than rounded packet-duration islands. Valid
+  committed packets remain seekable after a source read error, which is still reported after drain;
+  storage failures remain unusable. Failed resume/seek positioning can no longer publish a false
+  successful landing. Bounded cold probes avoid speculative detour fetches, and foreground software
+  positioning has a finite 30 s budget for slow multi-probe remote keyframe searches.
 
 - **A host with its own Objective-C and C++ links again (#752).** Since 7.34.0 LibTrueHD and LibDovi
   each brought a `rust_eh_personality`, and with the host's `__objc_personality_v0` and
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 8c22f2a17..acb4b31b4 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -6184,6 +6184,19 @@ public final class AetherEngine: ObservableObject {
         // A superseding seek owns the final state.
         guard loadGeneration == gen, seekGeneration == seekGen else { return }
         setPendingRecoverySeekTarget(nil)
+        if softwareHost != nil, hostReposition != .landed {
+            setProgrammaticSeek(inFlight: false, target: nil)
+            closeSeekTicket(&programmaticSeekTicket,
+                            with: hostReposition == .superseded ? .superseded : .stalled)
+            // Host failure sinks may already have published .error. Never overwrite it with
+            // .playing/.paused or publish the requested position as though it was reached.
+            if hostReposition == .stalled {
+                if case .error = state {} else {
+                    publishError(.softwarePipelineFailed, "Playback source could not reposition.")
+                }
+            }
+            return
+        }
         // Publish the measured native landing, not the optimistic request. The two can differ
         // slightly even after a successful callback; subtitle anchors and SeekEvent must agree.
         let landedClock = nativeOnly ? (nativeHost?.currentTime ?? clockTarget) : clockTarget
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 126617cd6..6c8c3f2f4 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -2731,7 +2731,12 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         if let n = detourCache.serveCached(into: dst, maxLen: maxLen, at: offset) {
             return .served(n, fetched: false)
         }
-        guard allowFetch else { return .miss }
+        // A bounded position search may probe several distant offsets. Waiting for a whole
+        // speculative 4 MB block at each offset can spend the seek's entire deadline before
+        // the existing streaming reconnect gets a chance to deliver the requested bytes.
+        // Keep resident hits above, but let a bounded miss re-anchor immediately. Ordinary
+        // parse-time ping-pong still fills the detour cache and preserves its connection.
+        guard allowFetch, readDeadline == .distantFuture else { return .miss }
 
         let blockStart = (offset / Int64(Self.detourBlockSize)) * Int64(Self.detourBlockSize)
         let blockLen = Int(min(Int64(Self.detourBlockSize), fileSize - blockStart))
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 847ccc0fd..4d1d2dd99 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -2409,7 +2409,11 @@ public final class Demuxer: @unchecked Sendable {
         // matroska may return success with a partial index after abort; deadline flag
         // is authoritative, not ret.
         let capped = avioProvider?.readDeadlineFired ?? false
-        return ret >= 0 && !capped && probeControl?.isStopped != true
+        let stopped = probeControl?.isStopped == true
+        // Fixed result flags only: FFmpeg refusal, read deadline, cancellation. No source identity.
+        let flags = (ret < 0 ? 1 : 0) | (capped ? 2 : 0) | (stopped ? 4 : 0)
+        EngineLog.emit("[DemuxReposition] flags=\(flags)", category: .swPlayback)
+        return ret >= 0 && !capped && !stopped
     }
 
     /// How an off-actor reposition ended (#254). Named to mirror `SeekEvent.Outcome` so the engine's
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 5d4e533cf..c0cce31b3 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -63,6 +63,17 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     private var started = false
     private var ended = false
     private var failure: Error?
+    private enum FailureOrigin: Int {
+        case none = 0, sourceRead = 1024, storage = 2048, envelope = 4096
+    }
+    private var failureOrigin: FailureOrigin = .none
+    // Called under condition. An upstream read failure says nothing about the integrity of
+    // envelopes already committed to the FIFO. Keep those usable; read() still throws the
+    // original failure after they drain, and the producer stays parked until a cold seek.
+    private var retainedPacketsUsableLocked: Bool {
+        failure == nil || failureOrigin == .sourceRead
+    }
+    private var lastCoverageDiagnosticFlags: Int?
     private var count = 0
     private var bytes = 0
     private var residentBytes = 0
@@ -139,7 +150,28 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     /// timestamp conversion/intersection and keyframe selection happen after releasing it. No I/O.
     var residentRanges: [ClosedRange<Double>] {
         condition.lock()
-        guard !closed, !sourceRepositioning, !resetPending, failure == nil,
+        // Fixed numeric state only, emitted on edges by this background sampler. No URLs,
+        // error descriptions or packet content. Bits: closed/reposition/reset/failure,
+        // nonretaining/invalid-video/EOF/empty-audio/no-keyframe/unknown-floor,
+        // source-failure/storage-failure/envelope-failure/empty-video.
+        var flags = failureOrigin.rawValue
+        if closed { flags |= 1 }
+        if sourceRepositioning { flags |= 2 }
+        if resetPending { flags |= 4 }
+        if failure != nil { flags |= 8 }
+        if !fifo.retainsConsumedPackets { flags |= 16 }
+        if presentationCoverage?.isInvalidated == true { flags |= 32 }
+        if ended { flags |= 64 }
+        if audio != nil && audioCoverage.rangeCount == 0 { flags |= 128 }
+        if keyframes.isEmpty { flags |= 256 }
+        if residency.videoFloor == .infinity || residency.audioFloor == .infinity { flags |= 512 }
+        if (presentationCoverage?.rangeCount ?? videoCoverage.rangeCount) == 0 { flags |= 8192 }
+        let changed = lastCoverageDiagnosticFlags != flags
+        lastCoverageDiagnosticFlags = flags
+        defer {
+            if changed { EngineLog.emit("[SWCacheCoverage] flags=\(flags)", category: .swPlayback) }
+        }
+        guard !closed, !sourceRepositioning, !resetPending, retainedPacketsUsableLocked,
               fifo.retainsConsumedPackets else { condition.unlock(); return [] }
         let videoCoverage = self.videoCoverage
         let presentationCoverage = self.presentationCoverage
@@ -208,7 +240,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         guard token == generation, seeking, !closed else {
             condition.unlock(); throw ReadError.interrupted
         }
-        let hasCoverage = !sourceRepositioning && !resetPending && failure == nil
+        let hasCoverage = !sourceRepositioning && !resetPending && retainedPacketsUsableLocked
             && seconds.isFinite && (frontierLocked(at: seconds).map { $0 > seconds } ?? false)
         let candidates = hasCoverage ? keyframes.filter { $0.seconds <= seconds }
             .sorted { $0.seconds < $1.seconds } : []
@@ -272,7 +304,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         guard seconds.isFinite, maxPackets > 0, isCancelled?() != true else { return nil }
         let deadline = ContinuousClock.now.advanced(by: .milliseconds(750))
         condition.lock()
-        let eligible = !closed && !sourceRepositioning && !resetPending && failure == nil
+        let eligible = !closed && !sourceRepositioning && !resetPending && retainedPacketsUsableLocked
             && (frontierLocked(at: seconds).map { $0 > seconds } ?? false)
         let anchor = eligible
             ? keyframes.filter { $0.seconds <= seconds }.max { $0.seconds < $1.seconds } : nil
@@ -431,7 +463,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
 
     private func clearSourceMetadataLocked() {
         count = 0; bytes = 0; residentBytes = 0
-        ended = false; failure = nil
+        ended = false; failure = nil; failureOrigin = .none
         videoCoverage.reset(); audioCoverage.reset(); presentationCoverage?.reset()
         storedVideoSeconds = nil; consumedVideoSeconds = nil
         keyframes.removeAll(keepingCapacity: true)
@@ -487,7 +519,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                     if token == sourceEpoch { resetPending = false }
                     condition.broadcast()
                     condition.unlock()
-                } catch { recordFailure(error, token: token) }
+                } catch { recordFailure(error, token: token, origin: .storage) }
                 operations.unlock()
                 continue
             }
@@ -499,6 +531,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     }
 
     private func producePacket(token: UInt64) {
+        var failureOrigin: FailureOrigin = .sourceRead
         do {
             let packet = try readSource { [self] in
                 condition.lock(); defer { condition.unlock() }
@@ -514,6 +547,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                 condition.unlock()
                 return
             }
+            failureOrigin = .envelope
             let data = try packet.encoded()
             operations.lock()
             condition.lock()
@@ -563,10 +597,10 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                     }
                     condition.broadcast()
                     condition.unlock()
-                } catch { recordFailure(error, token: token) }
+                } catch { recordFailure(error, token: token, origin: .storage) }
             }
             operations.unlock()
-        } catch { recordFailure(error, token: token) }
+        } catch { recordFailure(error, token: token, origin: failureOrigin) }
     }
 
     private func shouldParkLocked() -> Bool {
@@ -587,10 +621,11 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         return frontierLocked().map { $0 - sourceClock >= forwardSeconds } ?? false
     }
 
-    private func recordFailure(_ error: Error, token: UInt64) {
+    private func recordFailure(_ error: Error, token: UInt64, origin: FailureOrigin) {
         condition.lock(); defer { condition.unlock() }
         guard token == sourceEpoch, !closed else { return }
         failure = error
+        failureOrigin = origin
         resetPending = false
         condition.broadcast()
     }
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 82f584abd..aa33c98ed 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -14,11 +14,14 @@ 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
+    /// (n8.1.2 hevc/ps.c:1397-1403), inside the 32-timestamp queue. VC-1's max_b_frames is at most
+    /// 7 (n8.1.2 vc1.c:346,426), also within that queue including a field-picture margin. Its
+    /// 33 ms packet durations over 33/34 ms timestamps otherwise create the same tiny holes.
+    /// 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
+        case AV_CODEC_ID_H264.rawValue, AV_CODEC_ID_HEVC.rawValue, AV_CODEC_ID_VC1.rawValue: return 32
         default: return nil
         }
     }
@@ -175,8 +178,12 @@ final class SoftwarePlaybackHost {
     /// the wrong thread for it. Serial and separate from `demuxQueue`, whose block never returns.
     private let seekQueue = DispatchQueue(label: "engine.sw.seek", qos: .userInitiated)
 
-    /// Read-deadline budget for a reposition (#254). Matches the side reader's positioning budget.
-    private static let seekBudgetSeconds: TimeInterval = 8.0
+    /// Bound foreground VOD positioning independently of speculative side-reader work.
+    /// Index-less containers can require several remote keyframe probes; cloud-mounted
+    /// sources may take 2-3 seconds per successful range response. The former 8-second
+    /// side-reader budget aborted these progressing seeks. Keep a finite total bound;
+    /// repositioning still runs off-main and failed/cancelled results remain failures.
+    static let seekBudgetSeconds: TimeInterval = 30.0
 
     /// True while a reposition is awaiting `seekQueue`. Gates the 0.25 s time tick: the synchronizer
     /// still carries the pre-seek anchor, so an ungated tick would walk the OLD position forward for
@@ -746,7 +753,16 @@ final class SoftwarePlaybackHost {
 
     // MARK: - Init
 
-    init(videoGravity: AVLayerVideoGravity = .resizeAspect) {
+    typealias Reposition = @Sendable (Demuxer, Double, TimeInterval, DispatchQueue,
+                                      @escaping @Sendable () -> Bool) async -> Demuxer.RepositionOutcome
+    private let reposition: Reposition
+
+    init(videoGravity: AVLayerVideoGravity = .resizeAspect,
+         reposition: @escaping Reposition = { dem, target, budget, queue, superseded in
+             await dem.seekBounded(to: target, timeout: budget, on: queue,
+                                   isSuperseded: superseded)
+         }) {
+        self.reposition = reposition
         self.renderer = SampleBufferRenderer(videoGravity: videoGravity)
         // Default to the software decoder; load() swaps it for the
         // VT-backed one when the source's video codec is HEVC.
@@ -1082,11 +1098,16 @@ final class SoftwarePlaybackHost {
             let sourceStart = SWClockAnchorPolicy.sourceSeconds(forSession: start, sessionZeroSeconds: zero)
             // #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: sourceStart, timeout: Self.seekBudgetSeconds, on: seekQueue)
+            let outcome = await reposition(dem, sourceStart, Self.seekBudgetSeconds, seekQueue,
+                                           { [weak self] in self?.stopRequested ?? true })
             // This is load()'s only suspension point, so it is also the only place a stop() can land
             // mid-load. Arming the clock and publishing isReady on a session already torn down would
             // hand the engine a host it has stopped.
-            guard !stopRequested else { return }
+            guard !stopRequested, !Task.isCancelled, outcome != .superseded else {
+                throw CancellationError()
+            }
+            EngineLog.emit("[SWReposition] flags=\(outcome == .landed ? 0 : 1)", category: .swPlayback)
+            guard outcome == .landed else { throw HostError.repositionFailed }
             // Mirror seek() skip-PTS + clock alignment so demux drops pre-keyframe frames and synchronizer starts at the resume offset.
             let startTime = CMTime(seconds: sourceStart, preferredTimescale: 90000)
             videoDecoder.skipUntilPTS = startTime
@@ -1161,6 +1182,7 @@ final class SoftwarePlaybackHost {
     // MARK: - Transport
 
     func play() {
+        guard !stopRequested, failure == nil else { return }
         // Resume after pause(): gate on clockArmed, not demuxLoopStarted. A rate change on the
         // un-anchored synchronizer (no media at its clock time yet) wedges the delayed-rate-change
         // machinery permanently frozen; the arming seekClock applies the current lastRate (#107).
@@ -1470,7 +1492,7 @@ final class SoftwarePlaybackHost {
     @discardableResult
     func seek(to seconds: Double) async -> Demuxer.RepositionOutcome {
         guard !stopRequested else { return .superseded }
-        guard let dem = demuxer else { return .stalled }
+        guard failure == nil, let dem = demuxer else { return .stalled }
         // Stop loop + bump generation to invalidate in-flight packets. Captured right after, so the
         // reposition can tell on `seekQueue` whether a newer seek has already taken over.
         bumpSeekGeneration()
@@ -1572,23 +1594,31 @@ final class SoftwarePlaybackHost {
             // existing frontier; seeking it too would duplicate or skip already retained packets.
             outcome = .landed
         } else {
-            outcome = await dem.seekBounded(
-                to: sourceSeconds, timeout: Self.seekBudgetSeconds, on: seekQueue,
-                isSuperseded: { [weak self] in
+            outcome = await reposition(dem, sourceSeconds, Self.seekBudgetSeconds, seekQueue,
+                { [weak self] in
                     self?.seekGeneration != generation || (self?.stopRequested ?? true)
                 })
         }
         // A newer seek owns the state from here: it published its own target and clears the hold itself.
         // stop() can also land in the await now that this suspends, and re-arming the clock or flipping
         // isPlaying on a torn-down session would resurrect a loop that has already been told to quit.
-        guard seekGeneration == generation, !stopRequested else { return .superseded }
+        guard seekGeneration == generation, !stopRequested, outcome != .superseded else { return .superseded }
         seekInFlight = false
-        if outcome == .stalled {
-            EngineLog.emit(
-                "[SWHost] reposition to \(String(format: "%.2f", seconds))s did not complete within "
-                + "\(String(format: "%.0f", Self.seekBudgetSeconds))s; read position is undefined",
-                category: .swPlayback
-            )
+        EngineLog.emit("[SWReposition] flags=\(outcome == .landed ? 2 : 3)", category: .swPlayback)
+        guard outcome == .landed else {
+            // No target clock, decoder run or cache producer may follow an undefined read position.
+            // Keep the last observed clock; the engine must not finalize this request as a landing.
+            isPlaying = false
+            pausedByHost = true
+            audioOutput?.setRate(0)
+            currentTime = clockSessionZero > 0
+                ? max(0, sourceClockSeconds - clockSessionZero) : sourceClockSeconds
+            packetSource?.close()
+            residentRanges = []
+            noteSeekSettled(generation)
+            failure = PlaybackErrorInfo(kind: .softwarePipelineFailed,
+                                       message: "Playback source could not reposition.")
+            return .stalled
         }
 
         // Re-armed after the landing: a pre-seek frame PAST the target (a backward seek) clears the
@@ -3329,7 +3359,7 @@ final class SoftwarePlaybackHost {
                 guard let aOut = self.audioOutput else { return }
                 // #254: a reposition in flight holds `currentTime` at its target; the synchronizer is
                 // still on the pre-seek anchor and would drag the published position backwards.
-                guard !self.seekInFlight else { return }
+                guard !self.seekInFlight, self.failure == nil else { return }
                 let raw = aOut.currentTimeSeconds
                 self.emitDiagIfDue(clock: raw)
                 // AE#724: until the first sample arms it, the synchronizer still reads 0, and a paused
@@ -3496,11 +3526,12 @@ final class SoftwarePlaybackHost {
     // MARK: - Errors
 
     enum HostError: Error, LocalizedError {
-        case noVideoStream
+        case noVideoStream, repositionFailed
 
         var errorDescription: String? {
             switch self {
             case .noVideoStream: return "Source has no video stream"
+            case .repositionFailed: return "Playback source could not resume at the requested position."
             }
         }
     }
diff --git a/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift b/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
index ae44a14e9..f57c93467 100644
--- a/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
+++ b/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-/// H.264 and HEVC compressed-packet presentation coverage matching the renderer's successor-PTS
+/// H.264, HEVC and VC-1 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
@@ -8,14 +8,17 @@ import Foundation
 /// 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/HEVC caller contract: complete selected-stream packets, with valid presentation timestamps,
+/// H.264/HEVC/VC-1 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 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
+/// holds 32 distinct timestamps as a conservative field-picture margin. VC-1's max_b_frames is
+/// either read from three bits or set to 7, also within that queue. 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
+/// https://github.com/FFmpeg/FFmpeg/blob/n8.1.2/libavcodec/vc1.c#L346
+/// https://github.com/FFmpeg/FFmpeg/blob/n8.1.2/libavcodec/vc1.c#L426
 ///
 /// 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
diff --git a/Sources/AetherEngine/SeekEvent.swift b/Sources/AetherEngine/SeekEvent.swift
index 15179bf8e..784ee7412 100644
--- a/Sources/AetherEngine/SeekEvent.swift
+++ b/Sources/AetherEngine/SeekEvent.swift
@@ -51,8 +51,9 @@ public struct SeekEvent: Sendable, Equatable {
         /// The picture is at the target: AVPlayer reported the landing, or the rendered frame reached the
         /// scrub target. This is the only outcome that means "safe to read the clock".
         case landed(renderedTime: Double)
-        /// The engine spent its recovery budget without the source serving the target. The clock is held
-        /// AT the target and the seek stays alive, so a `.landed` under this `id` can still follow.
+        /// Positioning did not complete within its budget. Native AVPlayer recovery may keep the
+        /// target pending and later emit `.landed` under this `id`. A software positioning failure
+        /// instead reports a terminal pipeline error without finalizing the requested clock.
         case stalled
         /// A newer seek took over before this one settled; the newer one's `.began` carries its target.
         case superseded
diff --git a/Tests/AetherEngineTests/DetourOriginTicketTests.swift b/Tests/AetherEngineTests/DetourOriginTicketTests.swift
index 1b8a5567a..b3a0f4f48 100644
--- a/Tests/AetherEngineTests/DetourOriginTicketTests.swift
+++ b/Tests/AetherEngineTests/DetourOriginTicketTests.swift
@@ -58,5 +58,55 @@ struct DetourOriginTicketTests {
         // 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)")
+
+        // Arming a seek deadline must still reuse that resident block without network I/O.
+        let requestsBeforeHit = server.rangeRequestCount
+        reader.beginReadDeadline(secondsFromNow: 8)
+        #expect(reader.seek(offset: target, whence: Int32(SEEK_SET)) == target)
+        #expect(reader.read(into: buf, size: Int32(chunk)) == chunk)
+        #expect(server.rangeRequestCount == requestsBeforeHit)
+        reader.endReadDeadline()
+    }
+
+    @Test("bounded cold probing reanchors without a speculative block, then restores normal detours",
+          .timeLimit(.minutes(2)))
+    func boundedProbeSkipsColdDetour() throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024,
+                                                       throttleUs: 40_000, patternedBody: true))
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/bounded.bin")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        let chunk = 256 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        func readToThirteenMB(from start: Int) throws {
+            var position = start
+            while position < 13 * 1024 * 1024 {
+                let n = Int(reader.read(into: buf, size: Int32(chunk)))
+                try #require(n > 0)
+                position += n
+            }
+        }
+        try readToThirteenMB(from: 0)
+        #expect(reader.hasLiveConnectionForTesting)
+        let target: Int64 = 5 * 1024 * 1024
+        reader.beginReadDeadline(secondsFromNow: 8)
+        #expect(reader.seek(offset: target, whence: Int32(SEEK_SET)) == target)
+        let n = Int(reader.read(into: buf, size: Int32(chunk)))
+        #expect(n == chunk)
+        #expect(!reader.readDeadlineFired)
+        #expect((0..<max(0, n)).allSatisfy {
+            buf[$0] == ThrottledOriginServer.patternByte(at: target + Int64($0))
+        })
+        #expect(server.requestedRanges.contains { $0.start == target })
+        #expect(!server.requestedRanges.contains { $0.start == 4 * 1024 * 1024 && $0.end == 8 * 1024 * 1024 - 1 })
+        reader.endReadDeadline()
+
+        // The policy is scoped to the bounded operation, not a sticky source-wide downgrade.
+        try readToThirteenMB(from: Int(target) + max(0, n))
+        #expect(reader.seek(offset: target, whence: Int32(SEEK_SET)) == target)
+        #expect(reader.read(into: buf, size: Int32(chunk)) == chunk)
+        #expect(server.requestedRanges.contains { $0.start == 4 * 1024 * 1024 && $0.end == 8 * 1024 * 1024 - 1 })
     }
 }
diff --git a/Tests/AetherEngineTests/DocumentedConstantsTests.swift b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
index 9e0e47179..c378f5882 100644
--- a/Tests/AetherEngineTests/DocumentedConstantsTests.swift
+++ b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
@@ -19,6 +19,11 @@ import AetherLibavcodec
 @MainActor
 final class DocumentedConstantsTests: XCTestCase {
 
+    func testSoftwarePositioningBudgetMatchesDocumentation() throws {
+        XCTAssertEqual(SoftwarePlaybackHost.seekBudgetSeconds, 30)
+        assertDocumented("**30 s positioning\nbudget**", try documentation())
+    }
+
     func testItemDiagnosticBoundsMatchDocumentation() throws {
         let docs = try documentation()
         XCTAssertEqual(ItemDiagnosticReadPool.maximumConcurrentReads, 2)
diff --git a/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift b/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift
index 0e3d307d6..fad9383c3 100644
--- a/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift
+++ b/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift
@@ -71,13 +71,15 @@ struct Issue613PacketCoverageTests {
 
     /// 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")
+    @Test("H.264, HEVC and VC-1 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: AV_CODEC_ID_VC1.rawValue) == 32)
+        for other in [AV_CODEC_ID_AV1, AV_CODEC_ID_VP9, AV_CODEC_ID_MPEG2VIDEO, AV_CODEC_ID_WMV3] {
             #expect(SoftwarePlaybackHost.presentationReorderDepth(codecID: other.rawValue) == nil)
         }
     }
@@ -107,6 +109,108 @@ struct Issue613PacketCoverageTests {
         }
     }
 
+    private func withAsyncRoot<T>(_ body: (URL) async throws -> T) async throws -> T {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("vc1-coverage-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+        return try await body(root)
+    }
+
+    /// Synthetic VC-1 timing only: one reference followed by up to seven B pictures,
+    /// 30 fps rounded to milliseconds, and presentation-ordered audio with explicit duration.
+    /// Missing audio duration is covered separately by upstream #775, not this VC-1 regression.
+    /// No private media, packet payloads or source identifiers are needed to reproduce it.
+    private func vc1ReadAhead(root: URL, count: Int, strict: Bool = false,
+                              discontinuity: Bool = false) async throws -> SoftwarePacketReadAhead {
+        var order = [0]
+        for first in stride(from: 1, to: count, by: 8) {
+            let reference = min(first + 7, count - 1)
+            order.append(reference)
+            order.append(contentsOf: first..<reference)
+        }
+        var packets: [SoftwareStoredPacket] = []
+        func timestamp(_ index: Int) -> Int64 {
+            Int64(index) * 100 / 3 + (discontinuity && index >= 150 ? 2000 : 0)
+        }
+        for (decodeIndex, picture) in order.enumerated() {
+            packets.append(SoftwareStoredPacket(pts: timestamp(picture), dts: timestamp(decodeIndex),
+                duration: 33, position: 0, streamIndex: 0, flags: picture % 240 == 0 ? 1 : 0,
+                timeBaseNumerator: 1, timeBaseDenominator: 1000,
+                bytes: Data(repeating: 7, count: 100), sideData: []))
+            if decodeIndex % 5 == 0 {
+                packets.append(SoftwareStoredPacket(pts: timestamp(decodeIndex), dts: timestamp(decodeIndex),
+                    duration: Int64(decodeIndex + 5) * 100 / 3 - Int64(decodeIndex) * 100 / 3,
+                    position: 0, streamIndex: 1, flags: 1,
+                    timeBaseNumerator: 1, timeBaseDenominator: 1000,
+                    bytes: Data(repeating: 3, count: 16), sideData: []))
+            }
+        }
+        let all = packets
+        let counter = Counter()
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64 * 1024, retainConsumed: true,
+                                              parentDirectory: root)
+        let source = SoftwarePacketReadAhead(video: .init(index: 0, numerator: 1, denominator: 1000),
+            audio: .init(index: 1, numerator: 1, denominator: 1000), byteBudget: 50_000_000,
+            forwardSeconds: 10_000, initialSourceClock: 0, fifo: fifo,
+            videoReorderDepth: strict ? nil : SoftwarePlaybackHost.presentationReorderDepth(
+                codecID: AV_CODEC_ID_VC1.rawValue)) { _ in
+                    let index = counter.next() - 1
+                    return index < all.count ? all[index] : nil
+                }
+        source.start()
+        do { try await waitFor { source.snapshot.sourceEnded } }
+        catch { source.close(); throw error }
+        return source
+    }
+
+    @Test("VC-1 rounded durations and seven-picture reorder retain one long A/V range", .timeLimit(.minutes(2)))
+    func vc1RoundedDurationsAndCacheSeek() async throws {
+        try await withAsyncRoot { root in
+            let old = try await vc1ReadAhead(root: root, count: 15_000, strict: true)
+            #expect(old.residentRanges.count == 4096, "old codec selection saturates coverage")
+            #expect((old.residentRanges.last?.upperBound ?? 0) < 420)
+            old.close()
+
+            let source = try await vc1ReadAhead(root: root, count: 15_000)
+            defer { source.close() }
+            #expect(source.residentRanges.count == 1)
+            #expect((source.residentRanges.last?.upperBound ?? 0) > 499)
+            // A former one-millisecond hole, then a retained position beyond the old cap.
+            for target in [0.0995, 450.0] {
+                let token = source.beginSeek(to: target)
+                #expect(try source.prepareSeek(token, to: target))
+            }
+            source.close()
+            #expect(source.residentRanges.isEmpty, "discard must clear the published cache")
+        }
+    }
+
+    @Test("VC-1 successor coverage preserves a genuine two-second A/V discontinuity", .timeLimit(.minutes(2)))
+    func vc1DiscontinuityRemainsUncached() async throws {
+        try await withAsyncRoot { root in
+            let source = try await vc1ReadAhead(root: root, count: 600, discontinuity: true)
+            defer { source.close() }
+            #expect(source.residentRanges.count == 2)
+            #expect(!source.residentRanges.contains { $0.contains(6) })
+            let token = source.beginSeek(to: 6)
+            #expect(try source.prepareSeek(token, to: 6) == false)
+        }
+    }
+
+    @Test("VC-1 admission retains the existing fail-closed late-timestamp guard")
+    func vc1LateTimestampInvalidates() throws {
+        let depth = try #require(SoftwarePlaybackHost.presentationReorderDepth(codecID: AV_CODEC_ID_VC1.rawValue))
+        var model = SoftwareVideoPacketCoverage(timeBaseNumerator: 1, timeBaseDenominator: 1000,
+                                                reorderDepth: depth)
+        for index: Int64 in 0..<100 { model.insert(pts: index * 100 / 3) }
+        #expect(!model.rangesSeconds.isEmpty)
+        let admitted = model.insert(pts: 1)
+        #expect(!admitted)
+        #expect(model.isInvalidated)
+        #expect(model.rangesSeconds.isEmpty)
+    }
+
     // 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.
diff --git a/Tests/AetherEngineTests/SoftwareRepositionResultTests.swift b/Tests/AetherEngineTests/SoftwareRepositionResultTests.swift
new file mode 100644
index 000000000..16792043c
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwareRepositionResultTests.swift
@@ -0,0 +1,152 @@
+import Foundation
+import Combine
+import Testing
+@testable import AetherEngine
+
+@Suite(.serialized, .timeLimit(.minutes(2)))
+@MainActor
+struct SoftwareRepositionResultTests {
+    actor Gate {
+        private var waits: [Int: CheckedContinuation<Demuxer.RepositionOutcome, Never>] = [:]
+        private(set) var count = 0
+        func next() async -> Demuxer.RepositionOutcome {
+            let id = count; count += 1
+            return await withCheckedContinuation { waits[id] = $0 }
+        }
+        func finish(_ id: Int, _ result: Demuxer.RepositionOutcome) {
+            waits.removeValue(forKey: id)?.resume(returning: result)
+        }
+    }
+
+    private func demuxer() throws -> Demuxer {
+        let dem = Demuxer()
+        try dem.open(reader: DataIOReader(data: ProbeTestFixtures.hdr10Plus()), formatHint: "mp4")
+        return dem
+    }
+
+    private func loadedHost(_ reposition: @escaping SoftwarePlaybackHost.Reposition) async throws -> SoftwarePlaybackHost {
+        let host = SoftwarePlaybackHost(reposition: reposition)
+        do {
+            try await host.load(demuxer: demuxer(), startPosition: nil, audioSourceStreamIndex: nil)
+            return host
+        } catch { host.stop(); throw error }
+    }
+
+    @Test("Failed resume never publishes readiness, target clock or first-frame readiness")
+    func failedResume() async throws {
+        let host = SoftwarePlaybackHost(reposition: { _, _, _, _, _ in .stalled })
+        defer { host.stop() }
+        do {
+            try await host.load(demuxer: demuxer(), startPosition: 42, audioSourceStreamIndex: nil)
+            Issue.record("failed resume returned successfully")
+        } catch SoftwarePlaybackHost.HostError.repositionFailed {} catch { throw error }
+        #expect(!host.isReady)
+        #expect(!host.isPlaying)
+        #expect(!host.isVideoReadyForDisplay)
+        #expect(host.currentTime == 0)
+        #expect(host.sourceClockSeconds == 0)
+    }
+
+    @Test("Successful resume retains its anchor without claiming a displayed first frame")
+    func successfulResume() async throws {
+        let host = SoftwarePlaybackHost(reposition: { _, _, _, _, _ in .landed })
+        defer { host.stop() }
+        try await host.load(demuxer: demuxer(), startPosition: 42, audioSourceStreamIndex: nil)
+        #expect(host.isReady)
+        #expect(host.currentTime == 42)
+        #expect(!host.isVideoReadyForDisplay)
+        #expect(!host.isPlaying)
+    }
+
+    @Test("Stop during resume cannot publish readiness or resurrect the target clock")
+    func stoppedResume() async throws {
+        let gate = Gate()
+        let host = SoftwarePlaybackHost(reposition: { _, _, _, _, _ in await gate.next() })
+        let dem = try demuxer()
+        let load = Task { try await host.load(demuxer: dem, startPosition: 42, audioSourceStreamIndex: nil) }
+        try await waitFor { await gate.count >= 1 }
+        host.stop()
+        await gate.finish(0, .landed)
+        do { try await load.value; Issue.record("stopped resume returned successfully") }
+        catch is CancellationError {} catch { throw error }
+        #expect(!host.isReady)
+        #expect(host.currentTime == 0)
+        #expect(!host.isPlaying)
+    }
+
+    @Test("Caller cancellation during resume cannot publish a successful load")
+    func cancelledResume() async throws {
+        let gate = Gate()
+        let host = SoftwarePlaybackHost(reposition: { _, _, _, _, _ in await gate.next() })
+        defer { host.stop() }
+        let dem = try demuxer()
+        let load = Task { try await host.load(demuxer: dem, startPosition: 42, audioSourceStreamIndex: nil) }
+        try await waitFor { await gate.count >= 1 }
+        load.cancel()
+        await gate.finish(0, .landed)
+        do { try await load.value; Issue.record("cancelled resume returned successfully") }
+        catch is CancellationError {} catch { throw error }
+        #expect(!host.isReady)
+        #expect(!host.isPlaying)
+        #expect(host.currentTime == 0)
+    }
+
+    @Test("Failed software seek stays failed through engine finalization and keeps its request identity", arguments: [false, true])
+    func failedSeek(wireFailure: Bool) async throws {
+        let host = try await loadedHost { _, _, _, _, _ in .stalled }
+        let engine = try AetherEngine()
+        engine.softwareHost = host
+        engine.duration = 100
+        engine.state = .paused
+        defer { engine.stop() }
+        let failureSink = wireFailure ? host.$failure.compactMap { $0 }.sink { engine.publishError($0) } : nil
+        defer { failureSink?.cancel() }
+        var events: [SeekEvent] = []
+        let sub = engine.seekEvents.sink { events.append($0) }
+        defer { sub.cancel() }
+        await engine.seek(to: 42)
+        #expect(host.failure?.kind == .softwarePipelineFailed)
+        #expect(!host.isPlaying)
+        #expect(host.currentTime != 42)
+        #expect(engine.currentTime != 42)
+        #expect(!engine.isSeeking)
+        guard case .error = engine.state else { Issue.record("failed seek was finalized as playable"); return }
+        #expect(events.map(\.outcome) == [.began, .stalled])
+        #expect(Set(events.map(\.id)).count == 1)
+        host.play()
+        #expect(!host.isPlaying)
+    }
+
+    @Test("A late failed seek cannot poison a newer successful paused seek")
+    func supersededFailure() async throws {
+        let gate = Gate()
+        let host = try await loadedHost { _, _, _, _, _ in await gate.next() }
+        let engine = try AetherEngine()
+        engine.softwareHost = host
+        engine.duration = 100
+        engine.state = .paused
+        defer { engine.stop() }
+        var events: [SeekEvent] = []
+        let sub = engine.seekEvents.sink { events.append($0) }
+        defer { sub.cancel() }
+        let first = Task { await engine.seek(to: 12) }
+        try await waitFor { await gate.count >= 1 }
+        let second = Task { await engine.seek(to: 24) }
+        try await waitFor { await gate.count >= 2 }
+        await gate.finish(0, .stalled)
+        await first.value
+        #expect(host.failure == nil)
+        await gate.finish(1, .landed)
+        await second.value
+        #expect(host.currentTime == 24)
+        #expect(engine.currentTime == 24)
+        #expect(engine.state == .paused)
+        #expect(!engine.isSeeking)
+        #expect(host.failure == nil)
+        #expect(events.filter { $0.target == 12 }.map(\.outcome) == [.began, .superseded])
+        #expect(events.filter { $0.target == 24 }.count == 2)
+        #expect(events.last?.target == 24)
+        if case .landed = events.last?.outcome {} else { Issue.record("newest seek did not land") }
+    }
+
+}
diff --git a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
index 8cd47c854..85cafd566 100644
--- a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
+++ b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
@@ -141,6 +141,124 @@ struct SoftwareResidentRangesTests {
         #expect(value.videoFloor == -.infinity)
     }
 
+    private func consume(_ source: SoftwarePacketReadAhead,
+                         expecting packets: [SoftwareStoredPacket], fails: Bool) async throws {
+        try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+                Thread.detachNewThread {
+                    do {
+                        for expected in packets { #expect(try source.read() == expected) }
+                        if fails { #expect(throws: SourceFailure.self) { _ = try source.read() } }
+                        else { #expect(try source.read() == nil) }
+                        continuation.resume()
+                    } catch { continuation.resume(throwing: error) }
+                }
+            }
+        } onCancel: { source.close() }
+    }
+
+    private enum SourceFailure: Error { case unavailable }
+    private final class FailingInput: @unchecked Sendable {
+        private let lock = NSLock()
+        private var packets: [SoftwareStoredPacket]
+        private var index = 0
+        private var failAtEnd = true
+        let reachedEnd = DispatchSemaphore(value: 0)
+        let releaseEnd = DispatchSemaphore(value: 0)
+        init(_ packets: [SoftwareStoredPacket]) { self.packets = packets }
+        func next() throws -> SoftwareStoredPacket? {
+            lock.lock()
+            if index < packets.count {
+                let packet = packets[index]; index += 1
+                lock.unlock(); return packet
+            }
+            let fail = failAtEnd
+            lock.unlock()
+            if fail {
+                reachedEnd.signal(); releaseEnd.wait()
+                throw SourceFailure.unavailable
+            }
+            return nil
+        }
+        func replace(_ packets: [SoftwareStoredPacket]) {
+            lock.lock(); defer { lock.unlock() }
+            self.packets = packets; index = 0; failAtEnd = false
+        }
+    }
+
+    @Test("A source failure preserves committed coverage and cached seeks, but never becomes EOF",
+           arguments: [false, true])
+    func retainedAfterSourceFailure(reordered: Bool) async throws {
+        let packets = (0..<100).map { packet(Int64($0) * 40, key: $0 == 0) }
+        let input = FailingInput(packets)
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 1024, retainConsumed: true)
+        let source = SoftwarePacketReadAhead(video: .init(index: 0, numerator: 1, denominator: 1000),
+            audio: nil, byteBudget: 1_000_000, forwardSeconds: 3600, initialSourceClock: 0,
+            fifo: fifo, videoReorderDepth: reordered ? 4 : nil) { _ in try input.next() }
+        defer { input.releaseEnd.signal(); source.close() }
+        source.start()
+        try await waitFor { input.reachedEnd.wait(timeout: .now()) == .success }
+        let before = source.residentRanges
+        #expect(!before.isEmpty)
+        let epoch = source.snapshot.sourceEpoch
+        input.releaseEnd.signal()
+        try await waitFor { source.producerParkedForTesting }
+        #expect(source.producerParkedForTesting)
+        #expect(!source.snapshot.sourceEnded)
+        #expect(source.residentRanges == before)
+        // A failure cannot flush unresolved successor PTS as though it proved a normal EOF.
+        if reordered { #expect((before.last?.upperBound ?? 4) < 3.96) }
+        try await consume(source, expecting: packets, fails: true)
+        for target in [0.5, 2.0, 1.0] {
+            let token = source.beginSeek(to: target)
+            #expect(try source.prepareSeek(token, to: target))
+            source.endSeek(token, sourceClock: target)
+            #expect(source.snapshot.sourceEpoch == epoch)
+            #expect(source.residentRanges == before)
+            try await consume(source, expecting: packets, fails: true)
+            #expect(!source.snapshot.sourceEnded)
+        }
+        // A miss still resets the failed source lifetime and accepts only the new epoch's data.
+        let replacement = (0..<100).map { packet(10_000 + Int64($0) * 40, key: $0 == 0) }
+        let miss = source.beginSeek(to: 10)
+        #expect(try !source.prepareSeek(miss, to: 10))
+        #expect(source.residentRanges.isEmpty)
+        input.replace(replacement)
+        source.endSeek(miss, sourceClock: 10)
+        try await waitFor { source.snapshot.sourceEnded }
+        #expect(source.snapshot.sourceEpoch == epoch + 1)
+        #expect(source.residentRanges.first?.lowerBound == 10)
+        try await consume(source, expecting: replacement, fails: false)
+    }
+
+    @Test("A storage append failure still invalidates retained coverage and cached seeks")
+    func storageFailureRemainsClosed() async throws {
+        let packets = (0..<10).map { packet(Int64($0) * 40) }
+        let input = Input(packets)
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 1024, retainConsumed: true)
+        let reached = DispatchSemaphore(value: 0), release = DispatchSemaphore(value: 0)
+        let source = SoftwarePacketReadAhead(video: .init(index: 0, numerator: 1, denominator: 1000),
+            audio: nil, byteBudget: 1_000_000, forwardSeconds: 3600, initialSourceClock: 0,
+            fifo: fifo) { _ in
+                if let packet = input.next() { return packet }
+                reached.signal(); release.wait()
+                return packets[0]
+            }
+        defer { release.signal(); source.close() }
+        source.start()
+        try await waitFor { reached.wait(timeout: .now()) == .success }
+        #expect(source.residentRanges == [0...0.4])
+        try fifo.close()
+        release.signal()
+        try await waitFor { source.producerParkedForTesting }
+        #expect(source.producerParkedForTesting)
+        #expect(!source.snapshot.sourceEnded)
+        #expect(source.residentRanges.isEmpty)
+        let miss = source.beginSeek(to: 0.1)
+        #expect(try !source.prepareSeek(miss, to: 0.1))
+        #expect(source.snapshot.cacheSeekHits == 0)
+    }
+
     @Test("Source origin mapping preserves gaps, clips negatives and rejects unknown origins")
     func displayMapping() {
         let spans = [90.0...105, 110...120]
diff --git a/docs/api.md b/docs/api.md
index 7ecfb3ae4..1d7cd87a2 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -590,7 +590,7 @@ Time lives on `player.clock`, a separate `ObservableObject`, so ~10 Hz ticks nev
 | `$duration` | seconds; a `LoadOptions.declaredDurationSeconds` outranks the container's |
 
 For software VOD, `residentRanges` intersects video presentation coverage with the selected audio
-stream, even if muted; a video-only source does not require audio. H.264/HEVC use verified
+stream, even if muted; a video-only source does not require audio. H.264/HEVC and VC-1 use verified
 successor-PTS intervals, so the final picture with no known successor does not acquire an invented
 end. Ranges are clipped against retained keyframes and discarded packet timestamps; unknown or
 invalid coverage stays empty. Metadata limits can conservatively omit old spans rather than claim
@@ -604,6 +604,25 @@ cannot establish a backward cache start. Live playback continues to expose its s
 window rather than VOD resident ranges.
 
 
+A source read failure preserves already committed software packets and their verified ranges.
+Cached seeks may replay them, but draining those packets still throws the original read failure;
+the error does not become EOF and does not flush unresolved successor timestamps. Storage or
+packet-envelope failures invalidate usability instead. A cold seek starts a new source lifetime.
+
+Software VOD resume and cache-miss seek positioning run off the main actor with a **30 s positioning
+budget**, measured after acquiring demux access. Waiting for an earlier read can add to the total
+call time. A deadline-bounded cold byte probe uses the existing streaming reconnect immediately;
+already resident detour blocks remain usable, and ordinary unbounded parsing keeps its detour policy.
+This allows multi-probe keyframe searches on slow remote storage to complete while retaining a finite
+I/O deadline. An unavailable source can consequently take longer to report failure.
+
+Failed software resume throws before readiness or a requested clock anchor is published. Failed
+software seek reports `.stalled` and `.softwarePipelineFailed`, clears the in-flight state, and does
+not resume decoding or finalize the target as landed. Unlike an AVPlayer seek that remains pending
+for a late landing, this software failure is terminal for the host. Stop, cancellation and newer
+seeks still prevent stale completions from changing the active session.
+
+
 **`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

From 383bad309ae4146b1b452d93268d37bb0c4b0edb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 14 Oct 2026 14:09:03 +0200
Subject: [PATCH 022/132] fix(disc): a folder with both BDMV and VIDEO_TS plays
 its Blu-ray title

#756 routed any listing that held a VIDEO_TS/ entry to the DVD path, and a
DVD path that found no title VOBs did not fall back to Blu-ray. An image is
recognized Blu-ray first with DVD as the fallback; a folder now follows the
same order, so a hybrid rip plays its Blu-ray title and a folder whose BDMV
tree holds no playable title still plays its DVD.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  3 ++-
 Sources/AetherEngine/Disc/DiscDirectory.swift |  4 ++--
 Sources/AetherEngine/Disc/DiscReader.swift    | 10 ++++++----
 Tests/AetherEngineTests/DVDFolderTests.swift  | 16 ++++++++++++++++
 docs/formats.md                               |  2 +-
 5 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6913bb09..356566aef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,8 @@ the public-API contract.
   as DVD-Video: the title sets, VMGI filtering, durations, chapters and languages come from the same code
   as an image's (`DiscReader.dvdTitleSet`, now shared), the selected title's VOBs play back to back in
   part order, and the cell timeline and VTS time map apply as on an image, since the VOBs in order are
-  the same run of bytes as their sectors. A listing without `VIDEO_TS/` is read as Blu-ray, as before.
+  the same run of bytes as their sectors. A listing without `VIDEO_TS/` is read as Blu-ray, as before,
+  and one with both trees plays its Blu-ray title, the order an image is recognized in.
 
 ### Fixed
 
diff --git a/Sources/AetherEngine/Disc/DiscDirectory.swift b/Sources/AetherEngine/Disc/DiscDirectory.swift
index 8015b2e91..50a515979 100644
--- a/Sources/AetherEngine/Disc/DiscDirectory.swift
+++ b/Sources/AetherEngine/Disc/DiscDirectory.swift
@@ -3,8 +3,8 @@ import Foundation
 /// A disc that a host serves as a FOLDER (the `BDMV` or `VIDEO_TS` tree, one address per file) rather
 /// than as a single image. Hand one to `load(source: .custom(reader))`: the engine selects the title and
 /// concatenates its clips or VOBs the same way it does for an ISO, so titles, chapters, track languages,
-/// the multi-clip and multi-cell timelines and the seek tables all behave as they do there. A listing
-/// with `VIDEO_TS/` in it is read as DVD-Video, anything else as Blu-ray.
+/// the multi-clip and multi-cell timelines and the seek tables all behave as they do there. As on an
+/// image, Blu-ray is tried first and a listing with `VIDEO_TS/` in it falls back to DVD-Video.
 ///
 /// A folder carries no bytes of its own: `read` is never called on it. The engine recognizes the
 /// conformance before it reads anything and opens the files it needs through `openDiscFile(_:)`.
diff --git a/Sources/AetherEngine/Disc/DiscReader.swift b/Sources/AetherEngine/Disc/DiscReader.swift
index 033aa440f..aba515fc8 100644
--- a/Sources/AetherEngine/Disc/DiscReader.swift
+++ b/Sources/AetherEngine/Disc/DiscReader.swift
@@ -276,10 +276,12 @@ enum DiscReader {
         // A disc folder is a set of files, not one byte range, so it is recognized before the cache,
         // which rebuilds a reader from extents of a single image.
         if let folder = reader as? DiscDirectoryReader {
-            if folder.discFiles.contains(where: { $0.path.uppercased().hasPrefix("VIDEO_TS/") }) {
-                return wrapDVDFolder(folder, selectTitleID: selectTitleID)
-            }
-            return wrapBluRayFolder(folder, selectTitleID: selectTitleID)
+            // Blu-ray first and DVD-Video as the fallback, as on an image, so a hybrid listing with both
+            // trees plays its Blu-ray title.
+            func has(_ root: String) -> Bool { folder.discFiles.contains { $0.path.uppercased().hasPrefix(root) } }
+            guard has("VIDEO_TS/") else { return wrapBluRayFolder(folder, selectTitleID: selectTitleID) }
+            if has("BDMV/"), let bluRay = wrapBluRayFolder(folder, selectTitleID: selectTitleID) { return bluRay }
+            return wrapDVDFolder(folder, selectTitleID: selectTitleID)
         }
         if let cacheKey, let cached = DiscRecognitionCache.lookup(key: cacheKey, selectTitleID: selectTitleID) {
             return DiscInfo(reader: ConcatIOReader(base: reader, extents: cached.extents),
diff --git a/Tests/AetherEngineTests/DVDFolderTests.swift b/Tests/AetherEngineTests/DVDFolderTests.swift
index 2ccebea0c..6ab92f7fd 100644
--- a/Tests/AetherEngineTests/DVDFolderTests.swift
+++ b/Tests/AetherEngineTests/DVDFolderTests.swift
@@ -51,6 +51,22 @@ struct DVDFolderTests {
         #expect(info.titles.first?.durationTicks == UInt64(2100 * discTickRate))
     }
 
+    @Test("a listing with both trees plays its Blu-ray title, and falls back to the DVD when BDMV has none")
+    func hybridListing() throws {
+        let bluRay = BluRayFolderTests.tinyStreamFolder().folder
+        let dvd = Self.folder()
+        let both = Folder(bluRay.order.map { ($0, bluRay.files[$0]!) } + dvd.order.map { ($0, dvd.files[$0]!) })
+        let info = try #require(try DiscReader.wrap(both))
+        #expect(info.formatHint == "mpegts")
+        #expect(!both.openedPaths.contains { $0.hasPrefix("VIDEO_TS/") })
+
+        let emptyBDMV = Folder([("BDMV/index.bdmv", Data([0x49, 0x4E, 0x44, 0x58]))]
+                               + dvd.order.map { ($0, dvd.files[$0]!) })
+        let fallback = try #require(try DiscReader.wrap(emptyBDMV))
+        #expect(fallback.formatHint == "mpeg")
+        #expect(BluRayFolderTests.readToEnd(fallback.reader) == Self.bytes(5, 7000) + Self.bytes(6, 4000))
+    }
+
     @Test("a VIDEO_TS folder without title VOBs is not a disc")
     func noTitleVOBs() throws {
         let folder = Folder([("VIDEO_TS/VIDEO_TS.IFO", Self.bytes(1, 2048)), ("VIDEO_TS/VIDEO_TS.VOB", Self.bytes(2, 2048))])
diff --git a/docs/formats.md b/docs/formats.md
index 04c8a53c4..4f21aba91 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -524,7 +524,7 @@ A remote `.iso` / `.img` / `.udf` needs an origin that honours HTTP `Range`, bec
 
 **Blu-ray folders.** A disc that was ripped as a `BDMV` folder rather than an image plays the same way through `MediaSource.custom` with a `DiscDirectoryReader`: the host lists the folder's files (path relative to the disc root, and size) and opens any one of them on request. `HTTPDiscDirectoryReader` is the ready-made one, with one URL per file, so an origin serves the disc as plain files over `Range` and never remuxes it. Recognition is the image path with files in place of UDF extents: the same bounded playlist scan and title selection, the selected title's `.m2ts` files concatenated in playlist order as one MPEG-TS, the same multi-clip timeline, chapters and STN track languages, and the same seek by the clips' EP maps when the folder carries `BDMV/CLIPINF`. A host that already knows the main playlist names it in `preferredPlaylist`, and only that playlist is read and published as the title. The concatenating reader opens a clip's file when the read reaches it and keeps at most three open. A controlled probe (`limits` or `cancellation`) does not recognize a folder yet; an uncontrolled `probe(source:)` and `load(source:)` do.
 
-**DVD-Video folders.** A listing that holds `VIDEO_TS/` files is read as DVD-Video instead, by the same title-set code as an image: the selected title set's VOBs are concatenated in part order, which is the same run of bytes as their sectors on a disc, so the cell timeline and the VTS time map apply unchanged. `preferredPlaylist` does not apply.
+**DVD-Video folders.** A listing that holds `VIDEO_TS/` files and no playable Blu-ray title is read as DVD-Video instead, by the same title-set code as an image: the selected title set's VOBs are concatenated in part order, which is the same run of bytes as their sectors on a disc, so the cell timeline and the VTS time map apply unchanged. `preferredPlaylist` does not apply.
 
 **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).
 

From ac6b5f7a7cd18927b0bef1ba691fba0135e8eff0 Mon Sep 17 00:00:00 2001
From: Andre Encarnacao <andreencar@gmail.com>
Date: Tue, 13 Oct 2026 09:58:50 +0200
Subject: [PATCH 023/132] fix(playback): report the software host's actual
 video decoder

---
 CHANGELOG.md                                  |  3 +
 .../AetherEngine/AetherEngine+Loading.swift   |  3 +-
 Sources/AetherEngine/AetherEngine+Probe.swift |  3 +-
 Sources/AetherEngine/AetherEngine.swift       |  3 +-
 .../Native/SoftwarePlaybackHost.swift         |  4 ++
 .../ActiveVideoDecoderTests.swift             | 65 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 7 files changed, 79 insertions(+), 4 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ActiveVideoDecoderTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 356566aef..0bbf26499 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,9 @@ the public-API contract.
 
 ### Fixed
 
+- **`activeVideoDecoder` names the decoder used by the software host (#753).** HEVC decoded by
+  VideoToolbox now reports `VideoToolbox HEVC (HW)` on initial load and reload, instead of
+  `libavcodec HEVC (SW)`. Decoder selection and playback routing are unchanged.
 - **A live GOP longer than the sealed target duration no longer breaks the playlist.** RFC 8216 keeps
   `TARGETDURATION` fixed for a playlist's life, so a later segment above it made the playlist invalid
   for AVPlayer (-12642). The engine now retires that playlist URL with its original target and an
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 077b2ced6..eaa33f1ae 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2562,7 +2562,8 @@ extension AetherEngine {
                 playbackBackend = .software
                 activeAudioTrackIndex = audioStreamIndex.map { Int($0) }
                 activeVideoDecoder = Self.videoDecoderLabel(
-                    codecID: preservedVideoCodec, isSoftware: true
+                    codecID: preservedVideoCodec,
+                    isSoftware: !(softwareHost?.usesHardwareVideoDecoder ?? false)
                 )
                 // AE#462: the rebuilt host's own resolved index (see the load site).
                 activeAudioDecoder = Self.softwareAudioDecoderLabel(
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index ecadadc6f..4a2a279a5 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -804,7 +804,8 @@ extension AetherEngine {
 
     // MARK: - Decoder identity helpers
 
-    /// User-facing label for the active video decoder. nil when no video track (AV_CODEC_ID_NONE). Native = VideoToolbox HW; SW = dav1d (AV1) or libavcodec (VP9, MPEG-2, VC-1).
+    /// User-facing label for the active video decoder. nil when no video track (AV_CODEC_ID_NONE).
+    /// isSoftware describes the decoder, not the playback path: the software host can use VideoToolbox.
     static func videoDecoderLabel(codecID: AVCodecID, isSoftware: Bool) -> String? {
         guard codecID != AV_CODEC_ID_NONE else { return nil }
         let name: String = {
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5a5629242..39463ec3b 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -5262,7 +5262,8 @@ public final class AetherEngine: ObservableObject {
                     )
                 }
                 activeVideoDecoder = Self.videoDecoderLabel(
-                    codecID: detectedCodecID, isSoftware: true
+                    codecID: detectedCodecID,
+                    isSoftware: !(softwareHost?.usesHardwareVideoDecoder ?? false)
                 )
                 // AE#462: the host's own resolved index, not the engine's pick. The pick says which
                 // track was ASKED for; only the host knows whether a decoder opened for it, and this
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 9817a8f6e..2c92ad60f 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -111,6 +111,10 @@ final class SoftwarePlaybackHost {
     /// point it uses for `AVPlayerLayer`.
     var displayLayer: AVSampleBufferDisplayLayer { renderer.displayLayer }
 
+    /// Whether load selected VideoToolbox rather than libavcodec / dav1d for video decoding.
+    /// Only meaningful after load has returned successfully.
+    var usesHardwareVideoDecoder: Bool { videoDecoder is HardwareVideoDecoder }
+
     /// AE#711 follow-up: the picture on screen now, read back from the renderer before a rebuild's
     /// `stop()` flushes it, so the engine can hold it over the new host's startup. Falls back to the
     /// newest frame enqueued, which a layer that is not on screen is all there is of.
diff --git a/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift b/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift
new file mode 100644
index 000000000..8c17146a4
--- /dev/null
+++ b/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift
@@ -0,0 +1,65 @@
+import Foundation
+import Testing
+import VideoToolbox
+@testable import AetherEngine
+
+/// AE#753: the software playback host can use VideoToolbox. Exercise the public label after
+/// both initial load and a session rebuild, rather than testing the label formatter alone.
+/// These synthetic clips are local-only; generate them with Scripts/fetch-fixtures.sh.
+@Suite("Active video decoder identity", .serialized)
+@MainActor
+struct ActiveVideoDecoderTests {
+    private nonisolated static func fixture(_ name: String) -> URL {
+        URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+            .appendingPathComponent("Fixtures").appendingPathComponent(name)
+    }
+
+    private nonisolated static func hasFixture(_ name: String) -> Bool {
+        FileManager.default.fileExists(atPath: fixture(name).path)
+    }
+
+    private func checkLoadAndReload(_ name: String, label: String) async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        var options = LoadOptions()
+        options.preferredDecodePath = .software
+        options.suppressDisplayCriteria = true
+        // A seekable custom source makes reloadAtCurrentPosition exercise the separate
+        // reloadWithAudioOverride path, rather than calling the initial URL load again.
+        let reader = DataIOReader(data: try Data(contentsOf: Self.fixture(name)))
+        _ = try await engine.load(source: .custom(reader), options: options)
+        engine.pause()
+        #expect(engine.playbackBackend == .software)
+        #expect(engine.activeVideoDecoder == label, "initial load must name the actual decoder")
+
+        _ = try await engine.reloadAtCurrentPosition()
+        #expect(engine.playbackBackend == .software)
+        #expect(engine.activeVideoDecoder == label, "reload must name the newly opened decoder")
+    }
+
+    @Test("HEVC decoded by VideoToolbox on the software path (#753)",
+          .enabled(if: hasFixture("hdr10-hevc.mp4") && VTIsHardwareDecodeSupported(kCMVideoCodecType_HEVC)),
+          .timeLimit(.minutes(1)))
+    func hardwareHEVC() async throws {
+        try await checkLoadAndReload("hdr10-hevc.mp4", label: "VideoToolbox HEVC (HW)")
+    }
+
+    @Test("HEVC with in-band parameter sets still reports libavcodec",
+          .enabled(if: hasFixture("hev1-inband-xps.mp4")), .timeLimit(.minutes(1)))
+    func softwareHEVC() async throws {
+        try await checkLoadAndReload("hev1-inband-xps.mp4", label: "libavcodec HEVC (SW)")
+    }
+
+    @Test("VP9 still reports libavcodec",
+          .enabled(if: hasFixture("vp9.webm")), .timeLimit(.minutes(1)))
+    func softwareVP9() async throws {
+        try await checkLoadAndReload("vp9.webm", label: "libavcodec VP9 (SW)")
+    }
+
+    @Test("AV1 still reports dav1d",
+          .enabled(if: hasFixture("av1.mp4")), .timeLimit(.minutes(1)))
+    func softwareAV1() async throws {
+        try await checkLoadAndReload("av1.mp4", label: "dav1d AV1 (SW)")
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index c4d62d9ce..6503bc7d2 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -682,7 +682,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$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 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. |
+| `$activeVideoDecoder`, `$activeAudioDecoder` | The decoder names actually in use, for a stats overlay. This is the honest "what is decoding this" surface; `playbackBackend` is not. The software playback host can use VideoToolbox for HEVC, in which case `$activeVideoDecoder` reports `VideoToolbox HEVC (HW)` on load and reload even though `playbackBackend` is `.software`. 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. |
 | `$currentAVPlayer`, `$currentAVPlayerItem` | The live AVFoundation objects, re-emitted on every reload. Both nil on `.software`, which renders into its own layer. A host that only ever hands `currentAVPlayer` to an `AVPlayerViewController` gets audio over an empty video plane on that route (#298). |

From 249bfe210d103752041b2d8580eb06b8eaaeab4c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 14 Oct 2026 14:55:26 +0200
Subject: [PATCH 024/132] fix(demux): keep non-video order across the
 missing-head handover (#761)

When the whole-file probe hands its held sample to the slot session, nothing
is dequeued in between. A non-video packet arriving while the session had no
pending picture returned false and went back into the parent's own queue,
which is drained ahead of the session's ready queue, so it overtook audio the
session had already taken: on the missing-head fixture audio DTS -1024 left
after 16384. It now queues behind the session's ready packets; in steady state
the demuxer drains before every read, so nothing else changes.

The runtime harness now requires every non-video stream to leave in DTS order
(fails on the previous code), and the all-stream budget check drains between
packets as the demuxer does.

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

diff --git a/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift b/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift
index bec0e4c3b..417dab26d 100644
--- a/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift
+++ b/Scripts/tests/H264PartialCompositionRuntimeStandalone.swift
@@ -87,6 +87,7 @@ struct H264PartialCompositionRuntimeTests {
             avcodec_flush_buffers(raw); avcodec_flush_buffers(fixed)
             var rawPTS: [Int64] = [], fixedPTS: [Int64] = []
             var videoRead = 0, reads = 0, delivered = 0, stop = false, observedRepair = false
+            var lastOther: [Int32: Int64] = [:]
             func emit(_ packet: UnsafeMutablePointer<AVPacket>) throws {
                 defer { var owned: UnsafeMutablePointer<AVPacket>? = packet; trackedPacketFree(&owned) }
                 let expected = inputs.removeValue(forKey: UInt(bitPattern: packet))!
@@ -102,7 +103,14 @@ struct H264PartialCompositionRuntimeTests {
                         precondition(twinPTS[actual.dts] == actual.pts, "repaired video PTS must exactly match its healthy twin")
                     }
                     try decode(fixed, packet: packet, into: &fixedPTS)
-                } else { precondition(actual == expected) }
+                } else {
+                    precondition(actual == expected)
+                    // Other streams keep the container's order: a held packet must not overtake one
+                    // that was handed over before it.
+                    precondition(lastOther[actual.streamIndex].map { actual.dts > $0 } ?? true,
+                                 "non-video packet left the session out of order")
+                    lastOther[actual.streamIndex] = actual.dts
+                }
                 delivered += 1
             }
             while !stop {
@@ -234,6 +242,9 @@ struct H264PartialCompositionRuntimeTests {
             guard let packet = trackedPacketAlloc() else { throw Failure.demux }
             packet.pointee.stream_index = index + 1
             if session.ingest(packet) { heldForeign += 1 } else { av_packet_free_safe(packet) }
+            // The demuxer drains the queue before every read, so a released packet is gone again
+            // before the next one arrives.
+            while let released = session.dequeue() { av_packet_free_safe(released) }
         }
         precondition(heldForeign > 0 && heldForeign <= H264PartialCompositionRepair.maximumHeldPackets,
                      "the all-stream budget has to end the hold, held \(heldForeign)")
diff --git a/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift b/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift
index 825d831be..15f096f3b 100644
--- a/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift
+++ b/Sources/AetherEngine/Video/H264PartialCompositionRepairSession.swift
@@ -90,7 +90,7 @@ final class H264PartialCompositionRepairSession {
     /// Returns true when the packet was taken over and must not be emitted yet.
     func ingest(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
         guard packet.pointee.stream_index == streamIndex else {
-            guard !pending.isEmpty else { return false }
+            guard !pending.isEmpty else { return handBack(packet) }
             append(packet, rank: nil)
             drain()
             enforceBounds()

From a65688e2f9c381d0e6b27005655649b816682407 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 14 Oct 2026 16:56:42 +0200
Subject: [PATCH 025/132] fix(demux): refuse a CFR reconstruction that presents
 before it decodes (#762)

The clamped-CFR verdict and its rewriter derived PTS from picture order and
DTS from decode order without checking that one does not precede the other.
A stream whose ranks lag their decode index by more than the reorder delay
would have been handed out with PTS < DTS. Both now fail closed on that, the
verdict back to the previous path and the rewriter to untouched packets.

Also covers the path #762 changed for #511 files: a coding-order ladder on a
whole-tick lattice still classifies as a permutation, not a reconstruction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  3 +-
 .../Video/H264MatroskaSlotPermutation.swift   | 10 +++++
 .../Issue511MatroskaCodingOrderTests.swift    | 41 +++++++++++++++++++
 3 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2addd6e39..cbc29c6c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,7 +28,8 @@ the public-API contract.
   recognizes that shape only from an exact CFR lattice, complete picture-order ranks and two
   corroborating clamps, then reconstructs PTS and DTS from the IDR anchor, picture order and decode
   order. A seek starts from a new IDR, and overflow or any later timestamp outside the proven shape
-  disables the repair and leaves that packet untouched.
+  disables the repair and leaves that packet untouched, as does a reconstruction that would present a
+  picture before its decode time.
 - **H.264 MP4s with missing composition offsets keep display order across cadence changes and
   hierarchical B pictures.** A corroborated missing-offset head with a changing decode cadence now
   reuses the existing timestamp slots. Later zero-offset regions can prove a forward-coded anchor
diff --git a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
index 6e6adf862..4b1deebd5 100644
--- a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
+++ b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
@@ -165,6 +165,12 @@ enum H264MatroskaSlotPermutation {
                     reconstructable = false
                     break
                 }
+                // A reconstruction that would present a picture before it is decoded describes some
+                // other stream, and handing it out would break the decoder instead of the cadence.
+                guard expectedPTS >= expectedDTS else {
+                    reconstructable = false
+                    break
+                }
                 if sample.pts != expectedPTS {
                     let (forward, overflow) = sample.pts.subtractingReportingOverflow(expectedPTS)
                     guard !overflow, sample.pts == sample.dts, forward == step,
@@ -251,6 +257,10 @@ enum H264MatroskaSlotPermutation {
                 brokenReason = "timestamp reconstruction overflowed"
                 return nil
             }
+            guard expectedPTS >= expectedDTS else {
+                brokenReason = "reconstructed pts=\(expectedPTS) precedes dts=\(expectedDTS)"
+                return nil
+            }
 
             let ptsForward = pts.subtractingReportingOverflow(expectedPTS)
             let dtsForward = dts.subtractingReportingOverflow(expectedDTS)
diff --git a/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift b/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
index 09d0f1c0f..b0da9de0e 100644
--- a/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
+++ b/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
@@ -88,6 +88,16 @@ struct Issue511MatroskaCodingOrderTests {
         #expect(Permutation.classify(samples: window, videoDelay: 1) == .permute(pocStep: 2))
     }
 
+    @Test("coding-order slots on a whole-tick CFR lattice still permute rather than reconstruct")
+    func codingOrderOnWholeTickLatticeStillPermutes() {
+        let count = Permutation.sampleTarget
+        let slots = (0..<count).map { Int64($0) * 40 }
+        let window = Self.samples(
+            slots: slots, pocs: Array(Self.reportedPictureOrder.prefix(count)))
+        #expect(Permutation.classify(samples: window, videoDelay: 1, nominalStep: 40)
+            == .permute(pocStep: 2))
+    }
+
     @Test("every picture carries the slot its own display rank owns, and the multiset is the file's")
     func permutesTheReportedSequence() throws {
         let sequenceSamples = Array(
@@ -234,6 +244,37 @@ struct Issue511MatroskaCodingOrderTests {
         #expect(broken.rewrite(pts: 80, dts: 0, pictureOrderCount: 4, isKeyframe: false) == nil)
     }
 
+    @Test("a clamp whose reconstruction would present before it decodes is left alone")
+    func clampReconstructingBeforeDecodeFailsClosed() {
+        let n = Int64.min
+        let samples = [
+            Sample(dts: n, pts: 0, pictureOrderCount: 0, isKeyframe: true),
+            Sample(dts: n, pts: 200, pictureOrderCount: 10, isKeyframe: false),
+            Sample(dts: 0, pts: 80, pictureOrderCount: 4, isKeyframe: false),
+            Sample(dts: 80, pts: 80, pictureOrderCount: 2, isKeyframe: false),
+            Sample(dts: 80, pts: 120, pictureOrderCount: 6, isKeyframe: false),
+            Sample(dts: 120, pts: 160, pictureOrderCount: 8, isKeyframe: false),
+            Sample(dts: 160, pts: 440, pictureOrderCount: 22, isKeyframe: false),
+            Sample(dts: 200, pts: 320, pictureOrderCount: 16, isKeyframe: false),
+            Sample(dts: 240, pts: 280, pictureOrderCount: 14, isKeyframe: false),
+            // Rank 6 decoded at index 9: its slot 240 would sit before the decode slot 280.
+            Sample(dts: 280, pts: 280, pictureOrderCount: 12, isKeyframe: false),
+            Sample(dts: 320, pts: 360, pictureOrderCount: 18, isKeyframe: false),
+            Sample(dts: 360, pts: 400, pictureOrderCount: 20, isKeyframe: false),
+        ]
+        #expect(Permutation.classify(samples: samples, videoDelay: 2, nominalStep: 40) == .healthy)
+
+        var rewriter = Permutation.CFRRewriter(step: 40, pocStep: 2, videoDelay: 2)
+        let repaired = samples.map {
+            rewriter.rewrite(
+                pts: $0.pts, dts: $0.dts, pictureOrderCount: $0.pictureOrderCount,
+                isKeyframe: $0.isKeyframe)
+        }
+        #expect(repaired[8] != nil)
+        #expect(repaired[9] == nil)
+        #expect(rewriter.brokenReason?.contains("precedes") == true)
+    }
+
     @Test("shapes this permutation does not describe are left alone")
     func failsClosed() {
         func verdict(slots: [Int64], pocs: [Int64], videoDelay: Int = 1) -> Permutation.Verdict {

From 3d4562e8add56fefcae5327eb75db3ea5b7e00ff Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Tue, 13 Oct 2026 07:55:58 +0100
Subject: [PATCH 026/132] fix(renderer): hand FEL frames over in arrival order
 with a minimum-upcoming hint

The dual-layer decoder delivers frames in decode order. The renderer held four of them to reorder,
which left the FEL look-ahead window four frames short and dropped about one frame in five on
Apple TV. AVSampleBufferVideoRenderer sorts by presentation time itself if it is told the lowest
timestamp still to come, so the FEL path now hands every frame over as it arrives and sets
presentationTimeExpectation = .minimumUpcoming(floor).

PresentationFloor computes that floor: the first gap in the frame grid, half a frame up, given up
once the clock passes a slot that never arrives. After a seek it starts at the skip threshold,
since B-frames below the next anchor arrive after it.

Apple TV, three rounds: drops 17/296/289 -> 6/5/5, same memory footprint. Without a frame rate the
renderer keeps the reorder buffer.
---
 .../Native/SoftwarePlaybackHost.swift         |   9 +-
 .../Renderer/PresentationFloor.swift          |  90 +++++++
 .../Renderer/SampleBufferRenderer.swift       | 133 +++++++++-
 .../PresentationFloorTests.swift              | 228 ++++++++++++++++++
 4 files changed, 446 insertions(+), 14 deletions(-)
 create mode 100644 Sources/AetherEngine/Renderer/PresentationFloor.swift
 create mode 100644 Tests/AetherEngineTests/PresentationFloorTests.swift

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index f8800a22d..3027d397e 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1045,13 +1045,18 @@ final class SoftwarePlaybackHost {
 
         // Audit PERF-104: only the VideoToolbox decoders emit out of presentation order. That includes the
         // DualLayerVideoDecoder: OrderedDelivery keeps its frames in the order the base layer came out of
-        // VideoToolbox, which is decode order (measured on the real fixtures, `DoviFelRealFileTests`), so it
-        // needs the same reorder depth as the single-layer hardware decoder.
+        // VideoToolbox, which is decode order (measured on the real fixtures, `DoviFelRealFileTests`). It gets
+        // the same reorder depth as the single-layer hardware decoder, used only when arrival-order handover
+        // below is off (no frame rate).
         renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(
             forHardwareDecoder: videoDecoder is HardwareVideoDecoder || videoDecoder is DualLayerVideoDecoder))
         renderer.setFELLookahead(
             enabled: videoDecoder is DualLayerVideoDecoder,
             frameRate: AetherEngine.detectFrameRate(stream: vStream))
+        // The FEL look-ahead window only holds if none of it waits in the reorder buffer; see
+        // `SampleBufferRenderer.arrivalFloor`. Without a frame rate it stays on the reorder buffer.
+        renderer.setArrivalOrderHandover(
+            frameRate: videoDecoder is DualLayerVideoDecoder ? AetherEngine.detectFrameRate(stream: vStream) : nil)
 
         // 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 {
diff --git a/Sources/AetherEngine/Renderer/PresentationFloor.swift b/Sources/AetherEngine/Renderer/PresentationFloor.swift
new file mode 100644
index 000000000..aa383f671
--- /dev/null
+++ b/Sources/AetherEngine/Renderer/PresentationFloor.swift
@@ -0,0 +1,90 @@
+import Foundation
+
+/// The lowest presentation time still to come, for a renderer that is handed frames in decode order.
+///
+/// `AVSampleBufferVideoRenderer` sorts the frames it is given by presentation time on its own, but a
+/// frame that arrives in decode order cannot be shown until the queue knows nothing earlier is still
+/// on its way. An app tells it through `presentationTimeExpectation = .minimumUpcoming(_:)`. Without that bound a
+/// Mac test dropped 25 to 50% of frames for hierarchical-B GOPs of 8 to 16, and with it none.
+///
+/// The bound is the first gap in the frame grid. `frontier` is the newest timestamp below which
+/// every slot has been handed over; frames past it wait in `ahead` until the slots before them fill.
+/// The floor sits half a frame past the frontier, below the next slot even when a container rounds
+/// its timestamps to the millisecond. A slot the clock has already passed is given up, so a frame
+/// that never comes (a decode failure, a gap in the stream) cannot hold the floor down for good.
+///
+/// Pure: the renderer owns one, guards it with its lock and feeds it the clock.
+struct PresentationFloor {
+
+    /// Seconds per frame.
+    let interval: Double
+
+    /// Newest timestamp with every earlier slot handed over; nil until the first frame or a start.
+    private(set) var frontier: Double?
+    /// Handed-over timestamps past the frontier, ascending.
+    private(set) var ahead: [Double] = []
+    /// What the renderer has been promised. Never moves down between resets.
+    private(set) var floor: Double = -.infinity
+
+    /// How far past the frontier the clock may be and still give up slots, in seconds.
+    static let maxClockGap: Double = 1
+
+    init(interval: Double) {
+        self.interval = interval
+    }
+
+    struct Step: Equatable {
+        /// Timestamps that joined the frontier with this frame, in display order: the cadence the
+        /// renderer will actually show, for the spacing diagnostic.
+        var contiguous: [Double] = []
+        /// The new floor, when it moved; nil when the promise is unchanged.
+        var raisedFloor: Double?
+        /// The frame arrived below a floor already promised. It is still handed over, and the
+        /// renderer may drop it.
+        var belowFloor = false
+    }
+
+    /// Forgets everything (a flush). `start` is the lowest timestamp that can still arrive, when the
+    /// caller knows it: after a seek the first frame past the skip threshold need not be the lowest
+    /// one to come, since B-frames below it arrive after it in decode order, so the frontier starts
+    /// just below the threshold rather than at that frame.
+    mutating func reset(start: Double? = nil) {
+        frontier = start.map { $0 - interval }
+        ahead.removeAll()
+        floor = -.infinity
+    }
+
+    /// Records a frame handed to the renderer. `clockSeconds` is the playback clock on the same axis,
+    /// nil while it is not running.
+    mutating func record(_ pts: Double, clockSeconds: Double?) -> Step {
+        var step = Step()
+        var f = frontier ?? (pts - interval)
+        if pts < floor {
+            step.belowFloor = true
+        } else if pts > f {
+            let i = ahead.firstIndex(where: { $0 > pts }) ?? ahead.endIndex
+            ahead.insert(pts, at: i)
+        }
+        // A clock more than `maxClockGap` past the frontier is not this stream's: a renderer not yet
+        // attached to its synchronizer runs on host time.
+        let clock = clockSeconds.flatMap { $0.isFinite && $0 - f <= Self.maxClockGap ? $0 : nil }
+        while true {
+            if let next = ahead.first, next < f + 1.5 * interval {
+                step.contiguous.append(next)
+                f = max(f, next)
+                ahead.removeFirst()
+            } else if let clock, f + interval < clock {
+                f += interval  // a slot the clock has passed: anything still owed there is late anyway
+            } else {
+                break
+            }
+        }
+        frontier = f
+        let candidate = f + 0.5 * interval
+        if candidate > floor {
+            floor = candidate
+            step.raisedFloor = candidate
+        }
+        return step
+    }
+}
diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 1a9df1de3..7573205d1 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -7,7 +7,9 @@ import CoreVideo
 ///
 /// 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.
+/// being enqueued to the display layer in strict presentation order. The FEL path skips it and
+/// hands frames over in decode order with a floor on upcoming timestamps instead
+/// (`setArrivalOrderHandover(frameRate:)`).
 final class SampleBufferRenderer: @unchecked Sendable {
 
     let displayLayer: AVSampleBufferDisplayLayer
@@ -54,6 +56,50 @@ final class SampleBufferRenderer: @unchecked Sendable {
         reorderLock.unlock()
     }
 
+    /// Arrival-order handover: frames go to the renderer the moment they arrive, in decode order,
+    /// and `presentationTimeExpectation = .minimumUpcoming(_:)` tells it the lowest timestamp still to
+    /// come (`PresentationFloor`), so the renderer sorts by presentation time itself. The reorder
+    /// buffer is bypassed. Used on the FEL path, where the held frames came out of the look-ahead
+    /// budget: with 4 held inside a 9-frame window the layer dropped about 1 frame in 5 on the Apple
+    /// TV (A12), and handing them over instead took that to the 4 to 6 a run drops with the compose
+    /// skipped altogether, at no extra memory (2026-10-13, three interleaved rounds each).
+    /// Guarded by `reorderLock`; nil uses the reorder buffer.
+    private var arrivalFloor: PresentationFloor?
+
+    /// The seek threshold on the arrival-order path, which outlives the first frame past it:
+    /// `skipUntilPTS` is cleared by that frame, but in decode order it is the GOP's next anchor, and
+    /// B-frames below the target still follow it. Cleared by `flush`. Guarded by `reorderLock`.
+    private var arrivalSkipBelow: Double?
+
+    /// Frames that arrived below a floor the renderer had already been promised. Still handed over
+    /// (the renderer may drop them), counted so a stream that breaks the promise is visible.
+    /// Guarded by `reorderLock`.
+    private var _framesBelowFloor = 0
+    var framesBelowFloor: Int {
+        reorderLock.lock()
+        defer { reorderLock.unlock() }
+        return _framesBelowFloor
+    }
+
+    /// Switches arrival-order handover on for a stream of `frameRate` frames per second, or off with
+    /// nil. Stays off without a usable rate, since the floor walks the frame grid and a wrong grid
+    /// would promise past frames still to come, and on visionOS 1.0, which has no expectation API.
+    func setArrivalOrderHandover(frameRate: Double?) {
+        reorderLock.lock()
+        defer { reorderLock.unlock() }
+        if #available(visionOS 1.1, *), let rate = frameRate, rate.isFinite, rate > 0 {
+            arrivalFloor = PresentationFloor(interval: 1 / rate)
+        } else {
+            arrivalFloor = nil
+        }
+    }
+
+    var handsOverInArrivalOrder: Bool {
+        reorderLock.lock()
+        defer { reorderLock.unlock() }
+        return arrivalFloor != nil
+    }
+
     /// Frames waiting for a smaller presentation time. Diagnostics and tests.
     var heldFrameCount: Int {
         reorderLock.lock()
@@ -65,10 +111,10 @@ final class SampleBufferRenderer: @unchecked Sendable {
     /// the FEL path. The gate runs BEFORE decode, so the decode + EL + compose latency (a few frames)
     /// comes out of this budget: 5 left a displayed lead of ~0 and the layer dropped 9 frames/s
     /// on device, against 0.5 s and no drops with no cap. A composed 4K frame costs ~25 MB, and
-    /// Apple's readiness gate alone allowed ~12 of them. Includes frames held in our reorder buffer, which is
-    /// `hardwareDecoderReorderDepth` deep on this path too: the held frames sit inside the window, so a
-    /// composer output pool sized from this cap does not grow with the reorder depth, but they
-    /// are frames the display layer has not been handed, so the lead it holds is that much smaller.
+    /// Apple's readiness gate alone allowed ~12 of them. The FEL path hands frames over in arrival
+    /// order (`setArrivalOrderHandover`), so none of the window sits in our reorder buffer: with
+    /// `hardwareDecoderReorderDepth` frames held there instead, the display layer was 4 frames short
+    /// of this budget and dropped about 1 frame in 5 on the Apple TV.
     static let felVideoLookaheadFrames = 9
     private var felFrameRate: Double?  // guarded by reorderLock; nil leaves non-FEL pacing unchanged
     /// Highest compressed-packet PTS the gate has seen, and the largest amount any later packet's PTS
@@ -426,6 +472,12 @@ final class SampleBufferRenderer: @unchecked Sendable {
     func setSkipThreshold(_ time: CMTime?) {
         reorderLock.lock()
         skipUntilPTS = time
+        // Nothing below the threshold will be handed over, and the first frame past it need not be
+        // the lowest one to come, so the floor starts here rather than at that frame.
+        if arrivalFloor != nil, let time, time.isNumeric {
+            arrivalFloor?.reset(start: CMTimeGetSeconds(time))
+            arrivalSkipBelow = CMTimeGetSeconds(time)
+        }
         reorderLock.unlock()
     }
 
@@ -465,6 +517,11 @@ final class SampleBufferRenderer: @unchecked Sendable {
         }
 
         let ptsSeconds = CMTimeGetSeconds(pts)
+        if arrivalFloor != nil {
+            handOverOnArrival(pixelBuffer: pixelBuffer, pts: pts, ptsSeconds: ptsSeconds,
+                              hdr10PlusData: hdr10PlusData)
+            return
+        }
         if let handed = _lastReleasedPtsSeconds, ptsSeconds < handed {
             _outOfOrderFramesDropped += 1
             let dropped = _outOfOrderFramesDropped
@@ -504,6 +561,50 @@ final class SampleBufferRenderer: @unchecked Sendable {
         reorderLock.unlock()
     }
 
+    /// Arrival-order handover (see `arrivalFloor`). Called with `reorderLock` held; returns with it
+    /// released. The frame goes out with no duration: its successor in display order may not have
+    /// arrived yet, and an open-ended frame is what the layer had before #407 anyway. The floor is
+    /// raised after the enqueue, so it never claims a frame that is still on its way in.
+    private func handOverOnArrival(pixelBuffer: CVPixelBuffer, pts: CMTime, ptsSeconds: Double,
+                                   hdr10PlusData: Data?) {
+        if let below = arrivalSkipBelow, ptsSeconds < below {
+            reorderLock.unlock()
+            return
+        }
+        // #303: the newest timestamp admitted, as on the reorder path.
+        if ptsSeconds > (_newestEnqueuedPtsSeconds ?? -.greatestFiniteMagnitude) {
+            _newestEnqueuedPtsSeconds = ptsSeconds
+        }
+        let timeline = _timeline
+        var clock: Double?
+        if let timebase = videoRenderer.timebase as CMTimebase?, CMTimebaseGetRate(timebase) > 0 {
+            let rendererSeconds = CMTimeGetSeconds(CMTimebaseGetTime(timebase))
+            clock = timeline?.sourceSeconds(forRenderer: rendererSeconds) ?? rendererSeconds
+        }
+        guard let step = arrivalFloor?.record(ptsSeconds, clockSeconds: clock) else {
+            reorderLock.unlock()
+            return
+        }
+        if step.belowFloor { _framesBelowFloor += 1 }
+        let belowCount = _framesBelowFloor
+        let floor = arrivalFloor?.floor
+        reorderLock.unlock()
+
+        flushFrame(pixelBuffer: pixelBuffer, pts: pts, hdr10PlusData: hdr10PlusData,
+                   displayOrderSpacing: step.contiguous)
+        if let raised = step.raisedFloor, #available(visionOS 1.1, *) {
+            let source = CMTime(seconds: raised, preferredTimescale: 90_000)
+            videoRenderer.presentationTimeExpectation =
+                .minimumUpcoming(timeline?.rendererTime(forSource: source) ?? source)
+        }
+        if step.belowFloor, belowCount == 1 || belowCount % 250 == 0 {
+            EngineLog.emit(
+                "[Renderer] frame at \(String(format: "%.3f", ptsSeconds))s arrived below the promised floor "
+                + "\(String(format: "%.3f", floor ?? .nan))s (\(belowCount) so far); handed over anyway",
+                category: .swPlayback)
+        }
+    }
+
     /// AE#711 follow-up: the newest frame handed to the layer, before the subtitle compositor, for a
     /// rebuild to hold when the layer cannot say what it is showing (off screen, or before tvOS 17.4's
     /// readback has anything). At most one buffer, released by `flush`.
@@ -524,6 +625,9 @@ final class SampleBufferRenderer: @unchecked Sendable {
         // not a cadence measurement. Left standing, every seek would report one enormous interval.
         _lastHandedPtsSeconds = nil
         _lastReleasedPtsSeconds = nil
+        // The renderer's own flush below also drops the expectation it was given.
+        arrivalFloor?.reset()
+        arrivalSkipBelow = 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.
@@ -559,8 +663,11 @@ final class SampleBufferRenderer: @unchecked Sendable {
 
     // MARK: - Internal
 
+    /// `displayOrderSpacing` replaces `pts` in the #407 spacing measurement on the arrival-order
+    /// path, where consecutive handovers are in decode order and their gaps say nothing about cadence:
+    /// it lists the timestamps that this frame made contiguous, in the order they will be shown.
     private func flushFrame(pixelBuffer: CVPixelBuffer, pts: CMTime, hdr10PlusData: Data?,
-                            nextPTS: CMTime? = nil) {
+                            nextPTS: CMTime? = nil, displayOrderSpacing: [Double]? = nil) {
         let outputBuffer = subtitleCompositor.composite(pixelBuffer, ptsSeconds: pts.seconds)
         reorderLock.lock()
         let timeline = _timeline
@@ -618,14 +725,16 @@ final class SampleBufferRenderer: @unchecked Sendable {
         reorderLock.lock()
         enqueueCount += 1
         // #407: the spacing of what the layer was given, which is the thing a frame COUNT cannot say.
-        if let previous = _lastHandedPtsSeconds {
-            let delta = CMTimeGetSeconds(pts) - previous
-            if delta.isFinite {
-                _minHandedDeltaSeconds = min(_minHandedDeltaSeconds, delta)
-                _maxHandedDeltaSeconds = max(_maxHandedDeltaSeconds, delta)
+        for shown in displayOrderSpacing ?? [CMTimeGetSeconds(pts)] {
+            if let previous = _lastHandedPtsSeconds {
+                let delta = shown - previous
+                if delta.isFinite {
+                    _minHandedDeltaSeconds = min(_minHandedDeltaSeconds, delta)
+                    _maxHandedDeltaSeconds = max(_maxHandedDeltaSeconds, delta)
+                }
             }
+            _lastHandedPtsSeconds = shown
         }
-        _lastHandedPtsSeconds = CMTimeGetSeconds(pts)
         let handed = enqueueCount
         reorderLock.unlock()
         // Sparse milestones so a stall is distinguishable from "logging stopped at #30"; bounded to 4 lines/hour at 60 fps.
diff --git a/Tests/AetherEngineTests/PresentationFloorTests.swift b/Tests/AetherEngineTests/PresentationFloorTests.swift
new file mode 100644
index 000000000..db4ae3875
--- /dev/null
+++ b/Tests/AetherEngineTests/PresentationFloorTests.swift
@@ -0,0 +1,228 @@
+import Foundation
+import Testing
+import AVFoundation
+import CoreMedia
+import CoreVideo
+@testable import AetherEngine
+
+/// The FEL path hands frames to the renderer in decode order and promises it a floor on the
+/// timestamps still to come (`PresentationFloor`). The promise is only useful if it is never broken:
+/// a frame that arrives below it may be dropped. These walk real decode orders (hierarchical-B GOPs
+/// of 4, 8 and 16, as VideoToolbox emits them) and check the floor never passes a frame still to come.
+@Suite("Presentation floor for arrival-order handover")
+struct PresentationFloorTests {
+
+    static let fps = 24.0
+    static let interval = 1 / fps
+
+    /// Display indices in decode order for a hierarchical-B GOP of `gop`: anchor first, then bisection.
+    static func decodeOrder(gop: Int, frames: Int, startingAt base0: Int = 0) -> [Int] {
+        var out = [base0]
+        func bisect(_ lo: Int, _ hi: Int) {
+            guard hi - lo >= 2 else { return }
+            let mid = (lo + hi) / 2
+            out.append(mid); bisect(lo, mid); bisect(mid, hi)
+        }
+        var base = base0
+        while base + gop < base0 + frames {
+            out.append(base + gop); bisect(base, base + gop); base += gop
+        }
+        for i in (base + 1)..<(base0 + frames) { out.append(i) }
+        return out
+    }
+
+    /// Feeds `order` (display indices) and checks, after every frame, that nothing still to come sits
+    /// below the floor. Returns the floor and the display-order spacing it reported.
+    static func walk(_ order: [Int], start: Double? = nil, clock: (Int) -> Double? = { _ in nil },
+                     timestamp: (Int) -> Double = { Double($0) * interval })
+        -> (floor: PresentationFloor, shown: [Double], violations: Int) {
+        var floor = PresentationFloor(interval: interval)
+        floor.reset(start: start)
+        var shown: [Double] = []
+        var violations = 0
+        for (k, index) in order.enumerated() {
+            let step = floor.record(timestamp(index), clockSeconds: clock(k))
+            if step.belowFloor { violations += 1 }
+            shown += step.contiguous
+            let stillToCome = order[(k + 1)...].map(timestamp)
+            if let lowest = stillToCome.min(), lowest < floor.floor { violations += 1 }
+        }
+        return (floor, shown, violations)
+    }
+
+    @Test("In display order the floor follows every frame", arguments: [0, 4, 8, 16])
+    func neverPassesAFrameStillToCome(gop: Int) {
+        let order = gop == 0 ? Array(0..<96) : Self.decodeOrder(gop: gop, frames: 96)
+        #expect(Set(order) == Set(0..<96), "the generator covers every frame once")
+        let r = Self.walk(order)
+        #expect(r.violations == 0)
+        // Every frame joins the frontier exactly once, in display order.
+        #expect(r.shown == (0..<96).map { Double($0) * Self.interval })
+        #expect(abs(r.floor.floor - (95.5 * Self.interval)) < 1e-9)
+        #expect(r.floor.ahead.isEmpty)
+    }
+
+    @Test("The floor rises within a GOP, not only at its end")
+    func risesInsideTheGOP() {
+        // GOP of 8: 0, 8, 4, 2, 1, 3, 6, 5, 7. Once 1 arrives, 0..4 are contiguous.
+        var floor = PresentationFloor(interval: Self.interval)
+        var raised: [Double?] = []
+        for i in [0, 8, 4, 2, 1] { raised.append(floor.record(Double(i) * Self.interval, clockSeconds: nil).raisedFloor) }
+        #expect(raised[1] == nil && raised[2] == nil && raised[3] == nil, "8, 4 and 2 leave a gap below them")
+        #expect(abs((raised[4] ?? 0) - 2.5 * Self.interval) < 1e-9, "1 closes the gap up to 2")
+    }
+
+    @Test("After a seek the floor starts at the threshold, not at the first frame past it")
+    func startsAtTheSeekThreshold() {
+        // Decoding restarts at the GOP's anchor below the target; frames below the target are skipped
+        // before they reach the floor, so the first one it sees is the next anchor, ABOVE B-frames
+        // that arrive after it.
+        let target = 100
+        let order = Self.decodeOrder(gop: 8, frames: 48, startingAt: 96).filter { $0 >= target }
+        #expect(order.first == 104, "the anchor past the target arrives before 100...103")
+        let seeded = Self.walk(order, start: Double(target) * Self.interval)
+        #expect(seeded.violations == 0)
+        let unseeded = Self.walk(order)
+        #expect(unseeded.violations > 0, "seeding from the first frame would promise past 100...103")
+    }
+
+    @Test("Millisecond-rounded 23.976 timestamps stay contiguous")
+    func roundedTimestamps() {
+        let rate = 24000.0 / 1001
+        var floor = PresentationFloor(interval: 1 / rate)
+        var shown = 0
+        for i in Self.decodeOrder(gop: 8, frames: 240) {
+            let ms = (Double(i) * 1001 / 24000 * 1000).rounded()
+            let step = floor.record(ms / 1000, clockSeconds: nil)
+            #expect(!step.belowFloor)
+            shown += step.contiguous.count
+        }
+        #expect(shown == 240)
+        #expect(floor.ahead.isEmpty)
+    }
+
+    @Test("A frame that never comes is given up once the clock passes it")
+    func clockPassesAHole() {
+        // Frame 3 is lost. Without the clock the floor would wait below it forever.
+        let order = [0, 1, 2, 4, 5, 6, 7, 8]
+        let stuck = Self.walk(order)
+        #expect(abs(stuck.floor.floor - 2.5 * Self.interval) < 1e-9)
+        let moving = Self.walk(order, clock: { k in k >= 5 ? 3.5 * Self.interval : nil })
+        #expect(abs(moving.floor.floor - 8.5 * Self.interval) < 1e-9)
+        #expect(moving.violations == 0)
+    }
+
+    @Test("A frame below the promised floor is flagged and does not move it")
+    func belowFloorIsFlagged() {
+        var floor = PresentationFloor(interval: Self.interval)
+        for i in 0..<5 { _ = floor.record(Double(i) * Self.interval, clockSeconds: nil) }
+        let before = floor.floor
+        let late = floor.record(1 * Self.interval, clockSeconds: nil)
+        #expect(late.belowFloor)
+        #expect(late.raisedFloor == nil)
+        #expect(floor.floor == before)
+    }
+
+    @Test("A reset forgets the promise")
+    func resetForgets() {
+        var floor = PresentationFloor(interval: Self.interval)
+        for i in 0..<10 { _ = floor.record(Double(i) * Self.interval, clockSeconds: nil) }
+        floor.reset()
+        #expect(floor.floor == -.infinity)
+        #expect(floor.frontier == nil)
+        #expect(!floor.record(0, clockSeconds: nil).belowFloor, "a seek back starts over")
+    }
+}
+
+/// The renderer side: on the arrival-order path frames reach the layer the moment they arrive, in the
+/// order they arrived, and nothing is held, dropped as out of order or counted below the floor.
+@Suite("Arrival-order handover in the software renderer")
+struct ArrivalOrderHandoverTests {
+
+    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() -> CVPixelBuffer {
+        var pb: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, 16, 16, kCVPixelFormatType_32BGRA,
+                            [kCVPixelBufferIOSurfacePropertiesKey: [:]] as CFDictionary, &pb)
+        return pb!
+    }
+
+    private static func time(_ index: Int) -> CMTime { CMTime(value: Int64(index) * 1000, timescale: 24000) }
+
+    @Test("Decode-order frames are handed over immediately, in arrival order")
+    @MainActor
+    func handsOverImmediately() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: true))
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        #expect(renderer.handsOverInArrivalOrder)
+        let handed = Handed()
+        renderer.setFrameEnqueuedObserver { handed.append($0) }
+        let pixels = Self.makePixelBuffer()
+        let order = PresentationFloorTests.decodeOrder(gop: 8, frames: 48)
+        for (k, i) in order.enumerated() {
+            renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i))
+            #expect(handed.seconds.count == k + 1, "frame \(k) is not held")
+        }
+        #expect(renderer.heldFrameCount == 0)
+        #expect(handed.seconds == order.map { Self.time($0).seconds })
+        #expect(renderer.outOfOrderFramesDropped == 0)
+        #expect(renderer.framesBelowFloor == 0)
+        #expect(renderer.enqueueCount == order.count)
+    }
+
+    @Test("Spacing is measured in display order, so decode order does not read as a reordering fault")
+    @MainActor
+    func spacingInDisplayOrder() {
+        let renderer = SampleBufferRenderer()
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        let pixels = Self.makePixelBuffer()
+        for i in PresentationFloorTests.decodeOrder(gop: 8, frames: 48) {
+            renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i))
+        }
+        let cadence = renderer.takeCadence()
+        let interval = 1 / 24.0
+        #expect(abs((cadence.minDeltaSeconds ?? 0) - interval) < 1e-6)
+        #expect(abs((cadence.maxDeltaSeconds ?? 0) - interval) < 1e-6)
+    }
+
+    @Test("A seek seeds the floor at the threshold, and frames below it are still skipped")
+    @MainActor
+    func seekSeedsTheFloor() {
+        let renderer = SampleBufferRenderer()
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        let pixels = Self.makePixelBuffer()
+        for i in 0..<20 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        renderer.flush(removingDisplayedImage: false)
+        renderer.setSkipThreshold(Self.time(100))
+        let handed = Handed()
+        renderer.setFrameEnqueuedObserver { handed.append($0) }
+        for i in PresentationFloorTests.decodeOrder(gop: 8, frames: 48, startingAt: 96) {
+            renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i))
+        }
+        #expect(handed.seconds.allSatisfy { $0 >= Self.time(100).seconds })
+        #expect(handed.seconds.count == 44)
+        #expect(renderer.framesBelowFloor == 0)
+    }
+
+    @Test("Without a frame rate the renderer keeps its reorder buffer")
+    @MainActor
+    func offWithoutARate() {
+        let renderer = SampleBufferRenderer()
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        renderer.setArrivalOrderHandover(frameRate: nil)
+        #expect(!renderer.handsOverInArrivalOrder)
+        renderer.setArrivalOrderHandover(frameRate: .nan)
+        #expect(!renderer.handsOverInArrivalOrder)
+        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: true))
+        let pixels = Self.makePixelBuffer()
+        for i in [0, 4, 2, 1, 3] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        #expect(renderer.heldFrameCount == 4, "the reorder buffer holds as before")
+    }
+}

From e13aa27534f45724a32551d434b049df5ef7fcd1 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Tue, 13 Oct 2026 20:51:06 +0100
Subject: [PATCH 027/132] fix(dovi): preroll the FEL route before the clock
 starts, and start it ahead of now

The software host started the master clock the moment the first packet arrived. On the FEL route
the first composed frames were then late on arrival, and an Apple TV 4K (A12) dropped 3 to 5 frames
at every start and every seek.

Two changes, both only on the FEL route:

- Preroll. seekClock anchors at rate 0 until the renderer holds composed frames up to 0.167 s past
  the clock (SampleBufferRenderer.felPrerollSatisfied, counted on the arrival-order frontier), then
  starts at the requested rate and the same source time; after 2 s it starts anyway. A rate set
  meanwhile becomes the start rate; a pause, another seek or stop cancels the start. The same idea
  as AVPlayer.preroll(atRate:).
- Start lead. The prerolled start is scheduled 250 ms ahead of now (setRate(_:time:atHostTime:)).
  On tvOS the synchronizer lives in another process and the display path learns about a rate change
  about one audio output latency late (138 ms measured on HDMI); frames due inside that window
  dropped even with the queue full.

Apple TV 4K (A12), 4K FEL 90 s segment with TrueHD, 150 s soaks with 5 seeks each: 0 dropped
frames in 8 of 8 runs (a 500 ms lead was no better), measured together with the in-memory packet
cache (separate PR) that removes the mid-play read stalls. Other routes answer nil and start as before.
---
 Sources/AetherEngine/Audio/AudioOutput.swift  | 102 ++++++++++++-
 .../Native/SoftwarePlaybackHost.swift         |   8 +
 .../Renderer/SampleBufferRenderer.swift       |  19 +++
 .../AetherEngineTests/VideoPrerollTests.swift | 137 ++++++++++++++++++
 4 files changed, 265 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AetherEngineTests/VideoPrerollTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index 2c9f279ac..46c352e5e 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -1,6 +1,7 @@
 import Foundation
 import AVFoundation
 import CoreMedia
+import QuartzCore
 
 /// Audio output via AVSampleBufferAudioRenderer + AVSampleBufferRenderSynchronizer. The synchronizer is the
 /// **master clock** for the whole player: video frames check synchronizer.currentTime() to decide presentation.
@@ -168,6 +169,10 @@ final class AudioOutput: @unchecked Sendable {
 
     /// Set playback speed (0.5-2.0). Hosts own rate state (lastRate/pausedByHost); this object is stateless about it.
     func setRate(_ rate: Float) {
+        // A host resumes right after it arms the clock; while a preroll waits, that rate is the one
+        // the preroll starts at, not a start of its own.
+        if rate > 0, updatePrerollRate(rate) { return }
+        cancelPreroll()
         let at = synchronizer.currentTime()
         EngineLog.emit("[AudioOutput] setRate \(rate) at t=\(String(format: "%.3f", timeline.sourceSeconds(forRenderer: at.seconds)))", category: .swPlayback)
         synchronizer.setRate(rate, time: at)
@@ -175,6 +180,7 @@ final class AudioOutput: @unchecked Sendable {
 
     /// Pause audio (and the master clock). Hosts resume via setRate (pausedByHost pattern); deliberately no resume() here.
     func pause() {
+        cancelPreroll()
         let at = synchronizer.currentTime()
         EngineLog.emit("[AudioOutput] pause at t=\(String(format: "%.3f", timeline.sourceSeconds(forRenderer: at.seconds)))", category: .swPlayback)
         synchronizer.setRate(0.0, time: at)
@@ -184,6 +190,7 @@ final class AudioOutput: @unchecked Sendable {
     /// 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) {
+        cancelPreroll()
         let now = timeline.sourceTime(forRenderer: synchronizer.currentTime())
         let seconds = SoftwareEndOfMediaClock.parkSeconds(clockSeconds: CMTimeGetSeconds(now), notAfter: latest)
         let at = seconds.map { CMTime(seconds: $0, preferredTimescale: 90000) } ?? now
@@ -358,6 +365,8 @@ final class AudioOutput: @unchecked Sendable {
         lock.lock()
         defer { lock.unlock() }
         _epoch &+= 1
+        prerollGeneration &+= 1
+        prerollRate = nil
         synchronizer.setRate(0.0, time: .zero)
         renderer.flush()
     }
@@ -366,9 +375,100 @@ final class AudioOutput: @unchecked Sendable {
     /// demux loops call it once on the first decoded packet, seek paths call it directly. Avoids the
     /// falling-through-time races that pause -> flush -> setRate would expose.
     func seekClock(to time: CMTime, rate: Float) {
+        // Asked before taking `lock`: the gate reads the video renderer's state under its own lock.
+        let preroll = rate > 0 ? videoPrerollSatisfied?(time.seconds) : nil
         lock.lock()
         defer { lock.unlock() }
         EngineLog.emit("[AudioOutput] seekClock to=\(String(format: "%.3f", time.seconds)) rate=\(rate)", category: .swPlayback)
-        synchronizer.setRate(rate, time: timeline.rendererTime(forSource: time))
+        prerollGeneration &+= 1
+        prerollRate = nil
+        guard let preroll else {
+            synchronizer.setRate(rate, time: timeline.rendererTime(forSource: time))
+            return
+        }
+        if preroll {
+            startAfterPreroll(rate: rate, time: time)
+            return
+        }
+        synchronizer.setRate(0, time: timeline.rendererTime(forSource: time))
+        let gen = prerollGeneration
+        prerollRate = rate
+        let started = CACurrentMediaTime()
+        prerollQueue.async { [weak self] in self?.pollPreroll(gen: gen, time: time, started: started) }
+    }
+
+    // MARK: - Video preroll
+
+    /// Whether the video renderer holds enough to start the clock at a source time: nil when this
+    /// session does not preroll, so the clock starts at once as it always has. Set by the host for the
+    /// Profile 7 FEL route (`SampleBufferRenderer.felPrerollSatisfied(clock:)`).
+    ///
+    /// The video queue is filled with the timebase stopped and the clock starts only once that is done,
+    /// the same idea as `AVPlayer.preroll(atRate:)`. Starting at full rate the moment
+    /// the first packet arrives made the first composed FEL frames late on arrival: five dropped
+    /// frames at every start and every seek on an Apple TV 4K (A12). With the preroll, `seekClock`
+    /// anchors at rate 0, and the clock starts at the requested rate and the same source time once
+    /// the renderer is ready, or after `prerollTimeout`. A pause, a rate change or another seek in the
+    /// meantime cancels the start; `stop()` too.
+    var videoPrerollSatisfied: (@Sendable (Double) -> Bool?)? {
+        get { lock.lock(); defer { lock.unlock() }; return _videoPrerollSatisfied }
+        set { lock.lock(); _videoPrerollSatisfied = newValue; lock.unlock() }
+    }
+    private var _videoPrerollSatisfied: (@Sendable (Double) -> Bool?)?  // guarded by lock
+
+    /// How long a preroll may hold the clock. A decoder that never delivers must not freeze playback.
+    static let prerollTimeout: Double = 2
+
+    /// How far ahead of now a prerolled start is scheduled. On tvOS the synchronizer lives in another
+    /// process, and the display path learns of a rate change about as late as the audio route's output
+    /// latency (138 ms measured on HDMI): a clock started "now" has already run that far when the first
+    /// frames are judged, and the ones due inside that window drop (3 to 5 a start on the A12 even with
+    /// the queue full). Scheduling the start 250 ms out took starts and seeks to 0 drops in every run
+    /// (8 of 8, 150 s soaks with 5 seeks; 500 ms was no better).
+    static let prerollStartLead: Double = 0.25
+
+    private var prerollGeneration = 0  // guarded by lock
+    private var prerollRate: Float?  // guarded by lock; non-nil while a preroll waits: the rate it starts at
+    private let prerollQueue = DispatchQueue(label: "aether.audio.preroll", qos: .userInteractive)
+
+    private func pollPreroll(gen: Int, time: CMTime, started: CFTimeInterval) {
+        let ready = videoPrerollSatisfied?(time.seconds) != false
+        let waited = CACurrentMediaTime() - started
+        if !ready, waited < Self.prerollTimeout {
+            prerollQueue.asyncAfter(deadline: .now() + .milliseconds(2)) { [weak self] in
+                self?.pollPreroll(gen: gen, time: time, started: started)
+            }
+            return
+        }
+        lock.lock()
+        defer { lock.unlock() }
+        guard prerollGeneration == gen, let rate = prerollRate else { return }
+        prerollRate = nil
+        EngineLog.emit("[AudioOutput] preroll \(ready ? "ready" : "timed out") after "
+                       + "\(String(format: "%.0f", waited * 1000)) ms; starting at t=\(String(format: "%.3f", time.seconds)) rate=\(rate)",
+                       category: .swPlayback)
+        startAfterPreroll(rate: rate, time: time)
+    }
+
+    /// Starts the clock `prerollStartLead` from now. Called with `lock` held.
+    private func startAfterPreroll(rate: Float, time: CMTime) {
+        let hostNow = CMClockGetTime(CMClockGetHostTimeClock())
+        let host = CMTimeAdd(hostNow, CMTime(seconds: Self.prerollStartLead, preferredTimescale: 1_000_000_000))
+        synchronizer.setRate(rate, time: timeline.rendererTime(forSource: time), atHostTime: host)
+    }
+
+    private func cancelPreroll() {
+        lock.lock()
+        prerollGeneration &+= 1
+        prerollRate = nil
+        lock.unlock()
+    }
+
+    private func updatePrerollRate(_ rate: Float) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        guard prerollRate != nil else { return false }
+        prerollRate = rate
+        return true
     }
 }
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 3027d397e..868d4de02 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1177,6 +1177,14 @@ final class SoftwarePlaybackHost {
         renderer.setTimeline(audioOutput.timeline)   // AE#395
         self.audioOutput?.volume = volume
         self.audioOutput?.setPresentationOffset(seconds: audioDelaySeconds)   // AE#464
+        // The FEL path holds the clock until composed frames are queued, then starts it a little ahead
+        // (`AudioOutput.videoPrerollSatisfied`); every other route answers nil and starts at once, and
+        // so does a session playing audio only in the background, which feeds the renderer nothing.
+        let prerollRenderer = renderer
+        self.audioOutput?.videoPrerollSatisfied = { [weak self] clock in
+            guard self?.backgroundAudioOnly != true else { return nil }
+            return prerollRenderer.felPrerollSatisfied(clock: clock)
+        }
         // 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() {
diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 7573205d1..2ab171585 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -166,6 +166,25 @@ final class SampleBufferRenderer: @unchecked Sendable {
         reorderLock.unlock()
     }
 
+    /// How much composed video the FEL path hands the layer before the clock starts, in seconds
+    /// (`felPrerollSatisfied(clock:)`): four frames at 24 fps, which covers a decode-order burst of a
+    /// hierarchical GOP. Measured on the Apple TV 4K (A12) with 4K FEL, the preroll completes after
+    /// 90 to 100 ms at a start and 0.3 to 0.9 s after a seek.
+    static let felPrerollSeconds = 0.167
+
+    /// The FEL path's preroll gate for `AudioOutput.videoPrerollSatisfied`: true once frames up to
+    /// `felPrerollSeconds` past `clock` (source seconds) are in the layer, nil off the FEL path. On
+    /// the arrival-order path only the frontier counts, the newest timestamp with every earlier slot
+    /// handed over, so a frame that came early past a gap does not open the gate.
+    func felPrerollSatisfied(clock: Double) -> Bool? {
+        reorderLock.lock()
+        defer { reorderLock.unlock() }
+        guard let rate = felFrameRate, clock.isFinite else { return nil }
+        let handed = arrivalFloor != nil ? arrivalFloor?.frontier : _lastReleasedPtsSeconds
+        guard let handed else { return false }
+        return handed + 1 / rate - clock >= Self.felPrerollSeconds
+    }
+
     /// Combined queue-readiness and look-ahead gate, called BEFORE decode so excess frames stay compressed.
     func mayEnqueueVideoFrame(ptsSeconds: Double, clockSeconds: Double, clockArmed: Bool) -> Bool {
         reorderLock.lock()
diff --git a/Tests/AetherEngineTests/VideoPrerollTests.swift b/Tests/AetherEngineTests/VideoPrerollTests.swift
new file mode 100644
index 000000000..0f0fda319
--- /dev/null
+++ b/Tests/AetherEngineTests/VideoPrerollTests.swift
@@ -0,0 +1,137 @@
+import Foundation
+import AVFoundation
+import CoreMedia
+import CoreVideo
+import os
+import Testing
+@testable import AetherEngine
+
+/// The FEL path's start: the clock waits at rate 0 until composed frames are in the layer, then
+/// starts a fixed lead from now (`AudioOutput.videoPrerollSatisfied`, `prerollStartLead`,
+/// `SampleBufferRenderer.felPrerollSatisfied(clock:)`). On an Apple TV 4K a clock started the moment
+/// the first packet arrived dropped 3 to 5 frames at every start and seek; with both, none.
+@Suite("Video preroll before the clock starts")
+struct VideoPrerollTests {
+
+    private static func makePixelBuffer() -> CVPixelBuffer {
+        var pb: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, 16, 16, kCVPixelFormatType_32BGRA,
+                            [kCVPixelBufferIOSurfacePropertiesKey: [:]] as CFDictionary, &pb)
+        return pb!
+    }
+
+    private static func time(_ index: Int) -> CMTime { CMTime(value: Int64(index) * 1000, timescale: 24000) }
+
+    // MARK: - Renderer gate
+
+    @Test("Off the FEL path the renderer has no opinion, so the clock starts at once")
+    @MainActor
+    func noGateOffTheFELPath() {
+        let renderer = SampleBufferRenderer()
+        #expect(renderer.felPrerollSatisfied(clock: 0) == nil)
+    }
+
+    @Test("The gate opens once the contiguous frames reach the preroll past the clock")
+    @MainActor
+    func gateCountsContiguousFrames() {
+        let renderer = SampleBufferRenderer()
+        renderer.setFELLookahead(enabled: true, frameRate: 24)
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        let pixels = Self.makePixelBuffer()
+        #expect(renderer.felPrerollSatisfied(clock: 0) == false, "nothing handed over yet")
+        // A frame past a gap does not count: 0, 1, 2 and then 6 leave the frontier at frame 2.
+        for i in [0, 1, 2, 6] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        #expect(renderer.felPrerollSatisfied(clock: 0) == false)
+        // 0 to 3 is four frames, 0.1667 s: just short of the preroll.
+        renderer.enqueue(pixelBuffer: pixels, pts: Self.time(3))
+        #expect(renderer.felPrerollSatisfied(clock: 0) == false)
+        renderer.enqueue(pixelBuffer: pixels, pts: Self.time(4))
+        #expect(renderer.felPrerollSatisfied(clock: 0) == true)
+        // The same frames are not enough for a clock further on.
+        #expect(renderer.felPrerollSatisfied(clock: Self.time(4).seconds) == false)
+    }
+
+    @Test("After a seek the gate counts from the seek target, not from the frames before it")
+    @MainActor
+    func gateRestartsAtTheSeekTarget() {
+        let renderer = SampleBufferRenderer()
+        renderer.setFELLookahead(enabled: true, frameRate: 24)
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        let pixels = Self.makePixelBuffer()
+        for i in 0..<20 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        renderer.flush(removingDisplayedImage: false)
+        renderer.setSkipThreshold(Self.time(100))
+        let target = Self.time(100).seconds
+        #expect(renderer.felPrerollSatisfied(clock: target) == false)
+        for i in 100..<105 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        #expect(renderer.felPrerollSatisfied(clock: target) == true)
+    }
+
+    // MARK: - Clock
+
+    /// A gate the test opens by hand.
+    private final class Gate: Sendable {
+        private let open = OSAllocatedUnfairLock(initialState: false)
+        func set(_ value: Bool) { open.withLock { $0 = value } }
+        var isOpen: Bool { open.withLock { $0 } }
+    }
+
+    @Test("Without a gate seekClock starts the clock at once", .timeLimit(.minutes(1)))
+    func startsAtOnceWithoutAGate() {
+        let output = AudioOutput()
+        output.seekClock(to: CMTime(seconds: 5, preferredTimescale: 90000), rate: 1)
+        #expect(output.synchronizer.rate == 1)
+    }
+
+    @Test("A closed gate holds the clock at rate 0 and the start follows when it opens",
+          .timeLimit(.minutes(1)))
+    func holdsUntilTheGateOpens() async throws {
+        let output = AudioOutput()
+        let gate = Gate()
+        output.videoPrerollSatisfied = { _ in gate.isOpen }
+        output.seekClock(to: CMTime(seconds: 5, preferredTimescale: 90000), rate: 1)
+        #expect(output.synchronizer.rate == 0)
+        #expect(abs(output.synchronizer.currentTime().seconds - 5) < 0.001)
+        let opened = CMClockGetTime(CMClockGetHostTimeClock()).seconds
+        gate.set(true)
+        try await waitFor { output.synchronizer.rate == 1 }
+        // The start was scheduled `prerollStartLead` after the gate opened, so however late this
+        // runs, the clock has not run longer than the time since then minus the lead.
+        let now = CMClockGetTime(CMClockGetHostTimeClock()).seconds
+        let ran = max(0, now - opened - AudioOutput.prerollStartLead)
+        #expect(output.synchronizer.currentTime().seconds <= 5 + ran + 0.02)
+    }
+
+    @Test("A rate set while the preroll waits is the rate it starts at", .timeLimit(.minutes(1)))
+    func setRateDuringPrerollIsTheStartRate() async throws {
+        let output = AudioOutput()
+        let gate = Gate()
+        output.videoPrerollSatisfied = { _ in gate.isOpen }
+        output.seekClock(to: CMTime(seconds: 5, preferredTimescale: 90000), rate: 1)
+        output.setRate(1.5)
+        #expect(output.synchronizer.rate == 0, "the rate does not start the clock early")
+        gate.set(true)
+        try await waitFor { output.synchronizer.rate == 1.5 }
+    }
+
+    @Test("A pause cancels the pending start", .timeLimit(.minutes(1)))
+    func pauseCancelsThePreroll() async throws {
+        let output = AudioOutput()
+        let gate = Gate()
+        output.videoPrerollSatisfied = { _ in gate.isOpen }
+        output.seekClock(to: CMTime(seconds: 5, preferredTimescale: 90000), rate: 1)
+        output.pause()
+        gate.set(true)
+        let started = try await waitFor(upTo: .milliseconds(300)) { output.synchronizer.rate != 0 }
+        #expect(!started)
+    }
+
+    @Test("A gate that never opens starts the clock after the timeout", .timeLimit(.minutes(1)))
+    func timesOut() async throws {
+        let output = AudioOutput()
+        output.videoPrerollSatisfied = { _ in false }
+        output.seekClock(to: CMTime(seconds: 5, preferredTimescale: 90000), rate: 1)
+        #expect(output.synchronizer.rate == 0)
+        try await waitFor { output.synchronizer.rate == 1 }
+    }
+}

From 4e4cc98301a7d755712b19b0ce322887cc901f4b Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 16:07:02 +0100
Subject: [PATCH 028/132] chore(dovi): composer logs: periodic GPU timing at
 verbose

DoviFelComposer.swift, recordGPUTime: the "[DoviFelComposer] gpu X ms/frame over N frames"
line repeats every 120 composed frames (about every 5 s at 24 fps) for the whole session. Moved
from the default level to .verbose, so it reaches OSLog's debug level only and no longer the host
handler or a default log stream.

Kept at the default level, unchanged: the shader compilation error (once per process), the
command buffer errors (real failures), the logOnce parse-time rejections (bounded to 64 distinct
lines), and the one-shot non-zero linear_deadzone_threshold notice.
---
 Sources/AetherEngine/Video/Metal/DoviFelComposer.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
index 18a5eae25..26cc87635 100644
--- a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
@@ -938,7 +938,7 @@ final class DoviFelComposer: @unchecked Sendable {
         gpuTimeLock.unlock()
         if let closed {
             EngineLog.emit(String(format: "[DoviFelComposer] gpu %.1fms/frame over %d frames",
-                                  closed, Self.gpuTimeWindow), category: .swPlayback)
+                                  closed, Self.gpuTimeWindow), category: .swPlayback, level: .verbose)
         }
     }
 

From 5fb36366dfe2eeba579f36d687fa92fa1917aaac Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 16:58:16 +0100
Subject: [PATCH 029/132] chore(dovi): composer logs a repeated command buffer
 error once

A GPU that keeps failing would otherwise log the same line for every frame.
The decoder's per-second summary still counts each failed compose.
---
 Sources/AetherEngine/Video/Metal/DoviFelComposer.swift | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
index 26cc87635..e7d40c05d 100644
--- a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
@@ -84,8 +84,9 @@ final class DoviFelComposer: @unchecked Sendable {
     private static let onceLock = NSLock()
     private static let maxOnceLines = 64
 
-    /// Logs a parse-time rejection once per distinct line. `parseRpuParameters` runs for every RPU, so a stream
-    /// that trips one of these would otherwise repeat it on every frame.
+    /// Logs a line once per distinct text. Parse-time rejections and command buffer errors can recur on every
+    /// frame (a stream that trips a check, a GPU that keeps failing), so each would otherwise flood the log;
+    /// the decoder's per-second summary still counts every failed compose.
     private static func logOnce(_ line: String, category: EngineLog.Category = .swPlayback) {
         onceLock.lock()
         let fresh = onceLines.count < maxOnceLines && onceLines.insert(line).inserted
@@ -385,7 +386,7 @@ final class DoviFelComposer: @unchecked Sendable {
         work.commandBuffer.waitUntilCompleted()
         if let failure = Self.commandBufferFailure(work.commandBuffer, forced: forcedCommandBufferFailure.withLock { $0 }) {
             // The GPU did not finish writing the destination: it is not a frame, so no frame is returned.
-            EngineLog.emit("[DoviFelComposer] Command buffer error: \(failure)", category: .swPlayback)
+            Self.logOnce("[DoviFelComposer] Command buffer error: \(failure)")
             return nil
         }
         _ = work.keepAlive
@@ -587,7 +588,7 @@ final class DoviFelComposer: @unchecked Sendable {
             let composer = self
             deliveryQueue.async {
                 if let errorDescription {
-                    EngineLog.emit("[DoviFelComposer] Command buffer error: \(errorDescription)", category: .swPlayback)
+                    Self.logOnce("[DoviFelComposer] Command buffer error: \(errorDescription)")
                 }
                 composer?.recordGPUTime(ms: gpuMs)
                 os_signpost(.end, log: Self.signpostLog, name: "Compose", signpostID: signpostID)

From cc2f7c292bfc12abc34fe8042436e6e53016ab2a Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 16:11:03 +0100
Subject: [PATCH 030/132] chore(dovi): dual-layer decoder logs: one prefix,
 readable phrases, 1 Hz summary at verbose

DualLayerVideoDecoder.swift (and its tests):

- Prefix: the per-frame and summary lines said "[DualLayer]" while the lifecycle lines said
  "[DualLayerVideoDecoder]". All use the type name now, as "[HardwareVideoDecoder]" does.
- Shouting tags to phrases, all still .verbose: "QUEUE BL" -> "queued base layer", "QUEUE EL" ->
  "queued enhancement layer", "DROP stale EL" -> "dropped stale enhancement layer", "PRUNED EL"
  -> "pruned enhancement layer", "BYPASS no-EL" -> "bypass, no enhancement layer arrived",
  "Bypass: ..." -> "bypass, <reason>: ...", "COMPOSE FAILED (BL arrived)" -> "compose failed
  (base layer arrived last)".
- The 1 Hz "summary:" line goes from the default level to .verbose, except for a second whose
  counters include a compose failure, which stays at the default level so a failure is visible
  without enabling debug output. Healthy playback now writes nothing per second to the host
  handler.
- "S1:" in two comments next to the missing-RPU bypass is dropped; it named nothing a maintainer
  can look up.
- Tests: the summary tests read the line and its level through a DEBUG-only
  summarySinkForTesting, because .verbose never reaches EngineLog.handler; the per-frame-at-info
  test checks the new texts; a test pins that a summary with a compose failure goes out at the
  default level.

Kept at the default level, unchanged: no composer, FEL/MEL detected, primary and secondary
decoder opened, the two decoder open failures, and the one-time "reordered against the base
layer" notice. Each fires once per open or per detection.

Not changed: the verbose lines still build their text eagerly (String(format:) of the pts, queue
counts) in the pairing paths, under the decoder lock, because EngineLog.emit takes a String and
not an autoclosure.
---
 .../Decoder/DualLayerVideoDecoder.swift       |  48 +++++---
 .../DualLayerVideoDecoderTests.swift          | 114 +++++++++++++-----
 2 files changed, 114 insertions(+), 48 deletions(-)

diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
index 1d9f7e94d..a6cec3f1d 100644
--- a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -893,7 +893,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         ) { [weak self] composed in
             self?.recordComposeResult(success: composed != nil)
             if composed == nil {
-                EngineLog.emit("[DualLayer] COMPOSE FAILED (\(arrived)): pts=\(String(format: "%.3f", pts.seconds))", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] compose failed (\(arrived)): pts=\(String(format: "%.3f", pts.seconds))", category: .swPlayback, level: .verbose)
             }
             let buffer = SendableBuffer(value: composed ?? fallback.value)
             delivery.fulfil(ticket: ticket, epoch: epoch, DeliveredFrame(buffer: buffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL))
@@ -933,7 +933,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             guard !draining else { return (.queued, []) }
             guard isFEL, !isMEL, enhancementDecoder != nil, composer != nil else {
                 // Not a FEL stream or secondary decoder not engaged (e.g. MEL or P8.1 fallback): emit Base Layer directly
-                EngineLog.emit("[DualLayer] Bypass: isFEL=\(isFEL), isMEL=\(isMEL), enhDecoder=\(enhancementDecoder != nil)", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] bypass, single layer: isFEL=\(isFEL), isMEL=\(isMEL), enhDecoder=\(enhancementDecoder != nil)", category: .swPlayback, level: .verbose)
                 if isFEL && !isMEL && enhancementDecoder == nil {
                     summaryBypassNoEL += 1
                 }
@@ -953,7 +953,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             // A frame without a timestamp has nothing to pair on: it goes out as its base layer now, under
             // the ticket it already holds, rather than waiting for a partner that cannot match it.
             guard key != Int64.min else {
-                EngineLog.emit("[DualLayer] Bypass: base-layer frame without a timestamp", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] bypass, no timestamp: base-layer frame has nothing to pair on", category: .swPlayback, level: .verbose)
                 return (.bypass(BypassRequest(ticket: ticket, epoch: epoch, buffer: baseBuffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, reason: "no-pts")), collectDueBypasses())
             }
             let mKey: Int64?
@@ -967,8 +967,8 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             if let mKey, let elBuffer = elFrameQueue.removeValue(forKey: mKey) {
                 // Matching EL frame is already ready: compose on the Metal GPU outside the lock
                 guard let params = takeParams(key: key) else {
-                    // S1: Missing RPU metadata: do NOT synthesize identity NLQ. Emit base layer directly.
-                    EngineLog.emit("[DualLayer] Bypass: missing RPU for key=\(key)", category: .swPlayback, level: .verbose)
+                    // Missing RPU metadata: do NOT synthesize identity NLQ. Emit base layer directly.
+                    EngineLog.emit("[DualLayerVideoDecoder] bypass, missing RPU: key=\(key)", category: .swPlayback, level: .verbose)
                     summaryBypassNoRPU += 1
                     noteSettledBaseLayer(key: key)
                     primary = .bypass(BypassRequest(ticket: ticket, epoch: epoch, buffer: baseBuffer, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, reason: "missing-rpu"))
@@ -976,10 +976,10 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
                 }
                 frameIndex &+= 1
                 noteSettledBaseLayer(key: key)
-                primary = .compose(ComposeRequest(ticket: ticket, epoch: epoch, base: baseBuffer, enhancement: elBuffer, params: params, frameIndex: frameIndex, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, arrived: "BL arrived"))
+                primary = .compose(ComposeRequest(ticket: ticket, epoch: epoch, base: baseBuffer, enhancement: elBuffer, params: params, frameIndex: frameIndex, pts: pts, hdr10Data: hdr10Data, dmNAL: dmNAL, arrived: "base layer arrived last"))
             } else {
                 // EL frame has not arrived yet: queue Base Layer frame under its ticket
-                EngineLog.emit("[DualLayer] QUEUE BL: pts=\(String(format: "%.3f", pts.seconds)) key=\(key), elCount=\(elFrameQueue.count)", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] queued base layer: pts=\(String(format: "%.3f", pts.seconds)) key=\(key), elCount=\(elFrameQueue.count)", category: .swPlayback, level: .verbose)
                 var displaced: BypassRequest?
                 if let old = blFrameQueue[key] {
                     // Same canonical key twice: the old entry's ticket would stall
@@ -1034,7 +1034,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             // This enhancement layer's base layer already went out
             // (composed or bypassed), so it can never pair; drop it.
             if settledBlKeys.contains(where: { FrameSideDataRing.isWithinJitter($0, key) }) {
-                EngineLog.emit("[DualLayer] DROP stale EL: key=\(key), already settled", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] dropped stale enhancement layer: key=\(key), already settled", category: .swPlayback, level: .verbose)
                 summaryDropStaleEL += 1
                 return .queued
             }
@@ -1051,18 +1051,18 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
                 let epoch = _feedEpoch
                 let dmNAL = waiting.side.dmNAL
                 guard let params = takeParams(key: mKey) else {
-                    // S1: Missing RPU metadata: do NOT synthesize identity NLQ. Emit base layer directly.
-                    EngineLog.emit("[DualLayer] Bypass: missing RPU for key=\(mKey)", category: .swPlayback, level: .verbose)
+                    // Missing RPU metadata: do NOT synthesize identity NLQ. Emit base layer directly.
+                    EngineLog.emit("[DualLayerVideoDecoder] bypass, missing RPU: key=\(mKey)", category: .swPlayback, level: .verbose)
                     summaryBypassNoRPU += 1
                     noteSettledBaseLayer(key: mKey)
                     return .bypass(BypassRequest(ticket: waiting.ticket, epoch: epoch, buffer: waiting.buffer, pts: waiting.pts, hdr10Data: waiting.side.hdr10Data, dmNAL: waiting.side.dmNAL, reason: "missing-rpu"))
                 }
                 frameIndex &+= 1
                 noteSettledBaseLayer(key: mKey)
-                return .compose(ComposeRequest(ticket: waiting.ticket, epoch: epoch, base: waiting.buffer, enhancement: elBuffer, params: params, frameIndex: frameIndex, pts: waiting.pts, hdr10Data: waiting.side.hdr10Data, dmNAL: dmNAL, arrived: "EL arrived"))
+                return .compose(ComposeRequest(ticket: waiting.ticket, epoch: epoch, base: waiting.buffer, enhancement: elBuffer, params: params, frameIndex: frameIndex, pts: waiting.pts, hdr10Data: waiting.side.hdr10Data, dmNAL: dmNAL, arrived: "enhancement layer arrived last"))
             } else {
                 // Base Layer frame has not arrived yet: queue EL frame under its own larger cap
-                EngineLog.emit("[DualLayer] QUEUE EL: pts=\(String(format: "%.3f", pts.seconds)) key=\(key), blCount=\(blFrameQueue.count)", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] queued enhancement layer: pts=\(String(format: "%.3f", pts.seconds)) key=\(key), blCount=\(blFrameQueue.count)", category: .swPlayback, level: .verbose)
                 elFrameQueue[key] = elBuffer
                 let currentSkew = max(blFrameQueue.count, elFrameQueue.count)
                 if currentSkew > summaryMaxObservedSkew {
@@ -1071,7 +1071,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
                 if elFrameQueue.count > Self.maxEnhancementLayerQueueFrames {
                     let sortedKeys = elFrameQueue.keys.sorted()
                     for k in sortedKeys.prefix(elFrameQueue.count - Self.maxEnhancementLayerQueueFrames) {
-                        EngineLog.emit("[DualLayer] PRUNED EL: key=\(k)", category: .swPlayback, level: .verbose)
+                        EngineLog.emit("[DualLayerVideoDecoder] pruned enhancement layer: key=\(k)", category: .swPlayback, level: .verbose)
                         elFrameQueue.removeValue(forKey: k)
                         summaryPrunedEL += 1
                     }
@@ -1122,7 +1122,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
                 summaryBorrowedParams += 1
                 resolvedParams = last
                 resolvedNAL = dmNAL ?? lastGoodDMNAL
-                EngineLog.emit("[DualLayer] RPU missing for key=\(key); reusing the previous frame's parameters (\(borrowedParamsRun)/\(Self.maxBorrowedParamsRun))", category: .swPlayback, level: .verbose)
+                EngineLog.emit("[DualLayerVideoDecoder] RPU missing for key=\(key); reusing the previous frame's parameters (\(borrowedParamsRun)/\(Self.maxBorrowedParamsRun))", category: .swPlayback, level: .verbose)
             }
         }
         guard resolvedParams != nil || resolvedNAL != nil else { return }
@@ -1143,7 +1143,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         settledBlKeys.append(key)
         if settledBlKeys.count > Self.settledKeyMemory { settledBlKeys.removeFirst(settledBlKeys.count - Self.settledKeyMemory) }
         for k in elFrameQueue.keys where FrameSideDataRing.isWithinJitter(k, key) {
-            EngineLog.emit("[DualLayer] DROP stale EL: key=\(k), base \(key) settled", category: .swPlayback, level: .verbose)
+            EngineLog.emit("[DualLayerVideoDecoder] dropped stale enhancement layer: key=\(k), base \(key) settled", category: .swPlayback, level: .verbose)
             elFrameQueue.removeValue(forKey: k)
             summaryDropStaleEL += 1
         }
@@ -1159,7 +1159,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
                   blArrivalSeq &- entry.seq >= UInt64(Self.maxLayerSkewFrames) else { continue }
             blFrameQueue.removeValue(forKey: k)
             summaryBypassNoEL += 1
-            EngineLog.emit("[DualLayer] BYPASS no-EL: pts=\(String(format: "%.3f", entry.pts.seconds)) key=\(k)", category: .swPlayback, level: .verbose)
+            EngineLog.emit("[DualLayerVideoDecoder] bypass, no enhancement layer arrived: pts=\(String(format: "%.3f", entry.pts.seconds)) key=\(k)", category: .swPlayback, level: .verbose)
             noteSettledBaseLayer(key: k)
             due.append(BypassRequest(ticket: entry.ticket, epoch: _feedEpoch, buffer: entry.buffer, pts: entry.pts, hdr10Data: entry.side.hdr10Data, dmNAL: entry.side.dmNAL, reason: "no-el"))
         }
@@ -1171,11 +1171,14 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
 
     #if DEBUG
     var summaryTimestampProviderForTesting: (() -> TimeInterval)?
+    /// Sees every summary line with the level it went out at. `.verbose` lines never reach
+    /// `EngineLog.handler`, so a test cannot observe them there.
+    var summarySinkForTesting: ((String, EngineLog.Level) -> Void)?
     #endif
 
     // MARK: - Observability (dolby-vision-fel.md §5.11)
 
-    /// Seconds between `[DualLayer] summary` lines (dolby-vision-fel.md §5.11).
+    /// Seconds between `[DualLayerVideoDecoder] summary` lines (dolby-vision-fel.md §5.11).
     static let summaryIntervalSeconds: TimeInterval = 1.0
 
     func maybeEmitSummary() {
@@ -1225,8 +1228,15 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         let gpuMs = activeComposer?.meanGPUTimeMs
         let pendingPeak = orderedDelivery.takePeakPendingCount()
         let gpuStr = gpuMs.map { String(format: "%.1f", $0) } ?? "n/a"
-        let line = "[DualLayer] summary: composed=\(composed), composeFailures=\(composeFailures), bypassNoEL=\(noEL), bypassNoRPU=\(noRPU), staleELDropped=\(staleEL), prunedEL=\(prunedEL), borrowedParams=\(borrowedParams), maxSkew=\(skew), peakGpuSlots=\(slots), poolBuffers=\(poolBuffers), deliveryPendingPeak=\(pendingPeak), meanGpuMs=\(gpuStr)"
-        EngineLog.emit(line, category: .swPlayback)
+        let line = "[DualLayerVideoDecoder] summary: composed=\(composed), composeFailures=\(composeFailures), bypassNoEL=\(noEL), bypassNoRPU=\(noRPU), staleELDropped=\(staleEL), prunedEL=\(prunedEL), borrowedParams=\(borrowedParams), maxSkew=\(skew), peakGpuSlots=\(slots), poolBuffers=\(poolBuffers), deliveryPendingPeak=\(pendingPeak), meanGpuMs=\(gpuStr)"
+        // Once a second is a trace, not an event: it goes to OSLog's debug level only. An interval in
+        // which a composition failed is the exception, so the failure reaches the default level and the
+        // host handler.
+        let level: EngineLog.Level = composeFailures > 0 ? .info : .verbose
+        EngineLog.emit(line, category: .swPlayback, level: level)
+        #if DEBUG
+        summarySinkForTesting?(line, level)
+        #endif
         activeComposer?.flushTextureCache()
     }
 
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 8cb32b33e..2cce66221 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -1117,6 +1117,31 @@ struct DualLayerVideoDecoderTests {
 
     // MARK: - Delivery queue
 
+    /// Fake composer whose every composition fails (completes with nil), as a GPU error does.
+    private final class FailingFakeComposer: FelComposing, @unchecked Sendable {
+        func acquireSlot() {}
+        func releaseSlot() {}
+        func flush() {}
+        func composeAsync(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            completion(nil)
+        }
+        func composeAsyncWithAcquiredSlot(
+            baseBuffer: CVPixelBuffer,
+            enhancementBuffer: CVPixelBuffer,
+            params: DoviMetalParams,
+            frameIndex: UInt32,
+            completion: @escaping @Sendable (CVPixelBuffer?) -> Void
+        ) {
+            completion(nil)
+        }
+    }
+
     /// Fake composer whose Nth call (1-indexed) never calls its completion at
     /// all — the one failure mode a ticket cannot self-report, unlike a
     /// bypass or a "compose failed" fallback. Every other call completes
@@ -2211,7 +2236,7 @@ struct DualLayerVideoDecoderTests {
 
     // MARK: - Per-Frame Logging & 1 Hz Summary
 
-    @Test("per-frame logs (QUEUE, Bypass, DROP) are NOT emitted at default info level")
+    @Test("per-frame logs (queue, bypass, drop) are NOT emitted at default info level")
     func fel14PerFrameLogsNotEmittedAtDefaultInfoLevel() throws {
         let prevHandler = EngineLog.handler
         defer { EngineLog.handler = prevHandler }
@@ -2247,12 +2272,12 @@ struct DualLayerVideoDecoderTests {
         logLock.unlock()
 
         let forbiddenPrefixes = [
-            "[DualLayer] QUEUE BL",
-            "[DualLayer] QUEUE EL",
-            "[DualLayer] Bypass:",
-            "[DualLayer] DROP stale EL",
-            "[DualLayer] PRUNED EL",
-            "[DualLayer] BYPASS no-EL"
+            "[DualLayerVideoDecoder] queued base layer",
+            "[DualLayerVideoDecoder] queued enhancement layer",
+            "[DualLayerVideoDecoder] bypass,",
+            "[DualLayerVideoDecoder] dropped stale enhancement layer",
+            "[DualLayerVideoDecoder] pruned enhancement layer",
+            "[DualLayerVideoDecoder] compose failed"
         ]
         for prefix in forbiddenPrefixes {
             let found = captured.filter { $0.contains(prefix) }
@@ -2262,25 +2287,21 @@ struct DualLayerVideoDecoderTests {
 
     @Test("1 Hz summary aggregates and emits expected fields, then resets interval")
     func fel14OneHzSummaryAggregationAndFormat() throws {
-        let prevHandler = EngineLog.handler
-        defer { EngineLog.handler = prevHandler }
-
         var summaryLines: [String] = []
         let logLock = NSLock()
-        EngineLog.handler = { line in
-            if line.contains("[DualLayer] summary:") {
-                logLock.lock()
-                summaryLines.append(line)
-                logLock.unlock()
-            }
-        }
-
+        var summaryLevels: [EngineLog.Level] = []
         let composer = ImmediateFakeComposer()
         let decoder = DualLayerVideoDecoder(composer: composer)
         defer { decoder.close() }
 
         var currentTime: TimeInterval = 10.0
         decoder.summaryTimestampProviderForTesting = { currentTime }
+        decoder.summarySinkForTesting = { line, level in
+            logLock.lock()
+            summaryLines.append(line)
+            summaryLevels.append(level)
+            logLock.unlock()
+        }
 
         decoder.primeForTesting(enhancementLayer: true)
 
@@ -2311,7 +2332,7 @@ struct DualLayerVideoDecoderTests {
         let summary = summaryLines.first ?? ""
         logLock.unlock()
 
-        #expect(summary.contains("[DualLayer] summary:"))
+        #expect(summary.contains("[DualLayerVideoDecoder] summary:"))
         #expect(summary.contains("composed=1"))
         #expect(summary.contains("bypassNoEL=0"))
         #expect(summary.contains("bypassNoRPU=0"))
@@ -2320,6 +2341,10 @@ struct DualLayerVideoDecoderTests {
         #expect(summary.contains("poolBuffers="))
         #expect(summary.contains("deliveryPendingPeak="))
         #expect(summary.contains("meanGpuMs="))
+        // A healthy second is a trace: verbose reaches OSLog's debug level only, never the host handler.
+        logLock.lock()
+        #expect(summaryLevels == [.verbose])
+        logLock.unlock()
 
         // Next call immediately at 11.2 does not emit again until another second passes
         currentTime = 11.2
@@ -2338,26 +2363,57 @@ struct DualLayerVideoDecoderTests {
         #expect(summary2.contains("composed=0"))
     }
 
+    @Test("a 1 Hz summary that counts a compose failure goes out at the default level")
+    func summaryWithComposeFailureIsInfo() throws {
+        var levels: [EngineLog.Level] = []
+        var lines: [String] = []
+        let logLock = NSLock()
+        let decoder = DualLayerVideoDecoder(composer: FailingFakeComposer())
+        defer { decoder.close() }
+
+        var currentTime: TimeInterval = 30.0
+        decoder.summaryTimestampProviderForTesting = { currentTime }
+        decoder.summarySinkForTesting = { line, level in
+            logLock.lock()
+            lines.append(line)
+            levels.append(level)
+            logLock.unlock()
+        }
+        decoder.primeForTesting(enhancementLayer: true)
+
+        let baseBuf = try #require(Self.baseLayer())
+        let elBuf = try #require(Self.enhancementLayer())
+        decoder.seedRPUForTesting(pts: Self.pts(1), params: Self.params(), displayMetadataNAL: nil)
+        decoder.handleBaseLayerFrame(baseBuffer: baseBuf, pts: Self.pts(1), hdr10Data: nil)
+        decoder.handleEnhancementLayerFrame(elBuffer: elBuf, pts: Self.pts(1))
+
+        currentTime = 31.1
+        decoder.maybeEmitSummary()
+        currentTime = 32.2
+        decoder.maybeEmitSummary()
+
+        logLock.lock()
+        defer { logLock.unlock() }
+        #expect(lines.count == 2)
+        #expect(lines.first?.contains("composeFailures=1") == true)
+        #expect(levels == [.info, .verbose], "only the interval with the failure reaches the host handler")
+    }
+
     @Test("flush and close reset 1 Hz summary counters")
     func fel14FlushAndCloseResetSummaryCounters() throws {
-        let prevHandler = EngineLog.handler
-        defer { EngineLog.handler = prevHandler }
-
         var summaryLines: [String] = []
         let logLock = NSLock()
-        EngineLog.handler = { line in
-            if line.contains("[DualLayer] summary:") {
-                logLock.lock()
-                summaryLines.append(line)
-                logLock.unlock()
-            }
-        }
 
         let decoder = DualLayerVideoDecoder(composer: ImmediateFakeComposer())
         defer { decoder.close() }
 
         var currentTime: TimeInterval = 20.0
         decoder.summaryTimestampProviderForTesting = { currentTime }
+        decoder.summarySinkForTesting = { line, _ in
+            logLock.lock()
+            summaryLines.append(line)
+            logLock.unlock()
+        }
         decoder.primeForTesting(enhancementLayer: true)
 
         let baseBuf = try #require(Self.baseLayer())

From 83001da0ae76dae4eb837164a7cbc2f9335fb975 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 16:11:03 +0100
Subject: [PATCH 031/132] chore(dovi): docs: the per-second summary and GPU
 timing are verbose

docs/dolby-vision-fel.md sections 5.1 (rule 5), 5.10 (CPU table) and 5.11 described a 1 Hz
summary at the default level and a "[DoviFelComposer] gpu ... ms/frame" line that "stays".
Both are .verbose now (see the dual-layer decoder and composer log commits), so the text says so,
gives the log stream command that shows them, and names the one exception (a summary that counts a
compose failure stays at the default level). The summary prefix is "[DualLayerVideoDecoder]".
---
 docs/dolby-vision-fel.md | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index c17f6a2a1..b92fb7d8b 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -238,7 +238,8 @@ sections below are the rules that keep per-frame work and shared mutable state t
 3. **Nothing blocks while holding a lock, and every piece of state has one owner.**
 4. **Every frame has a bounded lifetime.** Bounded wait for its partner, bounded queues, bounded GPU
    work in flight, and nothing from before a flush survives it.
-5. **Per-frame work writes no log lines.** Counters feed a 1 Hz summary.
+5. **Per-frame work writes no log lines at the default level.** Counters feed a 1 Hz summary, which is
+   a `.verbose` line (§5.11).
 
 ### 5.2 Routing
 
@@ -522,7 +523,7 @@ CPU per composed frame:
 | libdovi RPU parses | 1 |
 | Base-layer access-unit copies | 0 (`CustomBlockSource` hands VideoToolbox the packet's own buffer) |
 | Enhancement-layer copies | 1 (extraction into a standalone access unit) |
-| Log lines at the default level | 0; a 1 Hz summary instead (§5.11) |
+| Log lines at the default level | 0 per frame; a 1 Hz summary at `.verbose` instead (§5.11) |
 | Parameter upload | written into a preallocated `MTLBuffer` |
 | Side-data lookup | the 32-entry ring, no sorting |
 | Shader compilation | once per process, lazily |
@@ -532,12 +533,21 @@ GPU: 12.9–14.3 ms per frame measured on the A12 (§4.2), against a 41.7 ms bud
 
 ### 5.11 Observability
 
-One `[DualLayer] summary` line per second while composing: frames composed, bypassed without EL,
-bypassed without RPU, stale enhancement frames dropped, maximum observed layer skew in frames, peak
-GPU slots in use, output pool buffers allocated, delivery pending peak, mean GPU ms. The existing
-`[DoviFelComposer] gpu … ms/frame` line stays. `os_signpost` intervals around compose and delivery
-make the pipeline readable in Instruments. Nothing else logs per frame; anything genuinely per-frame
-for debugging uses `EngineLog` level `.verbose`.
+One `[DualLayerVideoDecoder] summary` line per second while composing: frames composed, compose
+failures, bypassed without EL, bypassed without RPU, stale enhancement frames dropped, maximum
+observed layer skew in frames, peak GPU slots in use, output pool buffers allocated, delivery pending
+peak, mean GPU ms. `[DoviFelComposer] gpu … ms/frame` is the same kind of line, once per 120 composed
+frames. Both are `.verbose`: they go to OSLog's debug level and never reach the host handler, so they
+cost nothing unless the category's debug level is on:
+
+```
+log stream --level debug --predicate 'subsystem == "de.superuser404.AetherEngine" && category == "sw.playback"'
+```
+
+The exception is a summary whose second counted a compose failure, which goes out at the default level
+so the failure is visible without that. `os_signpost` intervals around compose and delivery make the
+pipeline readable in Instruments. Nothing else logs per frame; anything genuinely per-frame for
+debugging, such as the pairing, queueing and bypass traces, uses `EngineLog` level `.verbose` too.
 
 ### 5.12 Invariants and the tests that hold them
 

From a4fd0fd7ad4451c5acf31fe26ea9ecb208c2f18c Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 16:11:18 +0100
Subject: [PATCH 032/132] chore(probes): pulse host reads the soak tally from
 lines that still reach the handler

DolbyVisionPulseHostApp.swift, SoakTally: it summed composeFailures= over the engine's 1 Hz
"[DualLayer] summary" line seen through EngineLog.handler, and took the presence of that line as
proof the FEL route ran. The summary is .verbose now, which never reaches the handler, except for
a second that counted a compose failure, so the sum stays exact. The route marker is the
once-per-open "[DualLayerVideoDecoder] FEL stream detected" line instead (still the default
level), and the matched prefix follows the rename from "[DualLayer]".
---
 .../Device/Host/DolbyVisionPulseHostApp.swift  | 18 +++++++++++++-----
 Probes/DolbyVisionPulse/README.md              |  2 +-
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift b/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
index 4dd62a30a..a53374bf2 100644
--- a/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
+++ b/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
@@ -214,9 +214,11 @@ struct PulseHarnessView: View {
     /// Long-run FEL playback with a seek schedule. Measures only what the engine exposes publicly:
     /// - droppedFrames: `liveTelemetry.droppedFrameCount` (render synchronizer's dropped frames on the
     ///   software path, session total; nil reads as -1).
-    /// - composeFailures: sum of `composeFailures=` over the engine's 1 Hz `[DualLayer] summary` log
-    ///   lines (seen through EngineLog.handler; the counter itself is internal). Stays 0 if the FEL
-    ///   route never ran, so `route=` is the thing to check first.
+    /// - composeFailures: sum of `composeFailures=` over the engine's `[DualLayerVideoDecoder] summary`
+    ///   lines (seen through EngineLog.handler; the counter itself is internal). The engine writes that
+    ///   line every second at `.verbose`, which never reaches the handler, and at the default level only
+    ///   for a second that counted a failure, so the sum is exact. Stays 0 if the FEL route never ran,
+    ///   so `route=` is the thing to check first.
     /// - footprint: task_vm_info phys_footprint, sampled each second.
     @MainActor
     private func playSoak(_ arm: PulseArm, log: @Sendable (String) -> Void) async {
@@ -290,7 +292,9 @@ struct PulseHarnessView: View {
     }
 }
 
-/// Accumulates the engine's `[DualLayer] summary: ... composeFailures=N ...` lines (1 Hz, per-second deltas).
+/// Accumulates the engine's `[DualLayerVideoDecoder] summary: ... composeFailures=N ...` lines (per-second
+/// deltas; only the seconds with a failure reach the handler). The FEL route is recognised by its
+/// open-time line, since a healthy summary does not reach the handler.
 private final class SoakTally: @unchecked Sendable {
     private let lock = NSLock()
     private var failures = 0
@@ -298,7 +302,11 @@ private final class SoakTally: @unchecked Sendable {
     var composeFailures: Int { lock.lock(); defer { lock.unlock() }; return failures }
     var sawDualLayer: Bool { lock.lock(); defer { lock.unlock() }; return seen }
     func ingest(_ line: String) {
-        guard line.contains("[DualLayer] summary:") else { return }
+        if line.contains("[DualLayerVideoDecoder] FEL stream detected") {
+            lock.lock(); seen = true; lock.unlock()
+            return
+        }
+        guard line.contains("[DualLayerVideoDecoder] summary:") else { return }
         lock.lock(); defer { lock.unlock() }
         seen = true
         if let r = line.range(of: "composeFailures="),
diff --git a/Probes/DolbyVisionPulse/README.md b/Probes/DolbyVisionPulse/README.md
index e839d7af9..c49e3bb65 100644
--- a/Probes/DolbyVisionPulse/README.md
+++ b/Probes/DolbyVisionPulse/README.md
@@ -123,7 +123,7 @@ frames of any composer's output and prints `ok`, `MISMATCH` or `no-EL` per frame
 The soak arm is not a pulse measurement. It plays a FEL title for several minutes through a seek
 schedule and reports one line, `soak summary: played= seeks= droppedFrames= composeFailures=
 peakFootprintMB= endFootprintMB= route=`. Check `route=` first: it reads `FEL` only if the engine's
-dual-layer summary lines were seen, and a run that never took the route reports zero compose failures
+dual-layer decoder reported a FEL stream (or a summary line with a failure), and a run that never took the route reports zero compose failures
 for the wrong reason.
 
 ## Run on an Apple TV

From bde80ba9ddb33bd27a54dea796808507467cf81c Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:00:19 +0000
Subject: [PATCH 033/132] fix(dovi): deliver the frames still owed at end of
 stream instead of dropping them

`flush()` raises `draining` and moves the delivery epoch before it drains the
sessions, so everything VideoToolbox, the GPU and the pairing queues still hold
is dropped. That is right for a seek, but the host also calls `flush()` at end of
stream, right after feeding the last packet, and there it drops the last frames
of every title. `drainForEndOfStream()` drains both sessions without the gate,
sends any base-layer frame still waiting for its enhancement layer out alone
under its ticket, and returns once the frames have reached `onFrame` (or after
0.5 s with a composition still on the GPU).
---
 .../Decoder/DualLayerVideoDecoder.swift       | 54 +++++++++++++++++-
 .../DoviFelRealFileTests.swift                | 15 +++++
 .../DualLayerVideoDecoderTests.swift          | 55 +++++++++++++++++++
 3 files changed, 123 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
index a6cec3f1d..c2aef494c 100644
--- a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -341,7 +341,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     private var summaryComposeFailures: Int = 0
     /// Compositions started, and compositions whose frame (composed or fallback) has been handed to
     /// `orderedDelivery`. Equal when nothing is on the GPU or in a completion handler. Guarded by
-    /// `composeResultLock`; read only by `quiesceForTesting`.
+    /// `composeResultLock`; read by `drainForEndOfStream` and `quiesceForTesting`.
     private var composeRequestsStarted = 0
     private var composeRequestsHandedOff = 0
     private var summaryBypassNoEL: Int = 0
@@ -1370,6 +1370,58 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         composer?.flush()
     }
 
+    /// How long `drainForEndOfStream()` waits for compositions still on the GPU.
+    static let endOfStreamComposeWait: TimeInterval = 0.5
+
+    /// End of stream: delivers the frames still owed, which `flush()` drops. `flush()` cannot tell the
+    /// frames it drains from pre-seek ones, so it drops everything the sessions, the GPU and the pairing
+    /// queues still hold, and at the end of the stream that is the last frames of the title. The host
+    /// calls this once the last packet has been fed, before its end-of-stream `flush()`.
+    ///
+    /// The drained frames pair as usual; a base-layer frame whose enhancement layer never came goes out
+    /// alone, under its own ticket. Returns once everything has reached `onFrame`, or after
+    /// `endOfStreamComposeWait` if a composition is still on the GPU.
+    func drainForEndOfStream() {
+        lifecycleLock.lock()
+        defer { lifecycleLock.unlock() }
+        lock.lock()
+        guard !isClosed else { lock.unlock(); return }
+        let primary = primaryDecoder
+        let el = enhancementDecoder
+        lock.unlock()
+
+        // Without `draining`, and without moving the epoch: what the sessions still owe arrives through
+        // the normal callbacks while these wait, and pairs with what the other layer already sent.
+        primary.flushKeepingEpoch()
+        el?.flushKeepingEpoch()
+
+        let unpaired: [BypassRequest] = {
+            lock.lock()
+            defer { lock.unlock() }
+            var due: [BypassRequest] = []
+            for k in blFrameQueue.keys.sorted() {
+                guard let entry = blFrameQueue.removeValue(forKey: k) else { continue }
+                summaryBypassNoEL += 1
+                noteSettledBaseLayer(key: k)
+                due.append(BypassRequest(ticket: entry.ticket, epoch: _feedEpoch, buffer: entry.buffer, pts: entry.pts, hdr10Data: entry.side.hdr10Data, dmNAL: entry.side.dmNAL, reason: "end-of-stream"))
+            }
+            return due
+        }()
+        for req in unpaired {
+            fulfilBypass(req)
+        }
+
+        let deadline = ProcessInfo.processInfo.systemUptime + Self.endOfStreamComposeWait
+        while ProcessInfo.processInfo.systemUptime < deadline {
+            composeResultLock.lock()
+            let idle = composeRequestsStarted == composeRequestsHandedOff
+            composeResultLock.unlock()
+            if idle { break }
+            usleep(500)
+        }
+        orderedDelivery.barrier()
+    }
+
     func close() {
         lifecycleLock.lock()
         defer { lifecycleLock.unlock() }
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
index b1f18cf58..43f3de8b7 100644
--- a/Tests/AetherEngineTests/DoviFelRealFileTests.swift
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -315,6 +315,21 @@ struct DoviFelRealFileTests {
         print(String(format: "[fallback] %@: worst per-plane mean |d| %.2f (10-bit codes)", name, worstMean))
     }
 
+    @Test("the end-of-stream drain delivers a frame for every packet fed, leaving nothing for the flush after it",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(2)), arguments: [DoviFelRealFileTests.fixtures[0]])
+    func endOfStreamDrainDeliversTheLastFrames(name: String) throws {
+        let s = try Self.open(name)
+        defer { s.decoder.close(); s.demuxer.close() }
+        // The clip opens on an IDR, so every packet from its head decodes to one frame.
+        let fed = Self.feed(s, count: 120)
+        s.decoder.drainForEndOfStream()
+        let drained = s.sink.pts.count
+        #expect(drained == fed, "\(drained) frames from \(fed) packets")
+        s.decoder.flush()
+        #expect(s.sink.pts.count == drained, "the drain left frames for the flush to drop")
+    }
+
     @Test("a flush before the first enhancement packet leaves the enhancement decoder in step: its frames still arrive",
           .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips),
           .timeLimit(.minutes(2)), arguments: [DoviFelRealFileTests.fixtures[0]])
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 2cce66221..ce63c230e 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -894,6 +894,61 @@ struct DualLayerVideoDecoderTests {
         #expect(CMTimeCompare(deliveries.snapshot.first?.pts ?? .invalid, Self.pts(1)) == 0)
     }
 
+    @Test("the end-of-stream drain delivers the frames the sessions still owe, paired or alone, in order")
+    func endOfStreamDrainDeliversOwedFrames() async throws {
+        let primary = FlushEmittingFakeDecoder()
+        let enhancement = FlushEmittingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        let deliveries = Deliveries()
+        decoder.onFrame = { buffer, pts, hdr10 in deliveries.record(buffer, pts, hdr10) }
+        decoder.primeForTesting(enhancementLayer: true)
+        defer { decoder.close() }
+
+        let bl: [SendableFrameBuffer] = try (0..<3).map { _ in
+            guard let b = Self.baseLayer() else { throw CancellationError() }
+            return SendableFrameBuffer(value: b)
+        }
+        let el: [SendableFrameBuffer] = try (0..<2).map { _ in
+            guard let e = Self.enhancementLayer() else { throw CancellationError() }
+            return SendableFrameBuffer(value: e)
+        }
+        for i in 0..<3 {
+            decoder.seedRPUForTesting(pts: Self.pts(Int64(i)), params: Self.params(), displayMetadataNAL: nil)
+        }
+        // The last frames of a stream, still inside the sessions after the last packet was fed: three
+        // base-layer frames, and enhancement-layer frames for the first two only.
+        primary.emitFromInsideFlush = {
+            for i in 0..<3 {
+                decoder.handleBaseLayerFrame(baseBuffer: bl[i].value, pts: Self.pts(Int64(i)), hdr10Data: nil)
+            }
+        }
+        enhancement.emitFromInsideFlush = {
+            for i in 0..<2 {
+                decoder.handleEnhancementLayerFrame(elBuffer: el[i].value, pts: Self.pts(Int64(i)))
+            }
+        }
+
+        decoder.drainForEndOfStream()
+        // No wait: the drain returns once its frames have reached `onFrame`.
+        let frames = deliveries.snapshot
+        #expect(frames.count == 3)
+        #expect(frames.map { ObjectIdentifier($0.buffer) } == bl.map { ObjectIdentifier($0.value) })
+        #expect(Self.isStrictlyIncreasing(frames))
+        #expect(decoder.composedFrameCount == 2, "the two frames with an enhancement layer are composed")
+        #expect(decoder.stateSnapshotForTesting.blQueueCount == 0)
+
+        // The host's flush that follows has nothing left to drop or deliver.
+        primary.emitFromInsideFlush = nil
+        enhancement.emitFromInsideFlush = nil
+        decoder.flush()
+        decoder.quiesceForTesting()
+        #expect(deliveries.count == 3)
+    }
+
     // MARK: - Thread safety
 
     /// Synchronous composer so the stress test needs no GPU: every composition

From 66cf433fd296b86eb47178f1b9dc057716bc90f2 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:00:43 +0000
Subject: [PATCH 034/132] fix(dovi): drain the FEL decoder before the
 end-of-stream flush

At end of media, at the end of a DVR ring and at a timeline seam the host
flushes the video decoder right after feeding the last packet. On the FEL route
that flush drops the frames the sessions and the GPU still hold, so the last
frames of every title never reached the layer. Drain them first.
---
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index f8800a22d..66bc1d67e 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -2640,6 +2640,7 @@ final class SoftwarePlaybackHost {
                 // next append, or finish when the source is gone and the
                 // ring is fully drained.
                 if sourceEnded() {
+                    (videoDecoder as? DualLayerVideoDecoder)?.drainForEndOfStream()
                     videoDecoder.flush()
                     audioDecoder?.flush()
                     renderer.drainReorderBuffer()
@@ -3158,6 +3159,9 @@ final class SoftwarePlaybackHost {
                 waitForRenderer(.drainAll)
                 guard admitsRead(genBeforeRead) else { return !stopRequested() }
                 freeParkedVideo()
+                // The dual-layer decoder's flush drops what its sessions and the GPU still hold,
+                // which here is the last frames of the stream: hand those over first.
+                (videoDecoder as? DualLayerVideoDecoder)?.drainForEndOfStream()
                 videoDecoder.flush()
                 audioDecoder?.flush()
                 renderer.drainReorderBuffer()
@@ -3187,6 +3191,7 @@ final class SoftwarePlaybackHost {
                         // its reference chain; the seam packet itself parks after this block.
                         waitForRenderer(.drainAll)
                         freeParkedVideo()
+                        (videoDecoder as? DualLayerVideoDecoder)?.drainForEndOfStream()
                         videoDecoder.flush()
                         // AE#492: this flush is THIS thread's, made after the read and on behalf of
                         // the packet in hand. Retiring that packet along with the seam it opens

From 93f3f03a45ed7a6f9cde58a97ed9ceb232f434e7 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:02:10 +0000
Subject: [PATCH 035/132] fix(dovi): let the dual-layer decoder report and
 rebuild invalidated sessions

The host recovers from a session the system invalidated (AE#739) only through
`HardwareVideoDecoder`: it installs `onSessionLost` and calls `rebuildSession()`
on that type alone. On the FEL route neither sub-decoder had a handler, so a
session lost to a screen lock or a media-services reset was never noticed and
the layers dropped every later packet: video stayed frozen while audio played on.

`VideoSessionRebuilding` names the two members the host uses; both decoders
conform. The dual-layer decoder hands the handler to both sub-decoders (and to
the enhancement decoder when it opens), and rebuilds both sessions, then puts
both back on its own feed epoch: each sub-decoder's rebuild moves its epoch,
and the packets the host feeds carry the owner's.
---
 .../Decoder/DualLayerVideoDecoder.swift       | 53 +++++++++++++++++++
 .../DoviFelRealFileTests.swift                | 20 +++++++
 .../DualLayerVideoDecoderTests.swift          | 41 ++++++++++++++
 3 files changed, 114 insertions(+)

diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
index c2aef494c..4cf8908ce 100644
--- a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -93,6 +93,16 @@ extension SingleLayerVideoDecoder {
 
 extension HardwareVideoDecoder: SingleLayerVideoDecoder {}
 
+/// AE#739: a decoder whose VideoToolbox sessions the system can invalidate behind its back, and that
+/// can build them again. The host recovers through this rather than through one decoder type.
+protocol VideoSessionRebuilding: AnyObject {
+    var onSessionLost: (@Sendable () -> Void)? { get set }
+    @discardableResult func rebuildSession() -> Bool
+}
+
+extension HardwareVideoDecoder: VideoSessionRebuilding {}
+extension DualLayerVideoDecoder: VideoSessionRebuilding {}
+
 /// Video decoding pipeline that transparently coordinates dual VideoToolbox HEVC decoders
 /// (base layer, typically 4K, plus an enhancement layer, typically 1080p) and reconstructs the 12-bit master on Apple GPU
 /// using `DoviFelComposer`. Falls back smoothly to single-layer BL if no EL is present (MEL / P8.1).
@@ -169,6 +179,22 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     }
     private var _skipUntilPTS: CMTime?
 
+    /// AE#739: called when the system invalidates either layer's session. Handed to both sub-decoders
+    /// (outside `lock`, as `skipUntilPTS` is), and to the enhancement decoder when it opens.
+    var onSessionLost: (@Sendable () -> Void)? {
+        get { lock.lock(); defer { lock.unlock() }; return _onSessionLost }
+        set {
+            lock.lock()
+            _onSessionLost = newValue
+            let primary = primaryDecoder
+            let enhancement = enhancementDecoder
+            lock.unlock()
+            (primary as? HardwareVideoDecoder)?.onSessionLost = newValue
+            (enhancement as? HardwareVideoDecoder)?.onSessionLost = newValue
+        }
+    }
+    private var _onSessionLost: (@Sendable () -> Void)?
+
     /// The primary decoder's own methods are internally synchronized
     /// (`HardwareVideoDecoder.lock` / `skipLock`); it is safe to call without holding
     /// this decoder's `lock`, and callers must do so to preserve the lock ordering
@@ -709,6 +735,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         var s = elSPS
         var p = elPPS
         let skip = _skipUntilPTS
+        let sessionLost = _onSessionLost
         let tb = timeBase
         lock.unlock()
         guard let data = packet.pointee.data, packet.pointee.size > 4 else { return }
@@ -735,6 +762,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         }
         let decoder = makeEnhancementDecoder()
         decoder.skipUntilPTS = skip
+        (decoder as? HardwareVideoDecoder)?.onSessionLost = sessionLost
         do {
             try decoder.open(parameterSets: [vv, ss, pp], timeBase: tb) { [weak self] elBuffer, pts, _ in
                 self?.handleEnhancementLayerFrame(elBuffer: elBuffer, pts: pts)
@@ -1422,6 +1450,31 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         orderedDelivery.barrier()
     }
 
+    /// AE#739: rebuilds both layers' sessions after the system invalidated them, the way
+    /// `HardwareVideoDecoder.rebuildSession()` does for one. Each sub-decoder's rebuild moves its own
+    /// feed epoch to retire what was fed to the old session; both are put back on this decoder's epoch,
+    /// which is the one the host's packets carry, or every later packet would be refused. Each layer
+    /// then resumes at its next keyframe. False when VideoToolbox refused either session.
+    @discardableResult
+    func rebuildSession() -> Bool {
+        lifecycleLock.lock()
+        defer { lifecycleLock.unlock() }
+        lock.lock()
+        guard !isClosed else { lock.unlock(); return false }
+        let primary = primaryDecoder
+        let enhancement = enhancementDecoder
+        let primaryOpen = primaryDecoderInitialized
+        let epoch = _feedEpoch
+        lock.unlock()
+        // A primary still waiting for its in-band parameter sets has no session to lose yet.
+        let primaryRebuilt = !primaryOpen || ((primary as? HardwareVideoDecoder)?.rebuildSession() ?? true)
+        let enhancementRebuilt = (enhancement as? HardwareVideoDecoder)?.rebuildSession() ?? true
+        // `flush()` and `close()` wait on `lifecycleLock`, so `epoch` is still this decoder's.
+        primary.adoptFeedEpoch(epoch)
+        enhancement?.adoptFeedEpoch(epoch)
+        return primaryRebuilt && enhancementRebuilt
+    }
+
     func close() {
         lifecycleLock.lock()
         defer { lifecycleLock.unlock() }
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
index 43f3de8b7..4fe0a555a 100644
--- a/Tests/AetherEngineTests/DoviFelRealFileTests.swift
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -330,6 +330,26 @@ struct DoviFelRealFileTests {
         #expect(s.sink.pts.count == drained, "the drain left frames for the flush to drop")
     }
 
+    @Test("a session rebuild leaves both layers on the decoder's epoch: packets fed after it still decode",
+          .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips),
+          .timeLimit(.minutes(2)), arguments: [DoviFelRealFileTests.fixtures[0]])
+    func sessionRebuildKeepsTheEpoch(name: String) async throws {
+        let s = try Self.open(name)
+        defer { s.decoder.close(); s.demuxer.close() }
+        Self.feed(s, count: 30, epoch: s.decoder.feedEpoch)
+        #expect(s.decoder.enhancementFeedEpochForTesting != nil)
+        // The host's return from background audio-only: flush, rebuild, then feed on with no
+        // reposition in between, so nothing else moves the layers' epochs back.
+        s.decoder.flush()
+        #expect(s.decoder.rebuildSession())
+        #expect(s.decoder.enhancementFeedEpochForTesting == s.decoder.feedEpoch)
+        let before = s.sink.pts.count
+        // A rebuilt session resumes at a keyframe: feed again from the head of the clip.
+        s.demuxer.seek(to: 0)
+        Self.feed(s, count: 30, epoch: s.decoder.feedEpoch)
+        try await waitFor { s.sink.pts.count > before }
+    }
+
     @Test("a flush before the first enhancement packet leaves the enhancement decoder in step: its frames still arrive",
           .enabled(if: DoviFelRealFileTests.available(DoviFelRealFileTests.fixtures[0]), DoviFelRealFileTests.needsClips),
           .timeLimit(.minutes(2)), arguments: [DoviFelRealFileTests.fixtures[0]])
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index ce63c230e..aecc71135 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -949,6 +949,47 @@ struct DualLayerVideoDecoderTests {
         #expect(deliveries.count == 3)
     }
 
+    // MARK: - Session loss (AE#739)
+
+    @Test("the session-loss handler reaches both layers' decoders, and clearing it clears both")
+    func sessionLostHandlerReachesBothLayers() {
+        let primary = HardwareVideoDecoder()
+        let enhancement = HardwareVideoDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        defer { decoder.close() }
+        let calls = SessionLossCount()
+        decoder.onSessionLost = { calls.bump() }
+        primary.onSessionLost?()
+        enhancement.onSessionLost?()
+        #expect(calls.value == 2)
+        decoder.onSessionLost = nil
+        #expect(primary.onSessionLost == nil)
+        #expect(enhancement.onSessionLost == nil)
+    }
+
+    @Test("a closed decoder refuses a session rebuild")
+    func closedDecoderRefusesRebuild() {
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: FlushEmittingFakeDecoder(),
+            enhancementDecoder: FlushEmittingFakeDecoder()
+        )
+        #expect(decoder.rebuildSession())
+        decoder.close()
+        #expect(!decoder.rebuildSession())
+    }
+
+    private final class SessionLossCount: @unchecked Sendable {
+        private let lock = NSLock()
+        private var count = 0
+        func bump() { lock.lock(); count += 1; lock.unlock() }
+        var value: Int { lock.lock(); defer { lock.unlock() }; return count }
+    }
+
     // MARK: - Thread safety
 
     /// Synchronous composer so the stress test needs no GPU: every composition

From e625ef9c030b1f7f70ecc6bda7f6bc5f3e7ceca6 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:02:40 +0000
Subject: [PATCH 036/132] fix(dovi): recover the FEL route's sessions after the
 system invalidates them

The AE#739 recovery (handler, rebuild on loss and on the foreground return)
looked only for `HardwareVideoDecoder`, so on the dual-layer route a lost
session froze the video for the rest of the session. Go through
`VideoSessionRebuilding`, which both decoders implement.
---
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 66bc1d67e..12ea873c7 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1101,7 +1101,8 @@ final class SoftwarePlaybackHost {
         videoDecoder.onDecodedFormat = { [weak self] format in
             self?.onDecodedVideoFormat?(format)
         }
-        (videoDecoder as? HardwareVideoDecoder)?.onSessionLost = { [weak self] in
+        // Both VideoToolbox decoders, the dual-layer one included: its two sessions can be lost the same way.
+        (videoDecoder as? any VideoSessionRebuilding)?.onSessionLost = { [weak self] in
             Task { @MainActor [weak self] in self?.handleVideoSessionLost() }
         }
         videoDecoder.onA53Captions = { [weak self] triplets, pts in
@@ -1475,7 +1476,7 @@ final class SoftwarePlaybackHost {
         if backgroundAudioOnly {
             videoDecoder.flush()
             renderer.flush()
-            let rebuilt = (videoDecoder as? HardwareVideoDecoder)?.rebuildSession()
+            let rebuilt = (videoDecoder as? any VideoSessionRebuilding)?.rebuildSession()
             if rebuilt == false { videoSessionRecoveryOwed = true }
             backgroundAudioOnly = false
             EngineLog.emit(
@@ -1512,7 +1513,7 @@ final class SoftwarePlaybackHost {
     /// at instead of freezing until the next keyframe. A live source without a rewind ring cannot go
     /// back and picks up at the next keyframe. A refused rebuild stays owed to the next foreground return.
     private func recoverVideoSession() {
-        guard !stopRequested, let hw = videoDecoder as? HardwareVideoDecoder else {
+        guard !stopRequested, let hw = videoDecoder as? any VideoSessionRebuilding else {
             videoSessionRecoveryOwed = false
             return
         }

From cf80ed5ca6e972d5da1d96626d95735599f0bc4f Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:05:13 +0000
Subject: [PATCH 037/132] test(dovi): DEBUG hook that invalidates both FEL
 sessions, for the AE#739 harness

---
 .../AetherEngine/Decoder/DualLayerVideoDecoder.swift  | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
index 4cf8908ce..9ff472c4c 100644
--- a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -1606,6 +1606,17 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         orderedDelivery.barrier()
     }
 
+    /// Invalidates both layers' sessions without forgetting them, as the system does on an iOS screen
+    /// lock (`HardwareVideoDecoder.invalidateSessionForTesting()`). For the aetherctl harness.
+    func invalidateSessionsForTesting() {
+        lock.lock()
+        let primary = primaryDecoder
+        let enhancement = enhancementDecoder
+        lock.unlock()
+        (primary as? HardwareVideoDecoder)?.invalidateSessionForTesting()
+        (enhancement as? HardwareVideoDecoder)?.invalidateSessionForTesting()
+    }
+
     /// Issues a ticket the same way `handleBaseLayerFrame` would — under
     /// `lock`, in decode order, tagged with the current epoch — and hands it
     /// straight to `orderedDelivery`, bypassing the `draining` gate that

From fd0fdce6d3d11267c28c6d483ecf098e8782a28f Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 17:05:15 +0000
Subject: [PATCH 038/132] test(dovi): the AE#739 harness hook reaches the FEL
 route's sessions

---
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 12ea873c7..75ea1bac5 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1489,6 +1489,10 @@ final class SoftwarePlaybackHost {
 
     #if DEBUG
     func invalidateVideoSessionForTesting() -> Bool {
+        if let dual = videoDecoder as? DualLayerVideoDecoder {
+            dual.invalidateSessionsForTesting()
+            return true
+        }
         guard let hw = videoDecoder as? HardwareVideoDecoder else { return false }
         hw.invalidateSessionForTesting()
         return true

From dc1f266678bb6008bd133825446a9e733d2c61b7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 14 Oct 2026 21:28:32 +0200
Subject: [PATCH 039/132] fix(iframes): serve tone-mapped Motion JPEG stills
 for HDR and Dolby Vision (#682)

The stock tvOS scrubber fetches the first keyframe of a PQ I-frame
rendition and then leaves the thumbnail box empty. Measured on an Apple
TV 4K (tvOS 27): Dolby Vision profile 5 and 8.1, plain HDR10, 4K and
1080p all fail the same way; the same keyframes boxed as BT.709 SDR are
shown, and so is a motion JPEG tier in the shape of Apple's adv_dv_atmos
stream.

An HDR or Dolby Vision session now lists CODECS="mjpg", VIDEO-RANGE=SDR,
640 pixels wide. Each still is the keyframe the side reader already
reads, wrapped as before, decoded through FrameDecodeContext (tone map
for PQ/HLG, RPU reshaping for profile 5), scaled and JPEG-encoded with a
byte cap that keeps BANDWIDTH honest. Built fragments are kept in memory
because AVKit asks for the same still more than once. SDR sessions keep
serving their own keyframes. The session log names the format.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |   9 +
 .../AetherEngine/Network/HLSLocalServer.swift |  12 +-
 Sources/AetherEngine/PlayerState.swift        |   2 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   |  42 +++-
 .../Video/IFrameJPEGBuilder.swift             | 182 ++++++++++++++++++
 .../AetherEngine/Video/IFrameRendition.swift  |  19 ++
 .../Video/VideoSegmentProvider.swift          |   1 +
 .../IFrameJPEGBuilderTests.swift              | 125 ++++++++++++
 .../IFramePlaylistTextTests.swift             |  17 +-
 .../IFrameSessionTests.swift                  |  30 +++
 docs/api.md                                   |   2 +-
 docs/cli.md                                   |   2 +-
 12 files changed, 429 insertions(+), 14 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/IFrameJPEGBuilder.swift
 create mode 100644 Tests/AetherEngineTests/IFrameJPEGBuilderTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cbc29c6c5..834cdace5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,15 @@ the public-API contract.
 
 ### Fixed
 
+- **`serveIFramePlaylist` shows scrub thumbnails for HDR10, HLG and Dolby Vision titles** (#682). The
+  stock tvOS scrubber fetched the first keyframe of a PQ rendition and then left the thumbnail box empty,
+  for Dolby Vision profile 5 and 8.1 as much as for plain HDR10, at 4K and at 1080p (measured on an Apple
+  TV 4K, tvOS 27). An HDR or Dolby Vision session now lists a Motion JPEG rendition instead
+  (`CODECS="mjpg"`, `VIDEO-RANGE=SDR`, 640 pixels wide), whose stills come from the engine's own still
+  pipeline: the tone map for PQ and HLG, the RPU reshaping for profile 5. SDR sessions keep serving their
+  own keyframes. The session log names the format: `i-frame rendition: served segments=<n>
+  format=keyframes|jpeg`.
+
 - **A 25 fps H.264 Matroska file with forward-clamped B-picture timestamps plays at a steady
   cadence.** Its packet timestamps repeated display slots and left the preceding slots empty, so
   decoded output alternated 0 ms and 80 ms frame intervals instead of 40 ms. The demuxer now
diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index cb72d9852..f52410e44 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -119,6 +119,8 @@ protocol HLSSegmentProvider: AnyObject {
     /// 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 }
+    /// What the rendition carries; nil reads as `.keyframes`.
+    var iFrameRenditionFormat: IFrameRenditionFormat? { get }
     func iFrameInitSegment() -> Data?
     func iFrameSegment(at index: Int) -> Data?
 
@@ -198,6 +200,7 @@ extension HLSSegmentProvider {
     var nativeSubtitleWholeProgram: Bool { false }
     func nativeSubtitleVTT(ordinal: Int, segmentIndex: Int) -> String? { nil }
     var iFrameRenditionServed: Bool { false }
+    var iFrameRenditionFormat: IFrameRenditionFormat? { nil }
     func iFrameInitSegment() -> Data? { nil }
     func iFrameSegment(at index: Int) -> Data? { nil }
     var liveTargetSegmentDuration: Double? { nil }
@@ -1822,7 +1825,14 @@ final class HLSLocalServer: @unchecked Sendable {
         }
         lines.append("#EXT-X-STREAM-INF:\(streamInfAttrs.joined(separator: ","))")
         lines.append("media.m3u8")
-        if provider.iFrameRenditionServed {
+        if provider.iFrameRenditionServed,
+           case .jpeg(let width, let height, let jpegBandwidth) = provider.iFrameRenditionFormat {
+            // AE#682: AVKit shows no scrub thumbnail from a PQ or Dolby Vision keyframe, so an HDR
+            // session lists SDR stills, the shape of Apple's own motion JPEG trick-play tier.
+            let iFrameAttrs = ["BANDWIDTH=\(jpegBandwidth)", "CODECS=\"mjpg\"", "RESOLUTION=\(width)x\(height)",
+                               "VIDEO-RANGE=SDR", "URI=\"iframe.m3u8\""]
+            lines.append("#EXT-X-I-FRAME-STREAM-INF:\(iFrameAttrs.joined(separator: ","))")
+        } else 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))\""]
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 68892ce54..d1616efd7 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -694,7 +694,7 @@ 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`.
+    /// 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 still per served segment: the source's own keyframe at full resolution for SDR, and for HDR10, HLG and Dolby Vision a tone-mapped SDR Motion JPEG 640 pixels wide, since AVKit shows no scrub thumbnail from a PQ or Dolby Vision keyframe. 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
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index a5f1500d8..4bbc3fd9f 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -2208,11 +2208,13 @@ public final class HLSVideoEngine: @unchecked Sendable {
         self.servingMasterPlaylist = useMasterPlaylist
         iFrameRenditionVerdict = IFrameRenditionEligibility.resolve(
             candidate: iFrameCandidate, servingMaster: useMasterPlaylist)
-        if iFrameRenditionVerdict == .served, let rendition = makeIFrameRendition(plan: plan, cache: segmentCache) {
+        if iFrameRenditionVerdict == .served,
+           let rendition = makeIFrameRendition(plan: plan, cache: segmentCache,
+                                               sourceIsHDR: videoRange != .sdr || dvVariant != .none) {
             iFrameRendition = rendition
             prov.setIFrameSource(rendition)
-            EngineLog.emit("[HLSVideoEngine] i-frame rendition: served segments=\(plan.count)",
-                           category: .session)
+            EngineLog.emit("[HLSVideoEngine] i-frame rendition: served segments=\(plan.count) "
+                           + "format=\(rendition.format.logName)", category: .session)
         } else if iFramePlaylistRequested {
             closeUnusedCustomIFrameReader()
             if iFrameRenditionVerdict == .served { iFrameRenditionVerdict = .absent(.noSecondReader) }
@@ -2741,7 +2743,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
 
     // MARK: - I-frame rendition (AE#682)
 
-    private func makeIFrameRendition(plan: [Segment], cache segmentCache: SegmentCache) -> IFrameRendition? {
+    /// `sourceIsHDR` picks the format: AVKit shows no scrub thumbnail from a PQ or Dolby Vision
+    /// keyframe, so those sessions serve tone-mapped JPEG stills instead of the keyframes themselves.
+    private func makeIFrameRendition(plan: [Segment], cache segmentCache: SegmentCache,
+                                     sourceIsHDR: Bool) -> 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)
@@ -2752,7 +2757,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
                            category: .session)
             return nil
         }
-        let builder = IFrameFragmentBuilder(
+        let keyframeBuilder = IFrameFragmentBuilder(
             video: MP4SegmentMuxer.VideoConfig(
                 codecpar: cfg.codecpar, timeBase: cfg.timeBase,
                 codecTagOverride: cfg.codecTagOverride, doviConfig: cfg.doviConfig,
@@ -2760,6 +2765,27 @@ public final class HLSVideoEngine: @unchecked Sendable {
                 convertsAnnexBSamples: cfg.convertsAnnexBSamples,
                 nalFramingLatch: cfg.nalFramingLatch),
             stagingDir: staging)
+        let format: IFrameRenditionFormat
+        let buildFragment: (Data, Int, IFrameRendition.Entry) -> IFrameFragmentBuilder.Output?
+        let par = cfg.codecpar.pointee
+        if sourceIsHDR, let size = IFrameJPEGBuilder.size(
+            codedWidth: Int(par.width), codedHeight: Int(par.height),
+            sarNum: par.sample_aspect_ratio.num, sarDen: par.sample_aspect_ratio.den) {
+            let jpeg = IFrameJPEGBuilder(keyframe: keyframeBuilder, width: size.width, height: size.height)
+            let shortest = plan.map(\.durationSeconds).filter { $0 > 0 }.min() ?? 1
+            format = .jpeg(width: size.width, height: size.height,
+                           bandwidth: IFrameJPEGBuilder.bandwidth(shortestSegmentSeconds: shortest))
+            buildFragment = { payload, index, entry in
+                jpeg.build(payload: payload, index: index,
+                           startSeconds: entry.startSeconds, durationSeconds: entry.durationSeconds)
+            }
+        } else {
+            format = .keyframes
+            buildFragment = { payload, index, entry in
+                keyframeBuilder.build(payload: payload, index: index,
+                                      startSeconds: entry.startSeconds, durationSeconds: entry.durationSeconds)
+            }
+        }
         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) },
@@ -2786,11 +2812,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
         return IFrameRendition(
             entries: entries,
             cache: IFramePayloadCache(directory: directory.appendingPathComponent("payloads", isDirectory: true)),
+            format: format,
             readPayload: { reader.payload(startPts: $0.startPts) },
-            buildFragment: { payload, index, entry in
-                builder.build(payload: payload, index: index,
-                              startSeconds: entry.startSeconds, durationSeconds: entry.durationSeconds)
-            },
+            buildFragment: buildFragment,
             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.
diff --git a/Sources/AetherEngine/Video/IFrameJPEGBuilder.swift b/Sources/AetherEngine/Video/IFrameJPEGBuilder.swift
new file mode 100644
index 000000000..6a16cefcc
--- /dev/null
+++ b/Sources/AetherEngine/Video/IFrameJPEGBuilder.swift
@@ -0,0 +1,182 @@
+// Sources/AetherEngine/Video/IFrameJPEGBuilder.swift
+import Foundation
+import CoreGraphics
+import ImageIO
+import UniformTypeIdentifiers
+
+/// AE#682: turns one keyframe into one Motion JPEG fragment, for sources whose own keyframes AVKit
+/// will not show as scrub thumbnails.
+///
+/// Measured on an Apple TV 4K (tvOS 27, 2026-10-14): the stock scrubber fetches the init and one
+/// I-frame of a PQ rendition and then gives up, whether the keyframes are Dolby Vision or plain HDR10,
+/// 4K or 1080p. The same keyframes declared and boxed as BT.709 SDR are shown. So an HDR source gets an
+/// SDR picture instead, from the still pipeline the engine already has (tone map for PQ/HLG, RPU
+/// reshaping for Dolby Vision profile 5), as JPEG in the shape of Apple's own `mjpg` trick-play tier.
+final class IFrameJPEGBuilder {
+    static let defaultWidth = 640
+    /// A JPEG above this is encoded again at lower quality, so the master's BANDWIDTH stays honest.
+    static let maxFrameBytes = 192 * 1024
+    private static let qualities: [CGFloat] = [0.8, 0.6, 0.4, 0.25]
+    private static let timescale: UInt32 = 90_000
+
+    /// Built fragments kept in memory (about 50 KB each): AVKit asks for the same still several times,
+    /// and each build is a full decode of the keyframe.
+    static let cachedFragments = 128
+
+    let width: Int
+    let height: Int
+    let initSegment: Data
+    private let keyframe: IFrameFragmentBuilder
+    private let lock = NSLock()
+    private var built: [Int: Data] = [:]
+    private var builtOrder: [Int] = []
+
+    init(keyframe: IFrameFragmentBuilder, width: Int, height: Int) {
+        self.keyframe = keyframe
+        self.width = width
+        self.height = height
+        self.initSegment = Self.makeInit(width: width, height: height)
+    }
+
+    /// Output size for a source of `codedWidth` x `codedHeight` with sample aspect `sar`, even on both
+    /// axes so every JPEG decoder takes it.
+    static func size(codedWidth: Int, codedHeight: Int, sarNum: Int32, sarDen: Int32,
+                     maxWidth: Int = defaultWidth) -> (width: Int, height: Int)? {
+        guard codedWidth > 0, codedHeight > 0 else { return nil }
+        let num = sarNum > 0 ? Double(sarNum) : 1
+        let den = sarDen > 0 ? Double(sarDen) : 1
+        let displayWidth = Double(codedWidth) * num / den
+        let w = min(maxWidth, Int(displayWidth.rounded()))
+        let h = Double(w) * Double(codedHeight) / displayWidth
+        let even = { (v: Double) in max(2, Int((v / 2).rounded()) * 2) }
+        return (even(Double(w)), even(h))
+    }
+
+    /// Highest declared bitrate a fragment can reach: the byte cap over the shortest segment.
+    static func bandwidth(shortestSegmentSeconds: Double) -> Int {
+        let seconds = max(shortestSegmentSeconds, 0.1)
+        return Int((Double(maxFrameBytes + 256) * 8 / seconds).rounded(.up))
+    }
+
+    func build(payload: Data, index: Int, startSeconds: Double,
+               durationSeconds: Double) -> IFrameFragmentBuilder.Output? {
+        if let hit = lock.withLock({ built[index] }) {
+            return IFrameFragmentBuilder.Output(initSegment: initSegment, fragment: hit)
+        }
+        guard let source = keyframe.build(payload: payload, index: index, startSeconds: startSeconds,
+                                          durationSeconds: durationSeconds),
+              let picture = Self.decode(source),
+              let jpeg = Self.encode(picture, width: width, height: height) else { return nil }
+        let fragment = Self.makeFragment(jpeg: jpeg, sequence: UInt32(truncatingIfNeeded: index + 1),
+                                         startSeconds: startSeconds, durationSeconds: durationSeconds)
+        lock.withLock {
+            if built.updateValue(fragment, forKey: index) == nil { builtOrder.append(index) }
+            if builtOrder.count > Self.cachedFragments { built[builtOrder.removeFirst()] = nil }
+        }
+        return IFrameFragmentBuilder.Output(initSegment: initSegment, fragment: fragment)
+    }
+
+    private static func decode(_ source: IFrameFragmentBuilder.Output) -> CGImage? {
+        let context = FrameDecodeContext(reader: DataIOReader(parts: [source.initSegment, source.fragment]),
+                                         formatHint: "mp4")
+        defer { context.close() }
+        do { try context.ensureOpen() } catch { return nil }
+        return context.decodeFrame(at: 0, mode: .thumbnail, targetWidth: defaultWidth,
+                                   maxSize: nil, isCancelled: { false })
+    }
+
+    static func encode(_ image: CGImage, width: Int, height: Int) -> Data? {
+        guard let space = CGColorSpace(name: CGColorSpace.sRGB),
+              let ctx = CGContext(data: nil, width: width, height: height, bitsPerComponent: 8,
+                                  bytesPerRow: 0, space: space,
+                                  bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue) else { return nil }
+        ctx.interpolationQuality = .high
+        ctx.draw(image, in: CGRect(x: 0, y: 0, width: width, height: height))
+        guard let scaled = ctx.makeImage() else { return nil }
+        var last: Data?
+        for quality in qualities {
+            let out = NSMutableData()
+            guard let dest = CGImageDestinationCreateWithData(out, UTType.jpeg.identifier as CFString, 1, nil)
+            else { return nil }
+            CGImageDestinationAddImage(dest, scaled, [kCGImageDestinationLossyCompressionQuality: quality] as CFDictionary)
+            guard CGImageDestinationFinalize(dest) else { return nil }
+            last = out as Data
+            if out.length <= maxFrameBytes { return last }
+        }
+        return last.flatMap { $0.count <= maxFrameBytes ? $0 : nil }
+    }
+
+    // MARK: - ISO BMFF
+
+    private static func box(_ type: String, _ body: Data) -> Data {
+        var out = Data()
+        out.append(be32(UInt32(8 + body.count)))
+        out.append(contentsOf: Array(type.utf8))
+        out.append(body)
+        return out
+    }
+    private static func fullBox(_ type: String, version: UInt8, flags: UInt32, _ body: Data) -> Data {
+        var head = be32(flags & 0x00FF_FFFF)
+        head[head.startIndex] = version
+        return box(type, cat([head, body]))
+    }
+    private static func be16(_ v: UInt16) -> Data { withUnsafeBytes(of: v.bigEndian) { Data($0) } }
+    private static func be32(_ v: UInt32) -> Data { withUnsafeBytes(of: v.bigEndian) { Data($0) } }
+    private static func be64(_ v: UInt64) -> Data { withUnsafeBytes(of: v.bigEndian) { Data($0) } }
+    private static func zeros(_ n: Int) -> Data { Data(count: n) }
+    private static let unityMatrix: Data = [0x0001_0000, 0, 0, 0, 0x0001_0000, 0, 0, 0, 0x4000_0000]
+        .reduce(into: Data()) { $0.append(be32($1)) }
+
+    private static func cat(_ parts: [Data]) -> Data { parts.reduce(into: Data()) { $0.append($1) } }
+
+    /// The layout of Apple's `adv_dv_atmos` motion JPEG tier: an `mjpg` sample entry with BT.709 `colr`.
+    static func makeInit(width: Int, height: Int) -> Data {
+        let ftyp = box("ftyp", cat([Data("iso6".utf8), be32(0), Data("iso6mp41".utf8)]))
+        let mvhd = fullBox("mvhd", version: 0, flags: 0, cat([
+            be32(0), be32(0), be32(timescale), be32(0), be32(0x0001_0000), be16(0x0100),
+            zeros(10), unityMatrix, zeros(24), be32(2)]))
+        let tkhd = fullBox("tkhd", version: 0, flags: 3, cat([
+            be32(0), be32(0), be32(1), be32(0), be32(0), zeros(8), zeros(8), unityMatrix,
+            be32(UInt32(width) << 16), be32(UInt32(height) << 16)]))
+        let mdhd = fullBox("mdhd", version: 0, flags: 0, cat([
+            be32(0), be32(0), be32(timescale), be32(0), be16(0x55C4), be16(0)]))
+        let hdlr = fullBox("hdlr", version: 0, flags: 0, cat([
+            be32(0), Data("vide".utf8), zeros(12), Data("VideoHandler\0".utf8)]))
+        let vmhd = fullBox("vmhd", version: 0, flags: 1, zeros(8))
+        let dref = fullBox("dref", version: 0, flags: 0, cat([be32(1), fullBox("url ", version: 0, flags: 1, Data())]))
+        let dinf = box("dinf", dref)
+        let colr = box("colr", cat([Data("nclx".utf8), be16(1), be16(1), be16(1), Data([0x00])]))
+        let pasp = box("pasp", cat([be32(1), be32(1)]))
+        let entry = box("mjpg", cat([
+            zeros(6), be16(1), zeros(16), be16(UInt16(width)), be16(UInt16(height)),
+            be32(0x0048_0000), be32(0x0048_0000), be32(0), be16(1), zeros(32),
+            be16(0x0018), be16(0xFFFF), colr, pasp]))
+        let stsd = fullBox("stsd", version: 0, flags: 0, cat([be32(1), entry]))
+        let stts = fullBox("stts", version: 0, flags: 0, be32(0))
+        let stsc = fullBox("stsc", version: 0, flags: 0, be32(0))
+        let stsz = fullBox("stsz", version: 0, flags: 0, cat([be32(0), be32(0)]))
+        let stco = fullBox("stco", version: 0, flags: 0, be32(0))
+        let stbl = box("stbl", cat([stsd, stts, stsc, stsz, stco]))
+        let minf = box("minf", cat([vmhd, dinf, stbl]))
+        let trak = box("trak", cat([tkhd, box("mdia", cat([mdhd, hdlr, minf]))]))
+        let trex = fullBox("trex", version: 0, flags: 0, cat([be32(1), be32(1), be32(0), be32(0), be32(0)]))
+        return cat([ftyp, box("moov", cat([mvhd, trak, box("mvex", trex)]))])
+    }
+
+    static func makeFragment(jpeg: Data, sequence: UInt32, startSeconds: Double,
+                             durationSeconds: Double) -> Data {
+        let start = UInt64(max(0, (startSeconds * Double(timescale)).rounded()))
+        let duration = UInt32(max(1, (durationSeconds * Double(timescale)).rounded()))
+        // default-base-is-moof, default duration, default size; trun carries only the data offset.
+        let tfhd = fullBox("tfhd", version: 0, flags: 0x02_0018,
+                           cat([be32(1), be32(duration), be32(UInt32(jpeg.count))]))
+        let tfdt = fullBox("tfdt", version: 1, flags: 0, be64(start))
+        let mfhd = fullBox("mfhd", version: 0, flags: 0, be32(sequence))
+        func moof(dataOffset: UInt32) -> Data {
+            let trun = fullBox("trun", version: 0, flags: 0x00_0001, cat([be32(1), be32(dataOffset)]))
+            return box("moof", cat([mfhd, box("traf", cat([tfhd, tfdt, trun]))]))
+        }
+        let sized = moof(dataOffset: 0)
+        return cat([moof(dataOffset: UInt32(sized.count + 8)), box("mdat", jpeg)])
+    }
+}
diff --git a/Sources/AetherEngine/Video/IFrameRendition.swift b/Sources/AetherEngine/Video/IFrameRendition.swift
index ab38e9819..9992f6290 100644
--- a/Sources/AetherEngine/Video/IFrameRendition.swift
+++ b/Sources/AetherEngine/Video/IFrameRendition.swift
@@ -3,10 +3,26 @@ import Foundation
 
 /// What the segment provider needs from an I-frame rendition (AE#682).
 protocol IFrameSegmentSource: AnyObject, Sendable {
+    var format: IFrameRenditionFormat { get }
     func initSegment() -> Data?
     func fragment(at index: Int) -> Data?
 }
 
+/// What the I-frame rendition carries, and so what the master declares for it.
+enum IFrameRenditionFormat: Equatable, Sendable {
+    /// The source's own keyframes; the master repeats the variant's codec, range and size.
+    case keyframes
+    /// One SDR Motion JPEG still per keyframe (`IFrameJPEGBuilder`), for HDR and Dolby Vision sources.
+    case jpeg(width: Int, height: Int, bandwidth: Int)
+
+    var logName: String {
+        switch self {
+        case .keyframes: return "keyframes"
+        case .jpeg: return "jpeg"
+        }
+    }
+}
+
 /// 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 {
@@ -16,6 +32,7 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
         let durationSeconds: Double
     }
 
+    let format: IFrameRenditionFormat
     private let entries: [Entry]
     private let cache: IFramePayloadCache
     private let readPayload: (Entry) -> Data?
@@ -33,12 +50,14 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
 
     init(entries: [Entry],
          cache: IFramePayloadCache,
+         format: IFrameRenditionFormat = .keyframes,
          readPayload: @escaping (Entry) -> Data?,
          buildFragment: @escaping (Data, Int, Entry) -> IFrameFragmentBuilder.Output?,
          waitForLink: @escaping (_ shouldStop: () -> Bool) -> Void = { _ in },
          sourceReadsAllowed: @escaping () -> Bool = { true },
          interruptReads: @escaping () -> Void = {},
          closeReader: @escaping () -> Void = {}) {
+        self.format = format
         self.entries = entries
         self.cache = cache
         self.readPayload = readPayload
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index baa2c3c24..a51eabead 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -2975,6 +2975,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     }
 
     var iFrameRenditionServed: Bool { iFrameSource != nil }
+    var iFrameRenditionFormat: IFrameRenditionFormat? { iFrameSource?.format }
     func iFrameInitSegment() -> Data? { iFrameSource?.initSegment() }
     func iFrameSegment(at index: Int) -> Data? { iFrameSource?.fragment(at: index) }
 
diff --git a/Tests/AetherEngineTests/IFrameJPEGBuilderTests.swift b/Tests/AetherEngineTests/IFrameJPEGBuilderTests.swift
new file mode 100644
index 000000000..cfe5203ac
--- /dev/null
+++ b/Tests/AetherEngineTests/IFrameJPEGBuilderTests.swift
@@ -0,0 +1,125 @@
+// Tests/AetherEngineTests/IFrameJPEGBuilderTests.swift
+import Foundation
+import Testing
+import ImageIO
+@testable import AetherEngine
+
+private func fixtureExists(_ name: String) -> Bool {
+    FileManager.default.fileExists(atPath: URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+        .appendingPathComponent("Fixtures/\(name)").path)
+}
+
+@Suite("I-frame JPEG builder", .serialized)
+struct IFrameJPEGBuilderTests {
+    private func stagingDir() throws -> URL {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("iframe-jpeg-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    private func sampleEntryType(_ initSegment: Data) -> String? {
+        guard let stsd = IFrameTestBoxes.find(["moov", "trak", "mdia", "minf", "stbl", "stsd"], in: initSegment)
+        else { return nil }
+        let at = stsd.lowerBound + 12
+        return String(bytes: initSegment[at..<(at + 4)], encoding: .isoLatin1)
+    }
+
+    private func jpegPayload(_ fragment: Data) -> Data? {
+        guard let mdat = IFrameTestBoxes.find(["mdat"], in: fragment) else { return nil }
+        return fragment.subdata(in: mdat)
+    }
+
+    @Test("the still keeps the display aspect, at most the requested width, even on both axes")
+    func size() {
+        #expect(IFrameJPEGBuilder.size(codedWidth: 3840, codedHeight: 2160, sarNum: 1, sarDen: 1)! == (640, 360))
+        #expect(IFrameJPEGBuilder.size(codedWidth: 3840, codedHeight: 1714, sarNum: 0, sarDen: 0)! == (640, 286))
+        // Anamorphic DVD: 720x576 at 64:45 displays 1024 wide.
+        #expect(IFrameJPEGBuilder.size(codedWidth: 720, codedHeight: 576, sarNum: 64, sarDen: 45)! == (640, 360))
+        #expect(IFrameJPEGBuilder.size(codedWidth: 320, codedHeight: 180, sarNum: 1, sarDen: 1)! == (320, 180))
+        #expect(IFrameJPEGBuilder.size(codedWidth: 0, codedHeight: 180, sarNum: 1, sarDen: 1) == nil)
+    }
+
+    @Test("the declared bandwidth covers the largest still over the shortest segment")
+    func bandwidth() {
+        let declared = IFrameJPEGBuilder.bandwidth(shortestSegmentSeconds: 2.0)
+        #expect(Double(declared) >= Double(IFrameJPEGBuilder.maxFrameBytes) * 8 / 2.0)
+        #expect(IFrameJPEGBuilder.bandwidth(shortestSegmentSeconds: 0) > declared)
+    }
+
+    @Test("the init carries one mjpg track of the declared size")
+    func initSegment() {
+        let initSegment = IFrameJPEGBuilder.makeInit(width: 640, height: 286)
+        #expect(IFrameTestBoxes.topLevelTypes(initSegment) == ["ftyp", "moov"])
+        #expect(sampleEntryType(initSegment) == "mjpg")
+        #expect(IFrameTestBoxes.timescale(initSegment: initSegment) == 90_000)
+        let tkhd = IFrameTestBoxes.find(["moov", "trak", "tkhd"], in: initSegment)!
+        #expect(IFrameTestBoxes.u32(initSegment, tkhd.upperBound - 8) == 640 << 16)
+        #expect(IFrameTestBoxes.u32(initSegment, tkhd.upperBound - 4) == 286 << 16)
+    }
+
+    @Test("a fragment holds one sample at the plan time, its data offset on the JPEG")
+    func fragment() {
+        let jpeg = Data([0xFF, 0xD8, 0x01, 0x02, 0xFF, 0xD9])
+        let fragment = IFrameJPEGBuilder.makeFragment(jpeg: jpeg, sequence: 8, startSeconds: 28.5,
+                                                      durationSeconds: 4)
+        #expect(IFrameTestBoxes.topLevelTypes(fragment) == ["moof", "mdat"])
+        #expect(IFrameTestBoxes.sampleCount(fragment: fragment) == 1)
+        #expect(IFrameTestBoxes.baseDecodeTime(fragment: fragment) == 2_565_000)
+        let trun = IFrameTestBoxes.find(["moof", "traf", "trun"], in: fragment)!
+        let offset = Int(IFrameTestBoxes.u32(fragment, trun.lowerBound + 8))
+        #expect(fragment.subdata(in: offset..<(offset + jpeg.count)) == jpeg)
+    }
+
+    @Test("an HDR10 keyframe becomes an SDR JPEG of the declared size",
+          .enabled(if: fixtureExists("hdr10-hevc.mp4")))
+    func hdrKeyframe() throws {
+        let fx = try IFrameFixture("hdr10-hevc.mp4", codecTag: "hvc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameJPEGBuilder(keyframe: IFrameFragmentBuilder(video: fx.config, stagingDir: dir),
+                                        width: 640, height: 360)
+
+        let out = try #require(builder.build(payload: fx.keyframe, index: 3, startSeconds: 12,
+                                             durationSeconds: 4))
+        #expect(out.initSegment == builder.initSegment)
+        #expect(IFrameTestBoxes.baseDecodeTime(fragment: out.fragment) == 1_080_000)
+        let jpeg = try #require(jpegPayload(out.fragment))
+        #expect(jpeg.prefix(2) == Data([0xFF, 0xD8]))
+        #expect(jpeg.count <= IFrameJPEGBuilder.maxFrameBytes)
+        let source = try #require(CGImageSourceCreateWithData(jpeg as CFData, nil))
+        let image = try #require(CGImageSourceCreateImageAtIndex(source, 0, nil))
+        #expect(image.width == 640 && image.height == 360)
+        #expect(try FileManager.default.contentsOfDirectory(atPath: dir.path).isEmpty)
+    }
+
+    @Test("a still asked for again is answered from memory without the payload",
+          .enabled(if: fixtureExists("hdr10-hevc.mp4")))
+    func repeatsFromMemory() throws {
+        let fx = try IFrameFixture("hdr10-hevc.mp4", codecTag: "hvc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameJPEGBuilder(keyframe: IFrameFragmentBuilder(video: fx.config, stagingDir: dir),
+                                        width: 640, height: 360)
+        let first = try #require(builder.build(payload: fx.keyframe, index: 5, startSeconds: 20,
+                                               durationSeconds: 4))
+        let again = try #require(builder.build(payload: Data([0, 0, 0, 1]), index: 5, startSeconds: 20,
+                                               durationSeconds: 4))
+        #expect(again.fragment == first.fragment)
+    }
+
+    @Test("a payload that does not decode builds nothing", .enabled(if: fixtureExists("hdr10-hevc.mp4")))
+    func undecodable() throws {
+        let fx = try IFrameFixture("hdr10-hevc.mp4", codecTag: "hvc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameJPEGBuilder(keyframe: IFrameFragmentBuilder(video: fx.config, stagingDir: dir),
+                                        width: 640, height: 360)
+        #expect(builder.build(payload: Data([0, 0, 0, 4, 1, 2, 3, 4]), index: 0, startSeconds: 0,
+                              durationSeconds: 4) == nil)
+    }
+}
diff --git a/Tests/AetherEngineTests/IFramePlaylistTextTests.swift b/Tests/AetherEngineTests/IFramePlaylistTextTests.swift
index 27d320a1d..364982ff4 100644
--- a/Tests/AetherEngineTests/IFramePlaylistTextTests.swift
+++ b/Tests/AetherEngineTests/IFramePlaylistTextTests.swift
@@ -7,8 +7,11 @@ 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) {
+    let format: IFrameRenditionFormat?
+    init(served: Bool, durations: [Double] = [4.0, 4.0, 2.5], supplemental: String? = nil,
+         format: IFrameRenditionFormat? = nil) {
         self.served = served; self.durations = durations; self.supplemental = supplemental
+        self.format = format
     }
     func initSegment() -> Data? { Data([0x00]) }
     func mediaSegment(at index: Int) -> Data? { Data([0x00]) }
@@ -22,6 +25,7 @@ private final class IFrameMockProvider: HLSSegmentProvider, @unchecked Sendable
     var masterBandwidth: Int? { 12_000_000 }
     var masterFrameRate: Double? { 23.976 }
     var iFrameRenditionServed: Bool { served }
+    var iFrameRenditionFormat: IFrameRenditionFormat? { format }
 }
 
 struct IFramePlaylistTextTests {
@@ -37,6 +41,17 @@ struct IFramePlaylistTextTests {
         #expect(lines.firstIndex(of: tag[0])! > variantURI)
     }
 
+    @Test("a JPEG rendition is declared as SDR motion JPEG, whatever the variant carries")
+    func masterLineForJPEG() {
+        let p = IFrameMockProvider(served: true, supplemental: "dvh1.08.06/db1p",
+                                   format: .jpeg(width: 640, height: 360, bandwidth: 790_000))
+        let tag = HLSLocalServer.buildMasterPlaylistText(provider: p)
+            .split(separator: "\n").map(String.init)
+            .filter { $0.hasPrefix("#EXT-X-I-FRAME-STREAM-INF:") }
+        #expect(tag == ["#EXT-X-I-FRAME-STREAM-INF:BANDWIDTH=790000,CODECS=\"mjpg\","
+                        + "RESOLUTION=640x360,VIDEO-RANGE=SDR,URI=\"iframe.m3u8\""])
+    }
+
     @Test("master is untouched when the rendition is not served")
     func masterWithout() {
         let m = HLSLocalServer.buildMasterPlaylistText(provider: IFrameMockProvider(served: false))
diff --git a/Tests/AetherEngineTests/IFrameSessionTests.swift b/Tests/AetherEngineTests/IFrameSessionTests.swift
index 14d939f91..c37b98dfe 100644
--- a/Tests/AetherEngineTests/IFrameSessionTests.swift
+++ b/Tests/AetherEngineTests/IFrameSessionTests.swift
@@ -66,6 +66,7 @@ struct IFrameSessionTests {
         #expect(playbackURL.lastPathComponent == "master.m3u8")
         let prov = try #require(engine.provider)
         #expect(prov.iFrameRenditionServed)
+        #expect(prov.iFrameRenditionFormat == .keyframes)
         try #require(prov.segmentCount >= 2)
 
         let initSegment = try #require(prov.iFrameInitSegment())
@@ -81,6 +82,35 @@ struct IFrameSessionTests {
         #expect(prov.iFrameSegment(at: prov.segmentCount) == nil)
     }
 
+    private static let dolbyVisionFixture = "user/Patterns_Of_Nature_DoVi_24_P5_UHD_HEVC-10mbps_DD+JOC-768kbps_iOS.mp4"
+
+    @Test("a Dolby Vision session serves SDR JPEG stills on the plan's timeline",
+          .enabled(if: fixtureExists(dolbyVisionFixture)), .timeLimit(.minutes(2)))
+    func dolbyVisionServesJPEG() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.dolbyVisionFixture), dvModeAvailable: true)
+        engine.requestIFramePlaylist()
+        _ = try engine.start()
+        defer { engine.stop() }
+        try #require(engine.iFrameRenditionVerdict == .served)
+        let prov = try #require(engine.provider)
+        guard case .jpeg(let width, let height, _) = prov.iFrameRenditionFormat else {
+            Issue.record("expected a JPEG rendition, got \(String(describing: prov.iFrameRenditionFormat))")
+            return
+        }
+        #expect(width == 640 && height == 360)
+        let master = HLSLocalServer.buildMasterPlaylistText(provider: prov)
+        #expect(master.contains("CODECS=\"mjpg\",RESOLUTION=640x360,VIDEO-RANGE=SDR"))
+        let initSegment = try #require(prov.iFrameInitSegment())
+        let timescale = Double(try #require(IFrameTestBoxes.timescale(initSegment: initSegment)))
+        for index in [prov.segmentCount - 1, 2] {
+            let fragment = try #require(prov.iFrameSegment(at: index))
+            let tfdt = Double(try #require(IFrameTestBoxes.baseDecodeTime(fragment: fragment)))
+            #expect(abs(tfdt / timescale - engine.segmentPlan[index].startSeconds) < 0.002)
+            let mdat = try #require(IFrameTestBoxes.find(["mdat"], in: fragment))
+            #expect(fragment.subdata(in: mdat).prefix(2) == Data([0xFF, 0xD8]))
+        }
+    }
+
     @Test("the loopback server answers the three new paths",
           .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
     func routes() throws {
diff --git a/docs/api.md b/docs/api.md
index 6503bc7d2..d9c152129 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1193,7 +1193,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`. |
+| `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 still per segment: an SDR source gets its own keyframes at full resolution, an HDR10, HLG or Dolby Vision source gets tone-mapped 640-pixel Motion JPEG stills (AVKit shows no scrub thumbnail from a PQ or Dolby Vision keyframe). 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. |
diff --git a/docs/cli.md b/docs/cli.md
index 8dbaa2baa..d19605c81 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -65,7 +65,7 @@ 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.
+`--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 still per segment: the source's keyframe for SDR, a tone-mapped Motion JPEG (`CODECS="mjpg"`) for HDR and Dolby Vision. The log line `[HLSVideoEngine] i-frame rendition: served segments=<n> format=keyframes|jpeg` 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.
 

From e4f48305f80e4ed924758465af77b616375caa64 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 19:46:24 +0000
Subject: [PATCH 040/132] fix(dovi): report a dual-layer session loss to the
 host once, not once per layer

A screen lock invalidates both sessions and each sub-decoder reported it,
so the host rebuilt both sessions twice and repositioned twice for one
event (seen with aetherctl bgaudio --lose-session --fel). The sub-decoders
now report through the dual-layer decoder, which passes the first loss on
and the rest only after rebuildSession() has replaced both sessions.
---
 .../Decoder/DualLayerVideoDecoder.swift       | 33 ++++++++++++++++---
 .../DualLayerVideoDecoderTests.swift          |  7 +++-
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
index 9ff472c4c..53f1157f0 100644
--- a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -179,8 +179,9 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     }
     private var _skipUntilPTS: CMTime?
 
-    /// AE#739: called when the system invalidates either layer's session. Handed to both sub-decoders
-    /// (outside `lock`, as `skipUntilPTS` is), and to the enhancement decoder when it opens.
+    /// AE#739: called when the system invalidates either layer's session. Both sub-decoders report
+    /// through `reportSessionLost()` (installed outside `lock`, as `skipUntilPTS` is), the enhancement
+    /// decoder from when it opens.
     var onSessionLost: (@Sendable () -> Void)? {
         get { lock.lock(); defer { lock.unlock() }; return _onSessionLost }
         set {
@@ -189,11 +190,29 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             let primary = primaryDecoder
             let enhancement = enhancementDecoder
             lock.unlock()
-            (primary as? HardwareVideoDecoder)?.onSessionLost = newValue
-            (enhancement as? HardwareVideoDecoder)?.onSessionLost = newValue
+            (primary as? HardwareVideoDecoder)?.onSessionLost = subDecoderLossHandler(newValue)
+            (enhancement as? HardwareVideoDecoder)?.onSessionLost = subDecoderLossHandler(newValue)
         }
     }
     private var _onSessionLost: (@Sendable () -> Void)?
+    /// Guarded by `lock`. A screen lock invalidates both sessions and each sub-decoder reports it;
+    /// the owner hears one loss until `rebuildSession()` has replaced both, not one per layer
+    /// (which rebuilt both sessions twice and repositioned twice).
+    private var sessionLossReported = false
+
+    private func subDecoderLossHandler(_ handler: (@Sendable () -> Void)?) -> (@Sendable () -> Void)? {
+        guard handler != nil else { return nil }
+        return { [weak self] in self?.reportSessionLost() }
+    }
+
+    private func reportSessionLost() {
+        lock.lock()
+        let first = !sessionLossReported
+        sessionLossReported = true
+        let handler = _onSessionLost
+        lock.unlock()
+        if first { handler?() }
+    }
 
     /// The primary decoder's own methods are internally synchronized
     /// (`HardwareVideoDecoder.lock` / `skipLock`); it is safe to call without holding
@@ -762,7 +781,7 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         }
         let decoder = makeEnhancementDecoder()
         decoder.skipUntilPTS = skip
-        (decoder as? HardwareVideoDecoder)?.onSessionLost = sessionLost
+        (decoder as? HardwareVideoDecoder)?.onSessionLost = subDecoderLossHandler(sessionLost)
         do {
             try decoder.open(parameterSets: [vv, ss, pp], timeBase: tb) { [weak self] elBuffer, pts, _ in
                 self?.handleEnhancementLayerFrame(elBuffer: elBuffer, pts: pts)
@@ -1472,6 +1491,10 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         // `flush()` and `close()` wait on `lifecycleLock`, so `epoch` is still this decoder's.
         primary.adoptFeedEpoch(epoch)
         enhancement?.adoptFeedEpoch(epoch)
+        // Both sessions are new (or refused, and the host owes another rebuild): the next loss is news.
+        lock.lock()
+        sessionLossReported = false
+        lock.unlock()
         return primaryRebuilt && enhancementRebuilt
     }
 
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index aecc71135..9d2d7e507 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -951,7 +951,7 @@ struct DualLayerVideoDecoderTests {
 
     // MARK: - Session loss (AE#739)
 
-    @Test("the session-loss handler reaches both layers' decoders, and clearing it clears both")
+    @Test("the session-loss handler reaches both layers' decoders, once per loss, and clearing it clears both")
     func sessionLostHandlerReachesBothLayers() {
         let primary = HardwareVideoDecoder()
         let enhancement = HardwareVideoDecoder()
@@ -963,8 +963,13 @@ struct DualLayerVideoDecoderTests {
         defer { decoder.close() }
         let calls = SessionLossCount()
         decoder.onSessionLost = { calls.bump() }
+        // A screen lock loses both sessions and each layer reports it: one recovery, not two.
         primary.onSessionLost?()
         enhancement.onSessionLost?()
+        #expect(calls.value == 1)
+        // After a rebuild (refused here: neither decoder was opened) the next loss is reported again.
+        _ = decoder.rebuildSession()
+        enhancement.onSessionLost?()
         #expect(calls.value == 2)
         decoder.onSessionLost = nil
         #expect(primary.onSessionLost == nil)

From f6fcdbd4a340c3ebddecaf6bbafd25395cbe5250 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 14 Oct 2026 22:04:44 +0200
Subject: [PATCH 041/132] fix(iframes): keep the media-playlist fallback when a
 JPEG rendition is listed (#682)

An SDR motion JPEG I-frame rendition next to an HDR variant is the one
thing AVPlayer can still play when it refuses the HDR variant (SDR panel,
dynamic range matching off). It then played the stills as the video
instead of failing into the engine's media-playlist fallback; measured on
an Apple TV 4K, where it fetched 89 iframe fragments and no init or
segment. Declaring the rendition in the variant's range avoids that but
costs the thumbnails (AVKit fetches one still and gives up).

So the server answers iframe.m3u8 for a JPEG rendition only once a media
segment was requested, which AVPlayer does before it asks for the I-frame
playlist when it plays the main variant. Without one within 3 s the
playlist is withheld, the item fails with the 404's -1100, and the host
treats that as the -11848 refusal it stands for. Verified on the device
in both panel modes: HDR plays with thumbnails, SDR without matching
falls back to the media playlist and plays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  6 +++-
 .../AetherEngine/AetherEngine+Loading.swift   |  1 +
 .../Native/MasterFallbackDecision.swift       | 20 ++++++++++-
 .../Native/NativeAVPlayerHost.swift           |  9 +++--
 .../AetherEngine/Network/HLSLocalServer.swift | 36 +++++++++++++++++++
 .../AetherEngine/Video/HLSVideoEngine.swift   |  3 ++
 .../IFrameSessionTests.swift                  | 21 +++++++++++
 .../MasterFallbackDecisionTests.swift         | 12 +++++++
 8 files changed, 104 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 834cdace5..b89228604 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,7 +29,11 @@ the public-API contract.
   (`CODECS="mjpg"`, `VIDEO-RANGE=SDR`, 640 pixels wide), whose stills come from the engine's own still
   pipeline: the tone map for PQ and HLG, the RPU reshaping for profile 5. SDR sessions keep serving their
   own keyframes. The session log names the format: `i-frame rendition: served segments=<n>
-  format=keyframes|jpeg`.
+  format=keyframes|jpeg`. Because an SDR rendition is the one thing AVPlayer can still play when it
+  refuses the HDR variant (an SDR panel without dynamic range matching), `iframe.m3u8` is answered only
+  once a media segment has been requested; otherwise it is withheld after 3 s, and the item's 404 counts
+  as the refusal it stands for, so the session still falls back to the media playlist instead of
+  playing the stills as its video.
 
 - **A 25 fps H.264 Matroska file with forward-clamped B-picture timestamps plays at a steady
   cadence.** Its packet timestamps repeated display slots and left the preceding slots empty, so
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index eaa33f1ae..e82dccc46 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1392,6 +1392,7 @@ extension AetherEngine {
         // keyed to the item that loaded it. Installed on the one funnel every attach passes through, so
         // the session's FIRST item is covered as well as every swap: both used to reconstruct the axis
         // from the cache instead, and a reconstruction is only as good as the older of its two samples.
+        host.iFramePlaylistWithheld = { [weak session] in session?.iFrameRenditionWithheld ?? false }
         host.onWillAttachItem = { [weak self] in
             // The host owns this closure, so it reaches back for the host rather than capturing it.
             guard let self, let attaching = self.nativeHost else { return }
diff --git a/Sources/AetherEngine/Native/MasterFallbackDecision.swift b/Sources/AetherEngine/Native/MasterFallbackDecision.swift
index 8716c7d6f..7db83d66c 100644
--- a/Sources/AetherEngine/Native/MasterFallbackDecision.swift
+++ b/Sources/AetherEngine/Native/MasterFallbackDecision.swift
@@ -64,7 +64,15 @@ enum MasterFallbackDecision {
 
     /// A malformed media playlist can be wrapped in the same -11848 as a display refusal.
     /// It says nothing about HDR support and must not poison the process's display decision.
-    static func isMasterRejection(_ error: NSError, mediaErrorCodes: [Int] = []) -> Bool {
+    ///
+    /// AE#682: an HDR master with an SDR motion JPEG I-frame rendition has one variant left when AVPlayer
+    /// refuses the HDR one, and AVPlayer would play the stills as the video. The server therefore
+    /// withholds the I-frame playlist until a media segment is asked for, and the refused item fails
+    /// with the 404's NSURLErrorDomain -1100. With `iFramePlaylistWithheld` that is the -11848 refusal
+    /// it stands in for.
+    static func isMasterRejection(_ error: NSError, mediaErrorCodes: [Int] = [],
+                                  iFramePlaylistWithheld: Bool = false) -> Bool {
+        if iFramePlaylistWithheld, isWithheldIFramePlaylistFailure(error) { return true }
         guard !mediaErrorCodes.contains(-12642) else { return false }
         var current: NSError? = error
         for _ in 0..<8 {
@@ -75,6 +83,16 @@ enum MasterFallbackDecision {
         return isMasterRejectionCode(error.code)
     }
 
+    static func isWithheldIFramePlaylistFailure(_ error: NSError) -> Bool {
+        error.domain == NSURLErrorDomain && error.code == NSURLErrorFileDoesNotExist
+    }
+
+    /// The code the fallback acts on: the item's own, or for a withheld I-frame playlist the display
+    /// refusal the 404 stands in for.
+    static func rejectionCode(for error: NSError, iFramePlaylistWithheld: Bool) -> Int {
+        iFramePlaylistWithheld && isWithheldIFramePlaylistFailure(error) ? -11848 : error.code
+    }
+
     /// Fall back to the media playlist only when a master-rejection failed the item, the engine was
     /// serving the master, and this session has not already fallen back (single-shot, no loop).
     static func shouldFallBackToMediaPlaylist(
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 8393b2b1d..d2e351df1 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -47,6 +47,9 @@ final class NativeAVPlayerHost {
     /// AE#495: what the AE#495 relay knows about the origin's certificate, when the item this host
     /// plays is served by one. Set by the engine at mount, read only while classifying a failure.
     var upstreamTrustRefusal: (@Sendable () -> Int?)?
+    /// AE#682: whether the session's server withheld its I-frame playlist from this item (see
+    /// `MasterFallbackDecision.isMasterRejection(_:mediaErrorCodes:iFramePlaylistWithheld:)`).
+    var iFramePlaylistWithheld: (@Sendable () -> Bool)?
     /// AE#561: what the session can still offer when AVPlayer refuses the media, answered by the
     /// engine because the host owns none of it. Set at mount, read only while classifying a failure.
     var softwarePathAvailability: (@Sendable () -> SoftwarePathEscalation.Availability?)?
@@ -1075,8 +1078,10 @@ final class NativeAVPlayerHost {
                 return
             }
             if let error = item.error as NSError?, MasterFallbackDecision.isMasterRejection(error,
-                mediaErrorCodes: item.errorLog()?.events.map(\.errorStatusCode) ?? []) {
-                let code = error.code
+                mediaErrorCodes: item.errorLog()?.events.map(\.errorStatusCode) ?? [],
+                iFramePlaylistWithheld: iFramePlaylistWithheld?() ?? false) {
+                let code = MasterFallbackDecision.rejectionCode(for: error,
+                    iFramePlaylistWithheld: iFramePlaylistWithheld?() ?? false)
                 EngineLog.emit(
                     "[NativeAVPlayerHost] #\(sessionID) startup .failed is a master rejection "
                     + "(code=\(code)); signalling engine for media fallback instead of surfacing",
diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index f52410e44..7843da75b 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -512,6 +512,36 @@ final class HLSLocalServer: @unchecked Sendable {
         return servedMediaBytes
     }
 
+    /// AE#682: how long `iframe.m3u8` waits for the first media segment request when the rendition is
+    /// SDR JPEG next to an HDR variant. AVPlayer asks for the main variant's segments before the I-frame
+    /// playlist; one that refused the HDR variant never asks for a segment, and would otherwise play the
+    /// stills as the video instead of failing into the media-playlist fallback.
+    static let iFrameMainVariantWaitSeconds: TimeInterval = 3
+
+    private var _iFrameRenditionWithheld = false
+    /// True once `iframe.m3u8` was answered 404 because no media segment was requested: AVPlayer refused
+    /// the HDR variant, and the item fails with the 404's -1100 instead of a display rejection code.
+    var iFrameRenditionWithheld: Bool {
+        stateLock.lock(); defer { stateLock.unlock() }
+        return _iFrameRenditionWithheld
+    }
+
+    /// True once a media segment was requested, waiting up to `iFrameMainVariantWaitSeconds`.
+    private func waitForMainVariant() -> Bool {
+        let deadline = Date().addingTimeInterval(Self.iFrameMainVariantWaitSeconds)
+        while true {
+            stateLock.lock()
+            let served = servedMediaBytes, stopping = shouldStop
+            stateLock.unlock()
+            if served { return true }
+            guard !stopping, Date() < deadline else {
+                stateLock.lock(); _iFrameRenditionWithheld = !stopping; stateLock.unlock()
+                return false
+            }
+            Thread.sleep(forTimeInterval: 0.025)
+        }
+    }
+
     private var loggedReducedMasterPlaylist = false
     private var loggedMediaPlaylist = false
     private var loggedRequestHeaders = false
@@ -1210,6 +1240,12 @@ final class HLSLocalServer: @unchecked Sendable {
             guard let prov = provider, prov.iFrameRenditionServed else {
                 return send404(fd: fd, path: normalizedPath, reason: "no I-frame rendition")
             }
+            if case .jpeg = prov.iFrameRenditionFormat, !waitForMainVariant() {
+                EngineLog.emit("[HLSLocalServer] i-frame rendition withheld: no media segment requested within "
+                               + "\(Self.iFrameMainVariantWaitSeconds)s, so the HDR variant was refused",
+                               category: .hlsServer)
+                return send404(fd: fd, path: normalizedPath, reason: "main variant not playing")
+            }
             let body = Self.buildIFramePlaylistText(provider: prov, subResourceBaseURL: subResourceBaseURL)
             return send200(fd: fd, path: normalizedPath, data: Data(body.utf8),
                            contentType: "application/vnd.apple.mpegurl")
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 4bbc3fd9f..0ed68ced9 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -250,6 +250,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// 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)
+    /// AE#682: the server withheld the JPEG I-frame playlist because AVPlayer never asked for a media
+    /// segment, which is how a refused HDR variant looks next to an SDR I-frame rendition.
+    var iFrameRenditionWithheld: Bool { server?.iFrameRenditionWithheld ?? false }
     private var iFrameRendition: IFrameRendition?
 
     /// Native subtitle rendition marked DEFAULT=YES in the master (Sodalite#32). Set before `start()`; the
diff --git a/Tests/AetherEngineTests/IFrameSessionTests.swift b/Tests/AetherEngineTests/IFrameSessionTests.swift
index c37b98dfe..137fea431 100644
--- a/Tests/AetherEngineTests/IFrameSessionTests.swift
+++ b/Tests/AetherEngineTests/IFrameSessionTests.swift
@@ -111,6 +111,27 @@ struct IFrameSessionTests {
         }
     }
 
+    @Test("a JPEG I-frame playlist waits for the main variant and is withheld from a player that refused it",
+          .enabled(if: fixtureExists(dolbyVisionFixture)), .timeLimit(.minutes(2)))
+    func jpegPlaylistFollowsMainVariant() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.dolbyVisionFixture), dvModeAvailable: true)
+        engine.requestIFramePlaylist()
+        let playbackURL = try engine.start()
+        defer { engine.stop() }
+        let base = playbackURL.deletingLastPathComponent()
+        let playlistURL = base.appendingPathComponent("iframe.m3u8")
+
+        let started = Date()
+        #expect(!engine.iFrameRenditionWithheld)
+        #expect((try? String(contentsOf: playlistURL, encoding: .utf8)) == nil)
+        #expect(Date().timeIntervalSince(started) >= HLSLocalServer.iFrameMainVariantWaitSeconds - 0.1)
+        #expect(engine.iFrameRenditionWithheld)
+
+        _ = try Data(contentsOf: base.appendingPathComponent("init.mp4"))
+        let playlist = try String(contentsOf: playlistURL, encoding: .utf8)
+        #expect(playlist.contains("iframe1.mp4"))
+    }
+
     @Test("the loopback server answers the three new paths",
           .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
     func routes() throws {
diff --git a/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift b/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift
index 6d347afcf..1626bc084 100644
--- a/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift
+++ b/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift
@@ -14,6 +14,18 @@ struct MasterFallbackDecisionTests {
         #expect(MasterFallbackDecision.isMasterRejection(generic))
     }
 
+    @Test("AE#682: a 404 is the HDR variant's refusal only when the server withheld the I-frame playlist")
+    func withheldIFramePlaylist() {
+        let notFound = NSError(domain: NSURLErrorDomain, code: NSURLErrorFileDoesNotExist)
+        #expect(!MasterFallbackDecision.isMasterRejection(notFound))
+        #expect(MasterFallbackDecision.isMasterRejection(notFound, iFramePlaylistWithheld: true))
+        #expect(MasterFallbackDecision.rejectionCode(for: notFound, iFramePlaylistWithheld: true) == -11848)
+        #expect(MasterFallbackDecision.rejectionCode(for: notFound, iFramePlaylistWithheld: false) == -1100)
+        let timeout = NSError(domain: NSURLErrorDomain, code: NSURLErrorTimedOut)
+        #expect(!MasterFallbackDecision.isMasterRejection(timeout, iFramePlaylistWithheld: true))
+        let display = NSError(domain: "AVFoundationErrorDomain", code: -11868)
+        #expect(MasterFallbackDecision.rejectionCode(for: display, iFramePlaylistWithheld: true) == -11868)
+    }
 
     @Test("Display-rejection codes are the two AVFoundation display-reject codes")
     func recognisesRejectionCodes() {

From 49b0d70fa217fe8a2aa0edcb33998b781f078af9 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 20:12:14 +0000
Subject: [PATCH 042/132] test(dovi): leak and memory checks that parallel
 suites cannot disturb

fel22StreamClassificationAndPacketBalance compared the process-wide
PacketBalanceTracker.alive before and after, so any suite allocating or
freeing packets in parallel failed it now and then. DEBUG builds get a
task-local PacketBalanceTracker.Scope; the test counts only its own task.

longRunStable asserted on the process's resident memory, which grew by
420 to 480 MiB in full runs while the test alone stayed flat at about
106 MiB. The bound is now asserted only on request, for a run on its own
(DV_FEL_MEMORY_SOLO=1); the frame and stall checks always run.
---
 .../Diagnostics/PacketBalanceTracker.swift    | 45 +++++++++++++++++++
 .../DoviFelRealFileTests.swift                |  7 ++-
 .../DualLayerVideoDecoderTests.swift          | 25 ++++++-----
 3 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift b/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift
index aae511efa..f1fbff4f9 100644
--- a/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift
+++ b/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift
@@ -14,12 +14,18 @@ enum PacketBalanceTracker {
         lock.lock()
         _allocs &+= 1
         lock.unlock()
+        #if DEBUG
+        scope?.recordAlloc()
+        #endif
     }
 
     static func recordFree() {
         lock.lock()
         _frees &+= 1
         lock.unlock()
+        #if DEBUG
+        scope?.recordFree()
+        #endif
     }
 
     static var alive: Int {
@@ -33,6 +39,45 @@ enum PacketBalanceTracker {
         defer { lock.unlock() }
         return _allocs
     }
+
+    #if DEBUG
+    /// The allocs and frees made by one task and the synchronous calls it makes. `alive` is
+    /// process-wide, so a test that compares it before and after reads every other test running in
+    /// parallel; a leak check scoped to the test's own task does not.
+    final class Scope: @unchecked Sendable {
+        private let lock = NSLock()
+        private var allocs = 0
+        private var frees = 0
+
+        var alive: Int {
+            lock.lock()
+            defer { lock.unlock() }
+            return allocs - frees
+        }
+
+        fileprivate func recordAlloc() {
+            lock.lock()
+            allocs &+= 1
+            lock.unlock()
+        }
+
+        fileprivate func recordFree() {
+            lock.lock()
+            frees &+= 1
+            lock.unlock()
+        }
+    }
+
+    @TaskLocal static var scope: Scope?
+
+    /// Runs `body` with a fresh `Scope` and returns it. Work `body` hands to another queue or thread
+    /// is not counted.
+    static func measure(_ body: () throws -> Void) rethrows -> Scope {
+        let scope = Scope()
+        try $scope.withValue(scope) { try body() }
+        return scope
+    }
+    #endif
 }
 
 /// Drop-in for av_packet_alloc() that records the alloc in PacketBalanceTracker.
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
index b1f18cf58..ea1b7353d 100644
--- a/Tests/AetherEngineTests/DoviFelRealFileTests.swift
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -431,8 +431,11 @@ struct DoviFelRealFileTests {
         print("[longRun] packets=\(total) frames=\(s.sink.pts.count) rss MiB by 200-packet step: \(samples)")
         #expect(total > 300)
         #expect(s.sink.pts.count >= Int(Double(total) * 0.95))
-        // Steady state: the last third may not sit more than 400 MiB above the first third.
-        if samples.count >= 6 {
+        // Steady state: the last third may not sit more than 400 MiB above the first third. Resident
+        // memory is the whole process's, so tests running in parallel move it too (it grew by 420 to 480 MiB
+        // in full runs, while this test alone stayed flat at about 106 MiB). Asserted only when asked for
+        // a run on its own: DV_FEL_MEMORY_SOLO=1 swift test --filter longRunStable
+        if ProcessInfo.processInfo.environment["DV_FEL_MEMORY_SOLO"] != nil, samples.count >= 6 {
             let early = samples[1..<(samples.count / 3 + 1)].max() ?? 0
             let late = samples[(samples.count * 2 / 3)...].max() ?? 0
             #expect(late - early < 400, "resident memory grew \(early) -> \(late) MiB")
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 2cce66221..80c251df8 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -2552,8 +2552,6 @@ struct DualLayerVideoDecoderTests {
 
     @Test("DualLayerVideoDecoder reports streamClassification accurately and balances packets")
     func fel22StreamClassificationAndPacketBalance() throws {
-        let aliveBefore = PacketBalanceTracker.alive
-
         let primary = CountingFakeDecoder()
         let enhancement = CountingFakeDecoder()
         let decoder = DualLayerVideoDecoder(
@@ -2572,20 +2570,27 @@ struct DualLayerVideoDecoderTests {
         let bl = Self.hevcNAL(type: 1, payload: [0x11, 0x22, 0x33, 0x44])
         let melRpu = Self.makeMelRpuBytes()
 
-        guard let melPkt = Self.makeAvccPacket([vps, sps, pps, bl, melRpu], pts: 1000) else {
+        // Counted on this test's task only: the process-wide `alive` also moves with every other
+        // suite running in parallel, which failed this check now and then in a full run.
+        var made = true
+        let packets = PacketBalanceTracker.measure {
+            guard let melPkt = Self.makeAvccPacket([vps, sps, pps, bl, melRpu], pts: 1000) else {
+                made = false
+                return
+            }
+            decoder.decode(packet: melPkt)
+            var optMel: UnsafeMutablePointer<AVPacket>? = melPkt
+            trackedPacketFree(&optMel)
+        }
+        guard made else {
             Issue.record("Failed to make MEL packet")
             return
         }
 
-        decoder.decode(packet: melPkt)
-
-        var optMel: UnsafeMutablePointer<AVPacket>? = melPkt
-        trackedPacketFree(&optMel)
-
         // Classification must be MEL, not FEL
         #expect(decoder.streamClassification == .mel)
 
-        // PacketBalanceTracker must return to baseline
-        #expect(PacketBalanceTracker.alive == aliveBefore)
+        // Every packet this test and the decoder allocated was freed
+        #expect(packets.alive == 0)
     }
 }

From e945d786cfe1b57e99e1fe84a18bf101c0f9ec96 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 20:14:34 +0000
Subject: [PATCH 043/132] fix(dovi): cap the reshaping prediction at full scale
 before the residual

The composer floored the prediction at 0 before adding the enhancement-layer
residual but did not cap it at the top. A prediction above full scale (seen
in chroma MMR on saturated colours) plus a negative residual then stayed at
vdr_max instead of landing below it. DoViBaker caps the polynomial and the
MMR result at full scale before the residual as well.

Against DoViBaker's integer pipeline on a real FEL RPU (fel_orig.bin from
dovi_tool's test assets, 200,000 random base and enhancement samples), Cr
differed by up to 199 12-bit codes on 1.2% of samples before this change and
by at most 1 code after it, the same as Y and Cb.

dovi_denormalize now clamps to [0, vdr_max]. Test: a prediction of 1.1 with a
-100 EL code residual lands on 3996, through the luma table and through
chroma MMR.
---
 .../Video/Metal/DoviShaderSource.swift        | 19 ++++++-------
 .../DoviGpuEdgeCaseTests.swift                | 27 +++++++++++++++++++
 2 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
index ededc06ef..7b0aa2afe 100644
--- a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
@@ -215,8 +215,8 @@ static inline int dovi_select_piece(constant struct DoviPolynomialParams &curve,
 
 // Polynomial piece, evaluated on the input normalised by `bl_max`. Callers pass
 // bl_max + 1 (= 2^bl_bit_depth), the same normaliser as the y/u/v inputs.
-// Returns the prediction in normalised units; dovi_denormalize floors it at 0 before the residual is
-// added (DoViBaker clamps `vv`/`rr` at 0 there), and the sum is clamped again afterwards.
+// Returns the prediction in normalised units; dovi_denormalize clamps it to [0, vdr_max] before the
+// residual is added (DoViBaker clamps `vv`/`rr` to [0, 0xffff] there), and the sum is clamped again afterwards.
 static inline float dovi_eval_poly(
     constant struct DoviPolynomialParams &curve,
     int piece,
@@ -321,10 +321,11 @@ static inline float dovi_eval_curve(
 // Normalised prediction back into VDR code units. Callers pass bl_max + 1, so the
 // scale is (bl_max + 1) * vdr_scale = 2^vdr_bit_depth rather than vdr_max, which is
 // what makes an identity curve bit-exact end to end.
-static inline int dovi_denormalize(float pred_norm, uint bl_max, uint vdr_scale) {
-    // The prediction is floored at 0 before the residual is added, as DoViBaker does for both the
-    // polynomial and the MMR result, so a negative prediction cannot be pulled back up by the residual.
-    return max(int(rint(pred_norm * float(bl_max) * float(vdr_scale))), 0);
+static inline int dovi_denormalize(float pred_norm, uint bl_max, uint vdr_scale, uint vdr_max) {
+    // The prediction is clamped to the VDR range before the residual is added, as DoViBaker does for both
+    // the polynomial and the MMR result, so a prediction outside it cannot be pulled back in by the
+    // residual: a negative one starts from 0, one above full scale from vdr_max.
+    return clamp(int(rint(pred_norm * float(bl_max) * float(vdr_scale))), 0, int(vdr_max));
 }
 
 /* ============================================================================
@@ -468,7 +469,7 @@ kernel void dovi_compose_luma(
                                params.poly_y, params.poly_cb, params.poly_cr, bl_y,
                                y_norm, u_norm, v_norm, params.bl_max + 1u);
     }
-    int vdr_y = dovi_denormalize(pred, params.bl_max + 1u, params.vdr_scale);
+    int vdr_y = dovi_denormalize(pred, params.bl_max + 1u, params.vdr_scale, params.vdr_max);
 
     if ((params.flags & DOVI_FLAG_DISABLE_RESIDUAL) == 0u &&
         params.nlq_y.nlq_method == DOVI_NLQ_METHOD_LINEAR &&
@@ -546,8 +547,8 @@ kernel void dovi_compose_chroma(
                                     params.poly_y, params.poly_cb, params.poly_cr, bl_cr,
                                     y_norm, u_norm, v_norm, params.bl_max + 1u);
 
-    int vdr_cb = dovi_denormalize(pred_cb, params.bl_max + 1u, params.vdr_scale);
-    int vdr_cr = dovi_denormalize(pred_cr, params.bl_max + 1u, params.vdr_scale);
+    int vdr_cb = dovi_denormalize(pred_cb, params.bl_max + 1u, params.vdr_scale, params.vdr_max);
+    int vdr_cr = dovi_denormalize(pred_cr, params.bl_max + 1u, params.vdr_scale, params.vdr_max);
 
     if ((params.flags & DOVI_FLAG_DISABLE_RESIDUAL) == 0u) {
         bool cb_active = (params.nlq_cb.nlq_method == DOVI_NLQ_METHOD_LINEAR && params.nlq_cb.nlq_scale != 0);
diff --git a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
index 30bbc0334..e244f73b9 100644
--- a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
@@ -489,4 +489,31 @@ extension DoviGpuEdgeCaseTests {
         let c = try Self.composeConstant(composer, bl: (512, 512, 512), el: (512, 612, 512), params: p)
         #expect(Set(DoviTestSupport.rawVDR(c)[1]) == [99])
     }
+
+    /// DoViBaker also caps the prediction at full scale (`v > 0xffff ? 0xffff : v`) before the residual, so a
+    /// prediction above it is not pulled back down from there: 4095 - 99, not 4506 - 99 -> clamp 4095.
+    @Test("a prediction above full scale is capped at vdr_max before the residual is added")
+    func overRangePredictionCappedBeforeResidual() throws {
+        let composer = try #require(DoviFelComposer())
+        var high = DoviPolynomialParams()
+        high.numPivots = 2; high.pivots[0] = 0; high.pivots[1] = 1023
+        high.method[0] = DoviMapping.polynomial.rawValue
+        high.order[0] = 0; high.coefShift[0] = 23
+        high.coef[0] = [Int32(1.1 * 8388608.0), 0, 0]   // 1.1 * 4096 = 4506 VDR codes
+
+        var p = Self.params()
+        p.ditherMode = .debugRawVDR
+        p.polyY = high
+        let out = try Self.composeConstant(composer, bl: (512, 512, 512), el: (412, 512, 512), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [3996])   // -100 EL codes -> -99 residual
+
+        // The same through MMR (chroma): constant 1.1, residual -99.
+        var m = DoviMmrParams(); m.coefShift = 23; m.constant[0] = Int32(1.1 * 8388608.0)
+        var mp = DoviPolynomialParams()
+        mp.numPivots = 2; mp.pivots[1] = 1023
+        mp.method[0] = DoviMapping.mmr.rawValue; mp.order[0] = 1; mp.coefShift[0] = 23
+        p.polyCr = mp; p.mmrCr = m
+        let c = try Self.composeConstant(composer, bl: (512, 512, 512), el: (512, 512, 412), params: p)
+        #expect(Set(DoviTestSupport.rawVDR(c)[2]) == [3996])
+    }
 }

From 923819f47c68b339a43f4d31d99c52e171151bb0 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Wed, 14 Oct 2026 20:51:48 +0000
Subject: [PATCH 044/132] test(dovi): N3 expects the prediction capped before
 the residual, as DoViBaker does

N3 asserted that a prediction above the VDR range keeps its overshoot until
the residual is added (3979). DoViBaker caps the mapping result at 0xffff
first (polynompialMapping and mmrMapping return uint16_t), which for N3's
inputs is (65535 - 3192 + 8) >> 4 = 3896, the value the previous commit
produces. The test's own header names DoViBaker as the oracle.
---
 Tests/AetherEngineTests/DoviFelMathTests.swift | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Tests/AetherEngineTests/DoviFelMathTests.swift b/Tests/AetherEngineTests/DoviFelMathTests.swift
index bffd2ed3a..9878d668e 100644
--- a/Tests/AetherEngineTests/DoviFelMathTests.swift
+++ b/Tests/AetherEngineTests/DoviFelMathTests.swift
@@ -164,18 +164,19 @@ struct DoviFelMathTests {
         #expect(worst <= 1.0, "worst deviation \(worst) VDR codes")
     }
 
-    // MARK: - N3: prediction overshoot survives until the residual is added
+    // MARK: - N3: prediction overshoot is capped before the residual is added
 
-    @Test("N3: a prediction above the VDR range keeps its overshoot until the residual is added")
-    func predictionOvershootKeptBeforeResidual() throws {
+    @Test("N3: a prediction above the VDR range is capped at vdr_max before the residual is added")
+    func predictionOvershootCappedBeforeResidual() throws {
         let composer = try #require(DoviFelComposer())
         // Prediction 1.02 -> 4178 12-bit codes (above vdr_max 4095); EL 312 -> r = -200 -> (399 * 2048) >> 12 = 199 -> -199.
-        // Clamping the prediction first would give 4095 - 199 = 3896; adding first gives 4178 - 199 = 3979.
+        // DoViBaker caps the mapping result at 0xffff before the residual (`polynompialMapping` returns uint16_t):
+        // (65535 - 3192 + 8) >> 4 = 3896, which is 4095 - 199. Adding first would give 4178 - 199 = 3979.
         var p = Self.rawParams(residual: true)
         p.polyY = Self.polynomial(1.02, order: 0)
         p.nlqY = DoviGpuEdgeCaseTests.nlq(vdrInMax: 4095)
         let out = try DoviGpuEdgeCaseTests.composeConstant(composer, bl: (512, 512, 512), el: (312, 512, 512), params: p)
-        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [3979])
+        #expect(Set(DoviTestSupport.rawVDR(out)[0]) == [3896])
     }
 
     // MARK: - D2: chroma MMR on a real RPU

From e725deb810c7002327feb8536e350ff5707eeffc Mon Sep 17 00:00:00 2001
From: williamliu0516 <122490794+williamliu0516@users.noreply.github.com>
Date: Tue, 13 Oct 2026 13:45:33 -0700
Subject: [PATCH 045/132] feat(audio): put LibTrueHD and LibDTSX behind package
 traits

Each object-audio decoder library is now behind a trait of its own, TrueHDObjectAudio and
DTSXObjectAudio, both on by default, so a host that does nothing keeps today's build. A host that
cannot ship one of them turns its trait off: the library is then neither linked nor resolved, and
its codec keeps the channel bridge whatever objectAudioRendering asks, with the reason in the
session log. The manifest moves to swift-tools-version 6.1, which traits need; CI also builds with
both traits off.
---
 .github/workflows/ci.yml                      |  4 ++++
 CHANGELOG.md                                  |  8 +++++++
 Package.swift                                 | 21 ++++++++++++++++---
 README.md                                     | 21 +++++++++++++++++--
 .../Spatial/DTSXObjectAudioDecoder.swift      |  3 +++
 .../Spatial/TrueHDObjectAudioDecoder.swift    |  3 +++
 .../Video/HLSVideoEngine+SpatialAudio.swift   | 18 ++++++++++++++++
 .../DTSXObjectMetadataMappingTests.swift      |  3 +++
 Tests/AetherEngineTests/DTSXSampleTests.swift |  3 +++
 .../TrueHDAtmosSampleTests.swift              |  3 +++
 .../TrueHDObjectMetadataMappingTests.swift    |  3 +++
 docs/api.md                                   |  2 +-
 docs/formats.md                               |  4 ++--
 13 files changed, 88 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3221315dd..4ef3b25be 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -37,6 +37,10 @@ jobs:
       - name: swift build
         run: swift build
 
+      # The object-audio decoder libraries are traits a host can turn off; keep that build compiling.
+      - name: swift build (traits off)
+        run: swift build --disable-default-traits --scratch-path .build-notraits
+
       # 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/CHANGELOG.md b/CHANGELOG.md
index b89228604..6fc68a1e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,14 @@ the public-API contract.
   the same run of bytes as their sectors. A listing without `VIDEO_TS/` is read as Blu-ray, as before,
   and one with both trees plays its Blu-ray title, the order an image is recognized in.
 
+- **LibTrueHD and LibDTSX can be left out.** Each object-audio decoder library is now behind a package
+  trait, `TrueHDObjectAudio` and `DTSXObjectAudio`, both on by default, so a host that does nothing
+  keeps today's build. A host that cannot ship one of them turns its trait off
+  (`.package(url:..., traits: [])`, or the package's traits in Xcode): the library is neither linked
+  nor resolved, and its codec keeps the channel bridge whatever `objectAudioRendering` asks, with the
+  reason in the session log. The manifest moves to swift-tools-version 6.1, which traits need. CI also
+  builds with both traits off. See README › Package traits.
+
 ### Fixed
 
 - **`serveIFramePlaylist` shows scrub thumbnails for HDR10, HLG and Dolby Vision titles** (#682). The
diff --git a/Package.swift b/Package.swift
index 159fbf410..c8190e1b4 100644
--- a/Package.swift
+++ b/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version: 6.0
+// swift-tools-version: 6.1
 
 import PackageDescription
 
@@ -25,6 +25,21 @@ let package = Package(
         // platforms. The target is preserved below so `swift build` on
         // macOS still produces the CLI for upstream development.
     ],
+    // Each object-audio decoder library sits behind a trait of its own, both on by default. A host that
+    // cannot ship one of them turns its trait off (`.package(url:..., traits: [...])`, or the package's
+    // traits in Xcode): the library is then not linked, and its codec keeps the channel bridge whatever
+    // `objectAudioRendering` asks. LibDovi, FFmpeg and everything else are unaffected.
+    traits: [
+        .trait(
+            name: "TrueHDObjectAudio",
+            description: "Link LibTrueHD, so objectAudioRendering can render TrueHD Atmos objects to APAC."
+        ),
+        .trait(
+            name: "DTSXObjectAudio",
+            description: "Link LibDTSX, so objectAudioRendering can render DTS:X heights and objects to APAC."
+        ),
+        .default(enabledTraits: ["TrueHDObjectAudio", "DTSXObjectAudio"]),
+    ],
     dependencies: [
         // Minimal FFmpeg build (avcodec, avformat, avutil, swresample only).
         // No network stack, we use custom AVIO + URLSession for HTTP streams.
@@ -68,8 +83,8 @@ let package = Package(
             dependencies: [
                 .product(name: "AetherFFmpegBuild", package: "FFmpegBuild"),
                 .product(name: "Dovi", package: "LibDovi"),
-                .product(name: "TrueHD", package: "LibTrueHD"),
-                .product(name: "DTSX", package: "LibDTSX"),
+                .product(name: "TrueHD", package: "LibTrueHD", condition: .when(traits: ["TrueHDObjectAudio"])),
+                .product(name: "DTSX", package: "LibDTSX", condition: .when(traits: ["DTSXObjectAudio"])),
             ],
             // Silent E-AC-3 Atmos that `AtmosOutputActivator` loops beside an APAC track on tvOS.
             resources: [.copy("Resources/silent-atmos.mp4")],
diff --git a/README.md b/README.md
index 148284e12..ec13c7cc5 100644
--- a/README.md
+++ b/README.md
@@ -653,6 +653,23 @@ The Swift and Xcode rows are the toolchain CI builds and tests with (GitHub's `x
 
 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")`.
 
+### Package traits
+
+The two object-audio decoder libraries are behind package traits, both on by default, so nothing changes for a host that does not ask:
+
+| Trait | Links | Without it |
+| --- | --- | --- |
+| `TrueHDObjectAudio` | [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD) | TrueHD Atmos keeps the channel bridge whatever `objectAudioRendering` asks |
+| `DTSXObjectAudio` | [LibDTSX](https://github.com/superuser404notfound/LibDTSX) | DTS:X keeps the channel bridge whatever `objectAudioRendering` asks |
+
+A host that cannot ship one of the libraries turns its trait off; the library is then neither linked nor resolved (it drops out of the host's `Package.resolved`), and the session log says why the codec stayed on the bridge (`built without the TrueHDObjectAudio trait`). In a package manifest, list the traits to keep (an empty list keeps none):
+
+```swift
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.36.0", traits: [])
+```
+
+In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: []` on the package). `swift build --disable-default-traits` builds the engine itself that way.
+
 ## Support
 
 If the engine is useful to you and you'd like to support its development, there's a [Ko-fi](https://ko-fi.com/superuser404).
@@ -675,9 +692,9 @@ The exception covers AetherEngine's own code; it does not extend to its dependen
 
 **libdovi** reaches your app through [LibDovi](https://github.com/superuser404notfound/LibDovi) as a static library. It is the compiled `dolby_vision` crate from [dovi_tool](https://github.com/quietvoid/dovi_tool), Copyright (c) quietvoid and contributors, dual-licensed MIT OR Apache-2.0 and consumed here under the MIT option. MIT asks for that copyright notice to travel with the binary, and it is quietvoid's notice that belongs on the acknowledgements screen. The MIT text in LibDovi's own `LICENSE` covers the packaging and build scripts only; both parts are in that one file.
 
-**LibTrueHD** ([superuser404notfound/LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) reaches your app as a static library and decodes TrueHD for `objectAudioRendering`. Its C API, framer and packaging are MIT (Copyright Quick104, who wrote it for Silo as SiloObjectAudio, and Vincent Herbst). It compiles in the `truehd` and `oamd` crates from [truehdd](https://github.com/truehdd/truehdd), Copyright Rainbaby and the truehdd contributors, under the Apache License 2.0, which asks for the license text and LibTrueHD's `NOTICE` to travel with the binary. Apache-2.0 combines with the engine's LGPL-3.0. The library is linked whether or not a host turns the option on.
+**LibTrueHD** ([superuser404notfound/LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) reaches your app as a static library and decodes TrueHD for `objectAudioRendering`. Its C API, framer and packaging are MIT (Copyright Quick104, who wrote it for Silo as SiloObjectAudio, and Vincent Herbst). It compiles in the `truehd` and `oamd` crates from [truehdd](https://github.com/truehdd/truehdd), Copyright Rainbaby and the truehdd contributors, under the Apache License 2.0, which asks for the license text and LibTrueHD's `NOTICE` to travel with the binary. Apache-2.0 combines with the engine's LGPL-3.0. It comes in through the `TrueHDObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it ([Package traits](#package-traits)).
 
-**LibDTSX** ([superuser404notfound/LibDTSX](https://github.com/superuser404notfound/LibDTSX)) reaches your app as a static library and decodes DTS:X for `objectAudioRendering`. Its C API, framing and packaging are Apache-2.0, and it compiles in the `dca` crate from [harletty-bridge](https://github.com/harletty/harletty-bridge), also under the Apache License 2.0, which asks for the license text and LibDTSX's `NOTICE` to travel with the binary. It is linked whether or not a host turns the option on.
+**LibDTSX** ([superuser404notfound/LibDTSX](https://github.com/superuser404notfound/LibDTSX)) reaches your app as a static library and decodes DTS:X for `objectAudioRendering`. Its C API, framing and packaging are Apache-2.0, and it compiles in the `dca` crate from [harletty-bridge](https://github.com/harletty/harletty-bridge), also under the Apache License 2.0, which asks for the license text and LibDTSX's `NOTICE` to travel with the binary. It comes in through the `DTSXObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it.
 
 **SMBClient** ([kishikawakatsumi/SMBClient](https://github.com/kishikawakatsumi/SMBClient), MIT) reaches your app only if you link the `AetherEngineSMB` product. Linking `AetherEngine` alone pulls in none of its symbols, even though SwiftPM still records the package in `Package.resolved`, which describes the resolved graph rather than what the linker kept.
 
diff --git a/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
index c70c2ee1c..27d392f38 100644
--- a/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
@@ -1,3 +1,5 @@
+// Only with the DTSXObjectAudio trait (on by default), which links LibDTSX.
+#if DTSXObjectAudio
 import Foundation
 import DTSX
 
@@ -185,3 +187,4 @@ final class DTSXObjectAudioDecoder: ObjectAudioDecoding {
             gain: element.flags & DTSX_ELEMENT_ACTIVE != 0 ? element.gain : 0)
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
index b6dfdfb5c..94564dbcf 100644
--- a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio trait (on by default), which links LibTrueHD.
+#if TrueHDObjectAudio
 import Foundation
 import TrueHD
 
@@ -219,3 +221,4 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
         }
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index 56dd58edd..4a20c485d 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -58,6 +58,7 @@ extension HLSVideoEngine {
         }
     }
 
+    #if DTSXObjectAudio
     /// Packets of the source's head `dtsxVerdict` may look at. LibDTSX needs three frames of the
     /// track, which a muxed file interleaves within the first few dozen packets; the same budget as
     /// the planner's head scans bounds a file whose audio starts late.
@@ -87,6 +88,7 @@ extension HLSVideoEngine {
         }
         return verdict
     }
+    #endif
 
     /// Build the producer on a `SpatialAudioBridge` when the host asked for object rendering and the
     /// source qualifies. Nil means "not this route": ineligible, unsupported OS, not DTS:X, or a
@@ -155,8 +157,17 @@ extension HLSVideoEngine {
             let decoder: ObjectAudioDecoding
             switch source {
             case .trueHDAtmos:
+                #if TrueHDObjectAudio
                 decoder = try TrueHDObjectAudioDecoder()
+                #else
+                EngineLog.emit(
+                    "[HLSVideoEngine] built without the TrueHDObjectAudio trait (no LibTrueHD); keeping the channel bridge",
+                    category: .session
+                )
+                return nil
+                #endif
             case .dtsHDMasterAudio:
+                #if DTSXObjectAudio
                 let dtsx = try DTSXObjectAudioDecoder()
                 // On a resume the verdict reads where the first producer starts, not the file head
                 // that step 8's seek would then drop; LibDTSX decides mid-stream as well.
@@ -192,6 +203,13 @@ extension HLSVideoEngine {
                     )
                     return nil
                 }
+                #else
+                EngineLog.emit(
+                    "[HLSVideoEngine] built without the DTSXObjectAudio trait (no LibDTSX); keeping the channel bridge",
+                    category: .session
+                )
+                return nil
+                #endif
             }
             bridge = try SpatialAudioBridge(
                 srcTimeBase: audioStream.pointee.time_base, layout: layout, decoder: decoder)
diff --git a/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift b/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
index c9d563f45..e2de14761 100644
--- a/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
+++ b/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
@@ -1,3 +1,5 @@
+// Only with the DTSXObjectAudio trait (on by default): the decoder and its library are not built without it.
+#if DTSXObjectAudio
 import Testing
 import Foundation
 import DTSX
@@ -88,3 +90,4 @@ struct DTSXObjectMetadataMappingTests {
         #expect(throws: DTSXObjectAudioDecoder.DecoderError.self) { try decoder.nextBlock() }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DTSXSampleTests.swift b/Tests/AetherEngineTests/DTSXSampleTests.swift
index 71c3cc18b..ea4ff2918 100644
--- a/Tests/AetherEngineTests/DTSXSampleTests.swift
+++ b/Tests/AetherEngineTests/DTSXSampleTests.swift
@@ -1,3 +1,5 @@
+// Only with the DTSXObjectAudio trait (on by default): the decoder and its library are not built without it.
+#if DTSXObjectAudio
 import Testing
 import Foundation
 import AetherLibavcodec
@@ -184,3 +186,4 @@ struct DTSXSampleTests {
         #expect(pts.count == 2 + Int((4_556_800.0 / 1024).rounded(.up)))
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift b/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift
index e82c2fe19..1341e9174 100644
--- a/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift
+++ b/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio trait (on by default): the decoder and its library are not built without it.
+#if TrueHDObjectAudio
 import Testing
 import Foundation
 import AetherLibavcodec
@@ -105,3 +107,4 @@ struct TrueHDAtmosSampleTests {
         #expect(pts.count == 2 + Int((1_298_000.0 / 1024).rounded(.up)))
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift b/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
index bde0d3b4c..bf8be5e0a 100644
--- a/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
+++ b/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio trait (on by default): the decoder and its library are not built without it.
+#if TrueHDObjectAudio
 import Testing
 import Foundation
 import TrueHD
@@ -149,3 +151,4 @@ struct TrueHDObjectMetadataMappingTests {
         #expect(try decoder.nextBlock() == nil)
     }
 }
+#endif
diff --git a/docs/api.md b/docs/api.md
index d9c152129..8a68b7dc8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1186,7 +1186,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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. |
-| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731). `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). |
+| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731). `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Each codec needs its package trait (`TrueHDObjectAudio`, `DTSXObjectAudio`, both on by default); with one turned off, that codec keeps the channel bridge. |
 | `confirmAtmos` | false | Background per-track JOC confirmation, republishing `audioTracks` as tracks confirm. Never on the start path; skipped for live and forward-only readers. |
 | `preferredAudioLanguages` | empty | First-frame audio pick from the engine's single probe. Ordered BCP-47 / ISO 639 tags; region and script are normalized and rank within one preference (#590). An explicit `audioSourceStreamIndex` still wins. |
 | `preferredSubtitleLanguages` | empty | Post-load subtitle activation on the host-overlay path. Ranks language specificity (an explicitly opposite script is rejected, not demoted) before the descriptor axis. Pure convenience: no reload and no pre-probe, unlike the audio equivalent. |
diff --git a/docs/formats.md b/docs/formats.md
index 93d31306a..4548e6493 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -331,7 +331,7 @@ The renderer is allocentric, the model Atmos metadata is authored in: the room i
 
 **Track choice.** With the option on, the automatic audio pick prefers a TrueHD Atmos track over the other tracks of the same language: of the `preferredAudioLanguages` match, or of the session's default track when no preference decides it. It never crosses a language or a dub (a region or script both tags state and disagree on), never picks a commentary for it, applies only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later), and an explicit `audioSourceStreamIndexOverride` still wins. Without that, a film carrying DTS-HD and TrueHD Atmos in one language usually opened on whichever the container listed first.
 
-It is opt-in because it is a trade: APAC is lossy, at several Mbit/s, in place of the lossless 7.1 the channel bridge delivers. It applies only to TrueHD that FFmpeg marks as Atmos, at 48 kHz, on OS 26 or later where the APAC encoder exists; anything else, and any failure to start, keeps `audioBridgeMode` with the audio intact. Silo built the first implementation in its fork and offered it as the reference this one is ported from.
+It is opt-in because it is a trade: APAC is lossy, at several Mbit/s, in place of the lossless 7.1 the channel bridge delivers. It applies only to TrueHD that FFmpeg marks as Atmos, at 48 kHz, on OS 26 or later where the APAC encoder exists; anything else, and any failure to start, keeps `audioBridgeMode` with the audio intact. Silo built the first implementation in its fork and offered it as the reference this one is ported from. The decoder comes with the `TrueHDObjectAudio` package trait, on by default; built without it, TrueHD Atmos keeps the channel bridge and the session log says so ([README › Package traits](../README.md#package-traits)).
 
 **Atmos on the receiver (tvOS).** tvOS sends APAC over HDMI as Dolby MAT, and some sinks show Dolby Atmos for it on their own, but not all: a Samsung HW-Q990C soundbar fed by an Apple TV 4K (tvOS 27.2) played APAC without ever showing Atmos, although `AVAudioSession` reported a MAT format throughout. While an APAC session plays, the engine therefore loops a silent E-AC-3 stream signalled as Dolby Atmos on a second, unmuted player (`AtmosOutputActivator`). On the same setup that brought the soundbar to Atmos before the first frame and kept it there across a seek. Nothing the app can read (`AVAudioSession`'s output format or channel count) tracked the indicator, so only the sink can confirm it. The stream is 2 s of digital silence written bit by bit from the E-AC-3 and object audio specifications (`Scripts/make-silent-atmos.swift`), plays only while the engine's player plays or waits to play an APAC item, and is released otherwise. iOS and macOS do not run it.
 
@@ -343,7 +343,7 @@ A linked peak limiter sits between the renderer and the encoder: the APAC encode
 
 ### DTS\:X with heights
 
-DTS:X reaches the bridge the same way TrueHD Atmos does: Apple TV cannot bitstream DTS-HD, so `audioBridgeMode` decodes the lossless 7.1, and on a DTS:X track that 7.1 is a compatible downmix into which the encoder folded the four height channels and any objects. `objectAudioRendering = .apac(layout)` keeps them: a DTS-HD Master Audio track goes through [LibDTSX](https://github.com/superuser404notfound/LibDTSX) (the `dca` crate from harletty-bridge behind a C API, packaged like LibTrueHD) into the same renderer, limiter and APAC encoder. LibDTSX does the DTS-specific work, so the engine side is a speaker mapping (`DTSXObjectAudioDecoder`): it subtracts every fold the frame states (or that `dca`'s fold renderer recomputes for an object the encoder panned into the bed) from the bed, so the bed, the heights and the objects play side by side without anything playing twice, and it places DTS:X's angular object positions in LibTrueHD's room coordinates. The reference sphere is projected onto the room's boundary through the speakers' angles (centre 0°, front ±30°, wide ±60°, side ±90°, rear ±145°), the ceiling reached at the 45° of a height speaker and its centre straight overhead, so the dual-balance panner places a sound between two speakers in the same proportion an angular panner would.
+DTS:X reaches the bridge the same way TrueHD Atmos does: Apple TV cannot bitstream DTS-HD, so `audioBridgeMode` decodes the lossless 7.1, and on a DTS:X track that 7.1 is a compatible downmix into which the encoder folded the four height channels and any objects. `objectAudioRendering = .apac(layout)` keeps them: a DTS-HD Master Audio track goes through [LibDTSX](https://github.com/superuser404notfound/LibDTSX) (the `dca` crate from harletty-bridge behind a C API, packaged like LibTrueHD) into the same renderer, limiter and APAC encoder. LibDTSX does the DTS-specific work, so the engine side is a speaker mapping (`DTSXObjectAudioDecoder`): it subtracts every fold the frame states (or that `dca`'s fold renderer recomputes for an object the encoder panned into the bed) from the bed, so the bed, the heights and the objects play side by side without anything playing twice, and it places DTS:X's angular object positions in LibTrueHD's room coordinates. The reference sphere is projected onto the room's boundary through the speakers' angles (centre 0°, front ±30°, wide ±60°, side ±90°, rear ±145°), the ceiling reached at the 45° of a height speaker and its centre straight overhead, so the dual-balance panner places a sound between two speakers in the same proportion an angular panner would. LibDTSX comes with the `DTSXObjectAudio` package trait, on by default, in the same way.
 
 The standard presentation, which every DTS:X film in SpatialAudioBridge's library census used in every frame, is a 7.1 bed and four fixed heights (top front and top back pairs), all routed discretely: rendered into 7.1.4, *8 Mile*, *The Bourne Identity* and the DTS:X Object Emulator demo give each speaker exactly its channel, bit for bit what SpatialAudioBridge's DTS:X renderer gives. The alternate presentations add one to five objects; `dca` classifies them from a corpus and calls them experimental. *Independence Day* (FFmpeg: "DTS-HD MA + DTS:X IMAX") is one: two static objects at ±34.5° and 12° up, which pan mostly into the front pair, a little into the sides and the front heights. Against SpatialAudioBridge's renderer, which pans DTS:X by angle over a bed ring and a height ring, the 7.1.4 render of a minute of it points the sound the same way within 0.07° (median of 200 ms windows, energy-weighted; 90th percentile 0.39°), and of the D4 trailer's five moving objects within 0.23° (2.3°); the floor channels correlate at 1.0000, and the ceiling's share of the energy is 0.1 to 0.2 points lower. These figures were taken against the panner before #742 moved its top speakers from the room's corners a quarter in, so the object renders now differ from them slightly; the standard presentation routes discretely and is unaffected.
 

From 11c28a53e3d193ddf14db61d1991e6e3038b1d4b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 06:17:07 +0200
Subject: [PATCH 046/132] fix(audio): decode FLAC whose blocks are under
 CoreMedia's 192-sample floor (#764)

CoreMedia validates the STREAMINFO min_blocksize field against 192, not the
spec's 16. A field of 191 drops the audio track even over real 4608-sample
frames, and a field of 192 over real 144-sample frames passes that check and
then hangs the decoder, so the AE#221 clamp cannot be extended to cover it.

A stream whose min_blocksize stays below 192 after the AE#221 repair now goes
through the FLAC bridge on the video route (bit-perfect for FLAC) and to the
FFmpeg host on the audio-only route. The stream-copy fallback packet duration
uses the block size STREAMINFO declares when min = max instead of 4096.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  12 ++
 Sources/AetherEngine/AetherEngine.swift       |  10 +-
 .../AetherEngine/Audio/FLACStreamInfo.swift   |  62 ++++++++++
 .../AetherEngine/Video/HLSVideoEngine.swift   |  18 ++-
 .../AetherEngine/Video/MP4SegmentMuxer.swift  |  20 ++--
 .../Issue764FLACSmallBlockTests.swift         | 109 ++++++++++++++++++
 docs/formats.md                               |   2 +-
 7 files changed, 216 insertions(+), 17 deletions(-)
 create mode 100644 Sources/AetherEngine/Audio/FLACStreamInfo.swift
 create mode 100644 Tests/AetherEngineTests/Issue764FLACSmallBlockTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b89228604..d9fc88e64 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,18 @@ the public-API contract.
 
 ### Fixed
 
+- **FLAC with blocks under 192 samples plays instead of failing to open** (#764). An MKV whose FLAC used
+  small fixed blocks (`STREAMINFO` min = max = 144, 48 kHz stereo) died on the native path with
+  `-11829 "Cannot Open"` (underlying `-12848`), and the same stream in a plain `.flac` file failed the
+  audio-only route. CoreMedia's floor for `min_blocksize` is 192, not the specification's 16: measured on
+  macOS 26, a field of 191 drops the audio track even over real 4608-sample frames, and a field of 192 over
+  real 144-sample frames gets past that check and then hangs the decoder, so the field cannot simply be
+  raised. Such a stream is now decoded by libavcodec: the video route bridges it (bit-perfect for FLAC),
+  the audio-only route takes the FFmpeg host. A zeroed `min_blocksize` over a legal `max_blocksize` keeps
+  the AE#221 clamp and stays a stream copy. The stream-copy fallback packet duration for FLAC also uses
+  the block size `STREAMINFO` declares when min = max, instead of assuming 4096 samples. Covered by
+  `Issue764FLACSmallBlockTests`.
+
 - **`serveIFramePlaylist` shows scrub thumbnails for HDR10, HLG and Dolby Vision titles** (#682). The
   stock tvOS scrubber fetched the first keyframe of a PQ rendition and then left the thumbnail box empty,
   for Dolby Vision profile 5 and 8.1 as much as for plain HDR10, at 4K and at 1080p (measured on an Apple
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 39463ec3b..555f32239 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4745,8 +4745,14 @@ public final class AetherEngine: ObservableObject {
             let audioCodecID: AVCodecID = (probeOpened && resolvedInitialAudio >= 0)
                 ? (probe.stream(at: resolvedInitialAudio)?.pointee.codecpar.pointee.codec_id ?? AV_CODEC_ID_NONE)
                 : AV_CODEC_ID_NONE
-            let useNativeAudio = !isCustomSource && Self.avPlayerCanDecodeAudio(audioCodecID)
-            EngineLog.emit("[AetherEngine] audio dispatch: codec=\(audioCodecID.rawValue) -> \(useNativeAudio ? "AVPlayer" : "FFmpeg")", category: .engine)
+            // AE#764: AVPlayer reads the source's own STREAMINFO here, so a FLAC with blocks under
+            // CoreMedia's floor goes to libavcodec rather than failing to open.
+            let flacBlocksTooSmall = probeOpened && resolvedInitialAudio >= 0
+                && (probe.stream(at: resolvedInitialAudio).map {
+                    FLACStreamInfo.coreMediaRejectsSource(UnsafePointer($0.pointee.codecpar))
+                } ?? false)
+            let useNativeAudio = !isCustomSource && Self.avPlayerCanDecodeAudio(audioCodecID) && !flacBlocksTooSmall
+            EngineLog.emit("[AetherEngine] audio dispatch: codec=\(audioCodecID.rawValue) -> \(useNativeAudio ? "AVPlayer" : "FFmpeg")\(flacBlocksTooSmall ? " (FLAC min_blocksize below CoreMedia's floor)" : "")", category: .engine)
             // A preserved video NativeAVPlayerHost from a native->native reload must be released before an audio
             // session; otherwise the old AVPlayer stays alive in currentAVPlayer and the volume setter writes into it.
             if nativeHost != nil {
diff --git a/Sources/AetherEngine/Audio/FLACStreamInfo.swift b/Sources/AetherEngine/Audio/FLACStreamInfo.swift
new file mode 100644
index 000000000..86f0fee4d
--- /dev/null
+++ b/Sources/AetherEngine/Audio/FLACStreamInfo.swift
@@ -0,0 +1,62 @@
+import AetherLibavcodec
+
+/// The two blocksize fields of a FLAC `STREAMINFO`, read from a codecpar's extradata.
+///
+/// AE#764: CoreMedia keys FLAC on the `min_blocksize` FIELD, with a floor of 192 samples (FLAC's smallest
+/// standard block size), well above the spec's 16. Measured on macOS 26 against fixed-blocksize encodes and
+/// field-patched copies of them: a field below 192 drops the audio track (`asset.tracks` without audio, an
+/// HLS item fails `-11829` / `-12848`) even when every real frame is 4608 samples; a field of 192 over real
+/// 144-sample frames gets past that check and then hangs Apple's decoder (`copyNextSampleBuffer` never
+/// returns). So the field can only be rewritten upward when the frames really are that large, which is the
+/// AE#221 clamp's premise, and a stream whose blocks really are small has to be decoded by libavcodec.
+enum FLACStreamInfo {
+    /// Smallest `min_blocksize` CoreMedia accepts. 191 fails, 192 plays and decodes bit-exact.
+    static let coreMediaMinimumBlockSize: UInt16 = 192
+    /// Spec floor for both blocksize fields.
+    static let specMinimumBlockSize: UInt16 = 16
+    /// `STREAMINFO` payload length.
+    static let size = 34
+
+    /// nil for a non-FLAC codecpar or extradata too short to be a `STREAMINFO`.
+    static func blockSizes(_ codecpar: UnsafePointer<AVCodecParameters>) -> (min: UInt16, max: UInt16)? {
+        guard codecpar.pointee.codec_id == AV_CODEC_ID_FLAC,
+              let extradata = codecpar.pointee.extradata,
+              codecpar.pointee.extradata_size >= Int32(size) else { return nil }
+        return blockSizes(UnsafeBufferPointer(start: extradata, count: 4))
+    }
+
+    static func blockSizes<C: Collection>(_ bytes: C) -> (min: UInt16, max: UInt16)? where C.Element == UInt8 {
+        let b = Array(bytes.prefix(4))
+        guard b.count == 4 else { return nil }
+        return (UInt16(b[0]) << 8 | UInt16(b[1]), UInt16(b[2]) << 8 | UInt16(b[3]))
+    }
+
+    /// AE#221: the value an illegal `min_blocksize` is clamped up to, or nil when there is nothing to repair
+    /// or nothing to repair it with. `max_blocksize` is the only blocksize the container attests to.
+    static func repairedMinBlockSize(min: UInt16, max: UInt16) -> UInt16? {
+        guard min < specMinimumBlockSize, max >= specMinimumBlockSize else { return nil }
+        return max
+    }
+
+    /// Whether CoreMedia refuses this stream as the source declares it. Audio-only playback hands AVPlayer
+    /// the source itself, so nothing repairs the field on that route. False when there is no `STREAMINFO`
+    /// to read, so an unreadable header keeps whatever route it had.
+    static func coreMediaRejectsSource(_ codecpar: UnsafePointer<AVCodecParameters>) -> Bool {
+        guard let sizes = blockSizes(codecpar) else { return false }
+        return sizes.min < coreMediaMinimumBlockSize
+    }
+
+    /// Whether CoreMedia refuses the `dfLa` a stream copy would write, i.e. after the AE#221 repair.
+    static func coreMediaRejectsStreamCopy(_ codecpar: UnsafePointer<AVCodecParameters>) -> Bool {
+        guard let sizes = blockSizes(codecpar) else { return false }
+        let written = repairedMinBlockSize(min: sizes.min, max: sizes.max) ?? sizes.min
+        return written < coreMediaMinimumBlockSize
+    }
+
+    /// The samples per frame a fixed-blocksize stream declares (min = max), for a packet duration fallback.
+    static func fixedBlockSize(_ codecpar: UnsafePointer<AVCodecParameters>) -> Int64? {
+        guard let sizes = blockSizes(codecpar), sizes.min == sizes.max,
+              sizes.max >= specMinimumBlockSize else { return nil }
+        return Int64(sizes.max)
+    }
+}
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 0ed68ced9..1712d19e9 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1869,7 +1869,20 @@ public final class HLSVideoEngine: @unchecked Sendable {
                     frameSize: acpForHE.frame_size,
                     hasASC: hasASC
                 )
-            if compat.requiresBridge || isHEAAC {
+            // AE#764: CoreMedia refuses a FLAC min_blocksize under 192 and hangs on frames smaller than the
+            // field claims, so a stream with small blocks cannot be copied, only decoded.
+            let flacBlocksTooSmall = compat == .flac
+                && FLACStreamInfo.coreMediaRejectsStreamCopy(UnsafePointer(audioStream.pointee.codecpar))
+            if flacBlocksTooSmall {
+                bridgePreferred = true
+                let sizes = FLACStreamInfo.blockSizes(UnsafePointer(audioStream.pointee.codecpar))
+                EngineLog.emit(
+                    "[HLSVideoEngine] audio: FLAC STREAMINFO min_blocksize=\(sizes?.min ?? 0) "
+                    + "max_blocksize=\(sizes?.max ?? 0) is below CoreMedia's floor of "
+                    + "\(FLACStreamInfo.coreMediaMinimumBlockSize), bridging instead of stream-copy",
+                    category: .session
+                )
+            } else if compat.requiresBridge || isHEAAC {
                 bridgePreferred = true
                 EngineLog.emit(
                     isHEAAC
@@ -1920,6 +1933,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
                 let sampleRate = Int64(acp.sample_rate)
                 let frameSamples: Int64 = {
                     if acp.frame_size > 0 { return Int64(acp.frame_size) }
+                    if let declared = FLACStreamInfo.fixedBlockSize(UnsafePointer(audioStream.pointee.codecpar)) {
+                        return declared
+                    }
                     switch acp.codec_id {
                     case AV_CODEC_ID_AC3, AV_CODEC_ID_EAC3: return 1536
                     case AV_CODEC_ID_AAC: return 1024
diff --git a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
index a25b09308..c17e93a71 100644
--- a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
+++ b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
@@ -1220,20 +1220,18 @@ final class MP4SegmentMuxer {
     /// target; when it is illegal too there is nothing to copy from and inventing a value would be a guess.
     /// Bisected on the reporter's asset: `min_blocksize` alone decides whether the session opens, and
     /// `total_samples` (equally wrong there, describing the pre-cut source) does not, so nothing else moves.
+    /// A field this repair leaves below CoreMedia's real floor of 192 never gets here: the audio route
+    /// bridges that stream instead (AE#764, `FLACStreamInfo`).
     static func sanitizedFLACExtradata(
         _ codecpar: UnsafePointer<AVCodecParameters>
     ) -> [UInt8]? {
-        guard codecpar.pointee.codec_id == AV_CODEC_ID_FLAC,
-              let extradata = codecpar.pointee.extradata,
-              codecpar.pointee.extradata_size >= Int32(flacStreamInfoSize) else { return nil }
+        guard let (minBlockSize, maxBlockSize) = FLACStreamInfo.blockSizes(codecpar),
+              let repaired = FLACStreamInfo.repairedMinBlockSize(min: minBlockSize, max: maxBlockSize),
+              let extradata = codecpar.pointee.extradata else { return nil }
 
         var bytes = [UInt8](UnsafeBufferPointer(start: extradata, count: Int(codecpar.pointee.extradata_size)))
-        let minBlockSize = UInt16(bytes[0]) << 8 | UInt16(bytes[1])
-        let maxBlockSize = UInt16(bytes[2]) << 8 | UInt16(bytes[3])
-        guard minBlockSize < flacMinimumBlockSize, maxBlockSize >= flacMinimumBlockSize else { return nil }
-
-        bytes[0] = UInt8(maxBlockSize >> 8)
-        bytes[1] = UInt8(maxBlockSize & 0xFF)
+        bytes[0] = UInt8(repaired >> 8)
+        bytes[1] = UInt8(repaired & 0xFF)
         EngineLog.emit(
             "[MP4SegmentMuxer] FLAC STREAMINFO min_blocksize=\(minBlockSize) is illegal, "
             + "clamped to max_blocksize=\(maxBlockSize) so dfLa passes CoreMedia validation",
@@ -1242,10 +1240,6 @@ final class MP4SegmentMuxer {
         return bytes
     }
 
-    /// FLAC `STREAMINFO` payload length, and the spec's floor for both blocksize fields.
-    private static let flacStreamInfoSize = 34
-    private static let flacMinimumBlockSize: UInt16 = 16
-
     /// Replace codecpar.extradata using av_malloc + AV_INPUT_BUFFER_PADDING_SIZE pad.
     private static func replaceExtradata(
         _ codecpar: UnsafeMutablePointer<AVCodecParameters>,
diff --git a/Tests/AetherEngineTests/Issue764FLACSmallBlockTests.swift b/Tests/AetherEngineTests/Issue764FLACSmallBlockTests.swift
new file mode 100644
index 000000000..c6b916f76
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue764FLACSmallBlockTests.swift
@@ -0,0 +1,109 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// AE#764: CoreMedia's floor for a FLAC `STREAMINFO` `min_blocksize` is 192, not the spec's 16. An MKV whose
+/// FLAC used fixed 144-sample blocks failed the native path with `-11829` / `-12848`, and the AE#221 clamp
+/// had nothing to copy from because `max_blocksize` was 144 too. Measured on macOS 26: a field of 191 drops
+/// the track even over real 4608-sample frames, and a field of 192 over real 144-sample frames hangs the
+/// decoder, so such a stream is decoded by libavcodec instead of being copied.
+@Suite("AE#764: FLAC blocks under CoreMedia's floor")
+struct Issue764FLACSmallBlockTests {
+
+    /// A FLAC codecpar whose extradata is a 34-byte STREAMINFO with the given block sizes.
+    private static func withFLAC(
+        min: UInt16, max: UInt16, length: Int = 34, codec: AVCodecID = AV_CODEC_ID_FLAC,
+        _ body: (UnsafePointer<AVCodecParameters>) -> Void
+    ) {
+        guard let codecpar = avcodec_parameters_alloc() else {
+            Issue.record("avcodec_parameters_alloc failed")
+            return
+        }
+        defer {
+            var p: UnsafeMutablePointer<AVCodecParameters>? = codecpar
+            avcodec_parameters_free(&p)
+        }
+        var bytes = [UInt8](repeating: 0, count: length)
+        if length >= 4 {
+            bytes[0] = UInt8(min >> 8); bytes[1] = UInt8(min & 0xFF)
+            bytes[2] = UInt8(max >> 8); bytes[3] = UInt8(max & 0xFF)
+        }
+        guard let buf = av_mallocz(length + Int(AV_INPUT_BUFFER_PADDING_SIZE))?
+            .assumingMemoryBound(to: UInt8.self) else {
+            Issue.record("av_mallocz failed")
+            return
+        }
+        bytes.withUnsafeBufferPointer { if let base = $0.baseAddress { memcpy(buf, base, length) } }
+        codecpar.pointee.codec_type = AVMEDIA_TYPE_AUDIO
+        codecpar.pointee.codec_id = codec
+        codecpar.pointee.extradata = buf
+        codecpar.pointee.extradata_size = Int32(length)
+        body(UnsafePointer(codecpar))
+    }
+
+    @Test("the reporter's shape, min = max = 144, cannot be stream-copied")
+    func reporterShapeBridges() {
+        Self.withFLAC(min: 144, max: 144) { codecpar in
+            #expect(FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar))
+            #expect(FLACStreamInfo.coreMediaRejectsSource(codecpar))
+            #expect(MP4SegmentMuxer.sanitizedFLACExtradata(codecpar) == nil,
+                    "a legal field is not the AE#221 clamp's to touch")
+        }
+    }
+
+    @Test("191 is refused and 192 passes", arguments: [
+        (UInt16(16), true), (UInt16(160), true), (UInt16(191), true),
+        (UInt16(192), false), (UInt16(4608), false),
+    ])
+    func floorIs192(size: UInt16, rejected: Bool) {
+        Self.withFLAC(min: size, max: size) { codecpar in
+            #expect(FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar) == rejected)
+            #expect(FLACStreamInfo.coreMediaRejectsSource(codecpar) == rejected)
+        }
+    }
+
+    @Test("a legal min under 192 bridges even when max is large: its small frames would hang the decoder")
+    func variableBlocksizeWithSmallMinBridges() {
+        Self.withFLAC(min: 144, max: 4608) { codecpar in
+            #expect(FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar))
+        }
+    }
+
+    @Test("a zeroed min over a legal max keeps the AE#221 clamp and stays a stream copy")
+    func zeroedMinStillClamps() {
+        Self.withFLAC(min: 0, max: 4608) { codecpar in
+            #expect(!FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar))
+            #expect(FLACStreamInfo.coreMediaRejectsSource(codecpar),
+                    "audio-only hands AVPlayer the unrepaired source")
+            #expect(MP4SegmentMuxer.sanitizedFLACExtradata(codecpar).flatMap { FLACStreamInfo.blockSizes($0) }?.min == 4608)
+        }
+    }
+
+    @Test("a zeroed min over a max under 192 bridges", arguments: [UInt16(0), UInt16(144)])
+    func clampTargetBelowFloorBridges(max: UInt16) {
+        Self.withFLAC(min: 0, max: max) { codecpar in
+            #expect(FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar))
+        }
+    }
+
+    @Test("no STREAMINFO to read keeps the route")
+    func unreadableHeaderKeepsRoute() {
+        Self.withFLAC(min: 144, max: 144, length: 33) { codecpar in
+            #expect(!FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar))
+            #expect(!FLACStreamInfo.coreMediaRejectsSource(codecpar))
+        }
+        Self.withFLAC(min: 144, max: 144, codec: AV_CODEC_ID_ALAC) { codecpar in
+            #expect(!FLACStreamInfo.coreMediaRejectsStreamCopy(codecpar))
+        }
+    }
+
+    @Test("the fallback packet duration takes a fixed block size from STREAMINFO")
+    func fixedBlockSize() {
+        Self.withFLAC(min: 4608, max: 4608) { #expect(FLACStreamInfo.fixedBlockSize($0) == 4608) }
+        Self.withFLAC(min: 192, max: 192) { #expect(FLACStreamInfo.fixedBlockSize($0) == 192) }
+        Self.withFLAC(min: 0, max: 4608) { #expect(FLACStreamInfo.fixedBlockSize($0) == nil) }
+        Self.withFLAC(min: 192, max: 4608) { #expect(FLACStreamInfo.fixedBlockSize($0) == nil) }
+    }
+}
diff --git a/docs/formats.md b/docs/formats.md
index 93d31306a..931d055a6 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -247,7 +247,7 @@ The label can also be taken back from the item itself, where the platform has no
 
 | | |
 | --- | --- |
-| Stream-copy (lossless into fMP4) | AAC-LC, AC3, EAC3, FLAC, ALAC. HE-AAC / HE-AACv2 stream-copy when the source carries an AudioSpecificConfig (any movie container) and bridge only without one (live ADTS / MPEG-TS, where a synthesized ASC would mis-signal SBR). LATM/LOAS-framed AAC (DVB broadcast framing) always bridges |
+| Stream-copy (lossless into fMP4) | AAC-LC, AC3, EAC3, FLAC, ALAC. HE-AAC / HE-AACv2 stream-copy when the source carries an AudioSpecificConfig (any movie container) and bridge only without one (live ADTS / MPEG-TS, where a synthesized ASC would mis-signal SBR). LATM/LOAS-framed AAC (DVB broadcast framing) always bridges. FLAC whose `STREAMINFO` `min_blocksize` is below 192 bridges too (AE#764): CoreMedia drops a track that declares less, and hangs on frames smaller than the field claims, so such a stream cannot be copied (the bridge is bit-perfect for FLAC). The same field sends an audio-only FLAC to the FFmpeg host instead of AVPlayer |
 | Bridged (`AudioBridge`) | TrueHD, MLP, DTS, DTS-HD MA, MP3, MP2, Opus, Vorbis, PCM (raw shapes plus G.711 A-law / mu-law), WMA (Standard, Pro, Lossless, Voice), and the Flash tail Nellymoser Asao / ADPCM-SWF / Speex: decoded to PCM and re-encoded |
 | Surround | 5.1 / 7.1 with correct `AudioChannelLayout` preserved through the wrapper |
 

From ec97b90066f3b59e99aa337e01fded0237df60c9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 08:18:23 +0200
Subject: [PATCH 047/132] docs(changelog): file the RPU guard under Unreleased
 (#765)

The entry landed under the released 7.29.0 section because the PR branch
predates the last releases. Moved to Unreleased > Fixed with credit, and
the verification against dovi_tool's RPU corpus noted. Drops a duplicated
trailing comment in DoviRpuGuard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 13 ++++++++++++-
 Sources/AetherEngine/Video/DoviRpuGuard.swift |  2 +-
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95cfc0f74..6b9978e91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -70,6 +70,18 @@ the public-API contract.
   a fresh seal; the consumer item swaps to it in place, keeping source, cache, position (also behind
   live) and play/pause intent. A media playlist failure no longer counts as evidence against the HDR
   master (#748, thanks @yucelokan).
+- **A CRC-valid but hostile Dolby Vision RPU no longer aborts the process on any path found so far,
+  in parse, convert or write (#765, thanks @pkajaba).** libdovi is built panic=abort, so one panic ends
+  the process. `DoviRpuGuard` checks the CRC and pre-scans each RPU for the inputs that make libdovi 3.4
+  panic or allocate unbounded: a polynomial piece with linear interpolation (`unimplemented!` in the
+  parser and the writer), a reshaping curve that mixes polynomial and MMR pieces (it parses, and a MEL
+  or residual-free RPU keeps its mapping through the mode 2 conversion, so `dovi_write_unspec62_nalu`
+  then indexes out of bounds), pivot and block counts the payload cannot hold, and display-management
+  block lengths the spec does not define (`unreachable!`). It also refuses an Exp-Golomb value of
+  2^32 - 1 or more anywhere it reads one (libdovi reads 64 leading zeros differently from a plain shift,
+  so a crafted `mapping_idc` could slip past, and its writer allocates about 0.5 GB to write such an id
+  back). The guard knows these paths; it does not prove there are no others. Every RPU in dovi_tool's
+  test corpus (2333, Profile 5, 7 MEL and FEL, 8, CM v2.9 and v4.0) passes it and converts as before.
 
 ## [7.36.0] - 2026-10-13
 
@@ -487,7 +499,6 @@ the public-API contract.
 - **A play or pause pressed during any session rebuild decides how it comes back.** An audio or disc-title switch, `reloadAtCurrentPosition()` or an engine-raised rebuild came back in the transport state it started from, so a pause pressed while it ran was lost. `play()` and `pause()` now write the transport the rebuild settles from, `transportIntentUnderReconstruction` (#464 round 3), while one runs. #711 had added this for audio picks in a field of its own; the two are one now.
 - **Video routing asks for the AV1 hardware decoder only for AV1 sources (#708).** It registered the supplemental decoder on every first load, H.264 and HEVC included. Contributed by yucelokan.
 - **The #243 fetch-tally test tolerates a parallel session start.** A session start zeroes the process-wide tally, so an engine test loading in parallel failed it on CI. Test-only.
-- **A CRC-valid but hostile Dolby Vision RPU no longer aborts the process on any path found so far, in parse, convert or write.** libdovi is built panic=abort, so one panic ends the process. `DoviRpuGuard` checks the CRC and pre-scans each RPU for the inputs that make libdovi 3.4 panic or allocate unbounded: a polynomial piece with linear interpolation (`unimplemented!` in the parser and the writer), a reshaping curve that mixes polynomial and MMR pieces (it parses, and a MEL or residual-free RPU keeps its mapping through the mode 2 conversion, so `dovi_write_unspec62_nalu` then indexes out of bounds), pivot and block counts the payload cannot hold, and display-management block lengths the spec does not define (`unreachable!`). It also refuses an Exp-Golomb value of 2^32 - 1 or more anywhere it reads one (libdovi reads 64 leading zeros differently from a plain shift, so a crafted `mapping_idc` could slip past, and its writer allocates about 0.5 GB to write such an id back). The guard knows these paths; it does not prove there are no others.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/Video/DoviRpuGuard.swift b/Sources/AetherEngine/Video/DoviRpuGuard.swift
index 76fecb89b..2e724eb3e 100644
--- a/Sources/AetherEngine/Video/DoviRpuGuard.swift
+++ b/Sources/AetherEngine/Video/DoviRpuGuard.swift
@@ -219,7 +219,7 @@ enum DoviRpuGuard {
         if !compressed {   // fixed fields of VdrDmData::parse
             guard r.pos + 509 <= r.end else { return false }
             r.pos += 509
-        }   // fixed fields of VdrDmData::parse
+        }
         for section in 0..<2 {
             if section == 1 && r.end - r.pos < 56 { return false }   // DM_DATA_PAYLOAD2_MIN_BITS
             guard let count = r.ue() else { return false }

From fcc3ea81498b9feb81b31b99bdc00608bf080512 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 09:00:24 +0200
Subject: [PATCH 048/132] fix(dovi): #767 follow-up: P8.1 rewrite skips the
 header read, pin the reporting change

- separateDualLayers reads the RPU header only when the dual-layer outputs
  want it. convertPacketToProfile81 (extractEL and extractParams off) threw
  the FEL/MEL and flag results away, so today's P7 to 8.1 path paid an extra
  libdovi call and a String allocation per frame for nothing.
- Test: a packet whose only NALs are a refused RPU and an EL stays byte for
  byte as it was and now reports failure, the one behaviour change #767 names.
- CHANGELOG: Unreleased > Changed entry for that reporting change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                        |  7 +++++++
 Sources/AetherEngine/Video/DoviRpuConverter.swift   |  3 ++-
 Tests/AetherEngineTests/DoviRpuConverterTests.swift | 12 ++++++++++++
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b9978e91..5139e7ebc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,13 @@ the public-API contract.
   the same run of bytes as their sectors. A listing without `VIDEO_TS/` is read as Blu-ray, as before,
   and one with both trees plays its Blu-ray title, the order an image is recognized in.
 
+### Changed
+
+- **Dolby Vision Profile 7: a packet whose only NALs are a refused RPU and its EL now reports the
+  conversion as failed** (#767, thanks @pkajaba). The packet is left as it was, as before; the result used
+  to say success, which hid the dropped RPU from the one-shot conversion log and from `aetherctl dovitest`.
+  The same PR adds the Metal FEL composer and the Dolby Vision display metadata, which nothing selects yet.
+
 ### Fixed
 
 - **FLAC with blocks under 192 samples plays instead of failing to open** (#764). An MKV whose FLAC used
diff --git a/Sources/AetherEngine/Video/DoviRpuConverter.swift b/Sources/AetherEngine/Video/DoviRpuConverter.swift
index 62b972dd0..149b7d0d0 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter.swift
@@ -190,7 +190,8 @@ public enum DoviRpuConverter {
                 defer { dovi_rpu_free(rpu) }
                 let thisParams: DoviMetalParams? = extractParams ? DoviFelComposer.parseRpuParameters(rpu: rpu) : nil
                 var thisPrevious = false, thisDisableResidual = false, thisFEL = false, thisMEL = false
-                if let hdr = dovi_rpu_get_header(rpu) {
+                // Only the dual-layer outputs read the header; the P8.1 rewrite drops what it yields.
+                if keepRpuBytes, let hdr = dovi_rpu_get_header(rpu) {
                     if hdr.pointee.use_prev_vdr_rpu_flag { thisPrevious = true }
                     thisDisableResidual = hdr.pointee.disable_residual_flag
                     if let elTypePtr = hdr.pointee.el_type {
diff --git a/Tests/AetherEngineTests/DoviRpuConverterTests.swift b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
index da8ab3d33..f3fd1197a 100644
--- a/Tests/AetherEngineTests/DoviRpuConverterTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
@@ -72,6 +72,18 @@ struct DoviRpuConverterTests {
         #expect(nalTypes(pkt) == [1])
     }
 
+    @Test("A packet of only a refused RPU and an EL is left untouched and reports the failure")
+    func refusedRPUWithoutBaseLayerReportsFailure() {
+        let nals = [hevcNAL(type: 62, payload: [0x00]), hevcNAL(type: 63, payload: [0xCC])]
+        let bytes = framed(nals, .lengthPrefixed(size: 4))
+        let pkt = packet(from: bytes)
+        defer { free(pkt) }
+
+        // Nothing is left to rebuild a packet from, so it stays as it was, but the dropped RPU still counts.
+        #expect(DoviRpuConverter.convertPacketToProfile81(pkt) == false)
+        #expect(packetBytes(pkt) == bytes)
+    }
+
     /// CRC-valid RPUs that reach a panic or an unbounded allocation in libdovi, and one with a wrong CRC.
     /// Handing any of them to libdovi aborts the test process, so passing is the point.
     typealias Hostile = (name: String, rpu: [UInt8])

From 069a7a7a7af36c275b83335fdb3c847f2602fe30 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 09:48:36 +0200
Subject: [PATCH 049/132] test: the #767 Dolby Vision suites run off the
 cooperative pool

CI's one-thread cooperative pool job failed twice on main after #767, both
times in the AE#711 fixture writer: `video 4/120` and `video 60/120` when its
fixed 20 s deadline ran out, with the writer still taking samples.

The new Dolby Vision suites block their thread for seconds at a time: the
synchronous compose waits on the GPU, and the CRC-valid fuzz and the guard's
exp-Golomb sweep are CPU loops. On the one-thread pool that thread is the only
one, so everything else, including the playing-capture test, waits behind
them. Locally under LIBDISPATCH_COOPERATIVE_POOL_STRICT=1 that test took
16.5 s without the Dolby Vision suites, 38 s with them, and 24 s with them
marked `.offCooperativePool`, the trait made for tests that block on purpose.

The fixture's deadline is now a stall deadline: it only gives up after 20 s
in which the writer took nothing, which is the deadlock it was written for.
A slow writer that is still moving is not one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/DoviComposeAsyncTests.swift  |  2 +-
 .../DoviComposedFrameRpuTests.swift                  |  2 +-
 Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift  |  1 +
 Tests/AetherEngineTests/DoviDitherTests.swift        |  1 +
 .../DoviEnhancementUpsamplerTests.swift              |  2 +-
 Tests/AetherEngineTests/DoviFelFuzzTests.swift       |  1 +
 Tests/AetherEngineTests/DoviFelMathTests.swift       |  1 +
 .../AetherEngineTests/DoviGpuAdversarialTests.swift  |  1 +
 Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift |  1 +
 Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift   |  1 +
 Tests/AetherEngineTests/DoviLayoutProbeTests.swift   |  1 +
 Tests/AetherEngineTests/DoviRpuGuardTests.swift      |  1 +
 Tests/AetherEngineTests/DoviShaderSyncTests.swift    |  1 +
 Tests/AetherEngineTests/ItemSwapStillTests.swift     | 12 ++++++++----
 14 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
index 8d0a4e194..48ecd8be7 100644
--- a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
+++ b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
@@ -7,7 +7,7 @@ import Metal
 /// `composeAsync` is the playback path: it must produce exactly what the blocking
 /// `compose` produces, fire its completion exactly once per call, and never let
 /// more than `maxFramesInFlight` compositions be outstanding.
-@Suite(.enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
+@Suite(.offCooperativePool, .enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
 struct DoviComposeAsyncTests {
 
     private static func makeBuffer(width: Int, height: Int, fill: UInt16) -> CVPixelBuffer? {
diff --git a/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift b/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
index 412b635c0..8a219512a 100644
--- a/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
+++ b/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
@@ -15,7 +15,7 @@ import Dovi
 ///
 /// The path under test is `DoviRpuConverter.separateDualLayers` with a custom block source, whose
 /// `convertedRpu` is the RPU a composed frame carries (what `DoviDisplayMetadata.attach` takes).
-@Suite(.serialized)
+@Suite(.serialized, .offCooperativePool)
 struct DoviComposedFrameRpuTests {
 
     // MARK: - Fixture
diff --git a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
index 47396bdce..2ec1a8c0a 100644
--- a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
@@ -6,6 +6,7 @@ import Dovi
 /// The existing RPU fuzz mostly dies at the CRC check. This one repairs the CRC after mutating the
 /// payload (and re-applies emulation prevention), so the mutated RPU actually reaches libdovi's
 /// parser, which is built panic=abort: any upstream panic here would kill the process.
+@Suite(.offCooperativePool)
 struct DoviCrcValidFuzzTests {
 
     private static let crcTable: [UInt32] = (0..<256).map { i in
diff --git a/Tests/AetherEngineTests/DoviDitherTests.swift b/Tests/AetherEngineTests/DoviDitherTests.swift
index ac2b64f2b..056eac79d 100644
--- a/Tests/AetherEngineTests/DoviDitherTests.swift
+++ b/Tests/AetherEngineTests/DoviDitherTests.swift
@@ -17,6 +17,7 @@ import Metal
 /// scale of 4 that every Dolby Vision stream uses, the two are bit-identical and
 /// no end-to-end test can tell them apart. The centring matters only above that,
 /// and the reason it is there is written out in the shader.
+@Suite(.offCooperativePool)
 struct DoviDitherTests {
 
     static let width = 64
diff --git a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
index e425870e9..331eacc90 100644
--- a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
+++ b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
@@ -6,7 +6,7 @@ import Metal
 /// The enhancement layer is upsampled to the base-layer grid by one hardware bilinear fetch
 /// (`dovi_sample_el_1d`). These tests run the production composer and read the residual back out of the
 /// un-quantised VDR plane, so a different filter (a Catmull-Rom, or nearest) fails them.
-@Suite(.enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
+@Suite(.offCooperativePool, .enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
 struct DoviEnhancementUpsamplerTests {
 
     typealias H = DoviGpuCurveSweepTests
diff --git a/Tests/AetherEngineTests/DoviFelFuzzTests.swift b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
index 0d9c8a0e7..423c0ba49 100644
--- a/Tests/AetherEngineTests/DoviFelFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
@@ -9,6 +9,7 @@ import Dovi
 /// Corrupt and hostile input must degrade (nil parameters, dropped EL, base layer
 /// only), never crash or hang. Seeds are real packets/RPUs from the FEL fixtures;
 /// mutations are deterministic so a failure reproduces.
+@Suite(.offCooperativePool)
 struct DoviFelFuzzTests {
 
     /// SplitMix64: deterministic, no dependence on the system RNG.
diff --git a/Tests/AetherEngineTests/DoviFelMathTests.swift b/Tests/AetherEngineTests/DoviFelMathTests.swift
index 9878d668e..da851f827 100644
--- a/Tests/AetherEngineTests/DoviFelMathTests.swift
+++ b/Tests/AetherEngineTests/DoviFelMathTests.swift
@@ -9,6 +9,7 @@ import Dovi
 /// `DoviFelComposer.compose` with `.debugRawVDR` (12-bit VDR codes, no quantisation) and the real RPU parser.
 /// Nothing here re-implements the kernel's arithmetic: expectations are worked out from the DoViBaker
 /// formulas (erazortt/DoViBaker, `DoViProcessor.cpp`) and written down as numbers.
+@Suite(.offCooperativePool)
 struct DoviFelMathTests {
 
     // Raw 376-byte unspec62 RPU NAL extracted from fel-clip-a.mkv
diff --git a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
index e39d0f257..5278b33f2 100644
--- a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
@@ -6,6 +6,7 @@ import CoreVideo
 /// Hostile parameter blocks and content thrown at the composition kernels. The RPU guard and the
 /// parser should never let such values through, but the kernels are the last line: whatever arrives,
 /// they must neither hang nor write outside the legal output range, and must be deterministic.
+@Suite(.offCooperativePool)
 struct DoviGpuAdversarialTests {
 
     typealias H = DoviGpuCurveSweepTests
diff --git a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
index d142ab989..5ba642d35 100644
--- a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
@@ -14,6 +14,7 @@ import Metal
 /// caught. They are built around the cases a single-piece test cannot see:
 /// per-piece order, per-piece coefficient denominators, and per-piece MMR
 /// coefficients.
+@Suite(.offCooperativePool)
 struct DoviGpuCurveSweepTests {
 
     static let blWidth = 1024
diff --git a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
index e244f73b9..23c2631a7 100644
--- a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
@@ -11,6 +11,7 @@ import Metal
 /// 12-bit VDR (vdr_scale 4), and an NLQ with `scale = 2048`, `shift = 11`, which is
 /// what the real P7 streams carry, so that one EL code of residual is exactly one
 /// VDR code. Dither is off so every expectation is exact.
+@Suite(.offCooperativePool)
 struct DoviGpuEdgeCaseTests {
 
     typealias H = DoviGpuCurveSweepTests
diff --git a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
index b60c8eeb0..2ec24351e 100644
--- a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
+++ b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
@@ -11,6 +11,7 @@ import Metal
 /// of each sub-block back out of the buffer the host actually uploaded: any offset
 /// drift between ``DoviMetalParams/serialize()`` and the shader's struct
 /// definitions moves a sentinel and fails a comparison below.
+@Suite(.offCooperativePool)
 struct DoviLayoutProbeTests {
 
     /// Distinct value per probed field, so a shifted read lands on a value that
diff --git a/Tests/AetherEngineTests/DoviRpuGuardTests.swift b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
index 0610b4bbf..61e407cce 100644
--- a/Tests/AetherEngineTests/DoviRpuGuardTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
@@ -5,6 +5,7 @@ import Dovi
 
 /// libdovi aborts the process on a polynomial piece with linear interpolation. The guard must
 /// see that coming for an RPU whose CRC is perfectly valid, and must not flag real ones.
+@Suite(.offCooperativePool)
 struct DoviRpuGuardTests {
 
     struct BitWriter {
diff --git a/Tests/AetherEngineTests/DoviShaderSyncTests.swift b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
index 2d61883b4..1831287e7 100644
--- a/Tests/AetherEngineTests/DoviShaderSyncTests.swift
+++ b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
@@ -4,6 +4,7 @@ import Metal
 @testable import AetherEngine
 
 /// Guards the Dolby Vision shader source integrity and parameter serialization.
+@Suite(.offCooperativePool)
 struct DoviShaderSyncTests {
 
     static let metalAvailable = MTLCreateSystemDefaultDevice() != nil
diff --git a/Tests/AetherEngineTests/ItemSwapStillTests.swift b/Tests/AetherEngineTests/ItemSwapStillTests.swift
index f9c0f1611..2147daafc 100644
--- a/Tests/AetherEngineTests/ItemSwapStillTests.swift
+++ b/Tests/AetherEngineTests/ItemSwapStillTests.swift
@@ -52,15 +52,19 @@ struct ItemSwapStillTests {
         // then takes nothing more until audio catches up. With a `requestMediaDataWhenReady` block
         // per track that catching up depends on AVFoundation calling the audio block again, and on
         // a loaded CI runner it did not: `video 88/120 ready=false, audio 21/40 ready=true`, the
-        // audio block called once in total, until the deadline below. A loop that waits on one
+        // audio block called once in total, until the deadline. A loop that waits on one
         // track at a time deadlocks the same way from the other side.
         let chunk = 4800
         var frame = 0
         var chunks = 0
         var videoDone = false
         var audioDone = false
-        let deadline = ContinuousClock.now + .seconds(20)
-        while !(videoDone && audioDone), writer.status == .writing, ContinuousClock.now < deadline {
+        // A stall deadline, not a total one: under load the writer can be slow and still moving
+        // (`video 4/120 ready=true, audio 24/40 ready=true` after a fixed 20 s on CI), and only a
+        // writer that takes nothing for 20 s is the deadlock described above.
+        var lastProgress = ContinuousClock.now
+        while !(videoDone && audioDone), writer.status == .writing,
+              ContinuousClock.now - lastProgress < .seconds(20) {
             var fed = false
             if !videoDone, video.isReadyForMoreMediaData {
                 // Our own buffer, not one from the adaptor's pool: that pool belongs to the
@@ -108,7 +112,7 @@ struct ItemSwapStillTests {
                     audioDone = true
                 }
             }
-            if !fed { try await Task.sleep(for: .milliseconds(5)) }
+            if fed { lastProgress = .now } else { try await Task.sleep(for: .milliseconds(5)) }
         }
         guard videoDone, audioDone else {
             let state = "video \(frame)/120 ready=\(video.isReadyForMoreMediaData), "

From f1ba8514ac20314836f82c3e2ffe27a35b6b6d6f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 10:08:14 +0200
Subject: [PATCH 050/132] test: the Dolby Vision compute suites share one lane
 off the pool

069a7a7a moved the #767 suites off the cooperative pool, which fixed the
one-thread job, but `BlockingExecutor` adds a thread per blocked job: their
CPU and GPU loops then all ran at once and took the 3-core runner from the
timing tests beside them (SourceOpenRecovery request count, CancellableLoad
ceiling, the composeAsync outstanding bound, all failing in the plain
`swift test` step that had passed before).

`.offCooperativePoolOneLane` runs them off the pool and one case at a time
across every suite that carries it. `DoviComposeAsyncTests` keeps the plain
trait: its cases are short deadlock watchdogs with one-minute limits, and the
time a case waits for the lane counts against its limit.

Locally, two rounds each: plain step 48-49 s, one-thread step 38-39 s, and
the AE#711 playing capture at 18 s and 7 s (it was 38 s on the one-thread
pool with the suites on it).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../DoviComposedFrameRpuTests.swift           |  2 +-
 .../DoviCrcValidFuzzTests.swift               |  2 +-
 Tests/AetherEngineTests/DoviDitherTests.swift |  2 +-
 .../DoviEnhancementUpsamplerTests.swift       |  2 +-
 .../AetherEngineTests/DoviFelFuzzTests.swift  |  2 +-
 .../AetherEngineTests/DoviFelMathTests.swift  |  2 +-
 .../DoviGpuAdversarialTests.swift             |  2 +-
 .../DoviGpuCurveSweepTests.swift              |  2 +-
 .../DoviGpuEdgeCaseTests.swift                |  2 +-
 .../DoviLayoutProbeTests.swift                |  2 +-
 .../AetherEngineTests/DoviRpuGuardTests.swift |  2 +-
 .../DoviShaderSyncTests.swift                 |  2 +-
 .../Support/OffCooperativePool.swift          | 58 +++++++++++++++++++
 13 files changed, 70 insertions(+), 12 deletions(-)

diff --git a/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift b/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
index 8a219512a..c799d55a1 100644
--- a/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
+++ b/Tests/AetherEngineTests/DoviComposedFrameRpuTests.swift
@@ -15,7 +15,7 @@ import Dovi
 ///
 /// The path under test is `DoviRpuConverter.separateDualLayers` with a custom block source, whose
 /// `convertedRpu` is the RPU a composed frame carries (what `DoviDisplayMetadata.attach` takes).
-@Suite(.serialized, .offCooperativePool)
+@Suite(.serialized, .offCooperativePoolOneLane)
 struct DoviComposedFrameRpuTests {
 
     // MARK: - Fixture
diff --git a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
index 2ec1a8c0a..e570f4061 100644
--- a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
@@ -6,7 +6,7 @@ import Dovi
 /// The existing RPU fuzz mostly dies at the CRC check. This one repairs the CRC after mutating the
 /// payload (and re-applies emulation prevention), so the mutated RPU actually reaches libdovi's
 /// parser, which is built panic=abort: any upstream panic here would kill the process.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviCrcValidFuzzTests {
 
     private static let crcTable: [UInt32] = (0..<256).map { i in
diff --git a/Tests/AetherEngineTests/DoviDitherTests.swift b/Tests/AetherEngineTests/DoviDitherTests.swift
index 056eac79d..5a98ea34f 100644
--- a/Tests/AetherEngineTests/DoviDitherTests.swift
+++ b/Tests/AetherEngineTests/DoviDitherTests.swift
@@ -17,7 +17,7 @@ import Metal
 /// scale of 4 that every Dolby Vision stream uses, the two are bit-identical and
 /// no end-to-end test can tell them apart. The centring matters only above that,
 /// and the reason it is there is written out in the shader.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviDitherTests {
 
     static let width = 64
diff --git a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
index 331eacc90..25a392444 100644
--- a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
+++ b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
@@ -6,7 +6,7 @@ import Metal
 /// The enhancement layer is upsampled to the base-layer grid by one hardware bilinear fetch
 /// (`dovi_sample_el_1d`). These tests run the production composer and read the residual back out of the
 /// un-quantised VDR plane, so a different filter (a Catmull-Rom, or nearest) fails them.
-@Suite(.offCooperativePool, .enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
+@Suite(.offCooperativePoolOneLane, .enabled(if: MTLCreateSystemDefaultDevice() != nil, "needs a Metal device"))
 struct DoviEnhancementUpsamplerTests {
 
     typealias H = DoviGpuCurveSweepTests
diff --git a/Tests/AetherEngineTests/DoviFelFuzzTests.swift b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
index 423c0ba49..72fb9cf71 100644
--- a/Tests/AetherEngineTests/DoviFelFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
@@ -9,7 +9,7 @@ import Dovi
 /// Corrupt and hostile input must degrade (nil parameters, dropped EL, base layer
 /// only), never crash or hang. Seeds are real packets/RPUs from the FEL fixtures;
 /// mutations are deterministic so a failure reproduces.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviFelFuzzTests {
 
     /// SplitMix64: deterministic, no dependence on the system RNG.
diff --git a/Tests/AetherEngineTests/DoviFelMathTests.swift b/Tests/AetherEngineTests/DoviFelMathTests.swift
index da851f827..b647689e4 100644
--- a/Tests/AetherEngineTests/DoviFelMathTests.swift
+++ b/Tests/AetherEngineTests/DoviFelMathTests.swift
@@ -9,7 +9,7 @@ import Dovi
 /// `DoviFelComposer.compose` with `.debugRawVDR` (12-bit VDR codes, no quantisation) and the real RPU parser.
 /// Nothing here re-implements the kernel's arithmetic: expectations are worked out from the DoViBaker
 /// formulas (erazortt/DoViBaker, `DoViProcessor.cpp`) and written down as numbers.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviFelMathTests {
 
     // Raw 376-byte unspec62 RPU NAL extracted from fel-clip-a.mkv
diff --git a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
index 5278b33f2..5c8380987 100644
--- a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
@@ -6,7 +6,7 @@ import CoreVideo
 /// Hostile parameter blocks and content thrown at the composition kernels. The RPU guard and the
 /// parser should never let such values through, but the kernels are the last line: whatever arrives,
 /// they must neither hang nor write outside the legal output range, and must be deterministic.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviGpuAdversarialTests {
 
     typealias H = DoviGpuCurveSweepTests
diff --git a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
index 5ba642d35..910881014 100644
--- a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
@@ -14,7 +14,7 @@ import Metal
 /// caught. They are built around the cases a single-piece test cannot see:
 /// per-piece order, per-piece coefficient denominators, and per-piece MMR
 /// coefficients.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviGpuCurveSweepTests {
 
     static let blWidth = 1024
diff --git a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
index 23c2631a7..2709d8f36 100644
--- a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
@@ -11,7 +11,7 @@ import Metal
 /// 12-bit VDR (vdr_scale 4), and an NLQ with `scale = 2048`, `shift = 11`, which is
 /// what the real P7 streams carry, so that one EL code of residual is exactly one
 /// VDR code. Dither is off so every expectation is exact.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviGpuEdgeCaseTests {
 
     typealias H = DoviGpuCurveSweepTests
diff --git a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
index 2ec24351e..8581033f0 100644
--- a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
+++ b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
@@ -11,7 +11,7 @@ import Metal
 /// of each sub-block back out of the buffer the host actually uploaded: any offset
 /// drift between ``DoviMetalParams/serialize()`` and the shader's struct
 /// definitions moves a sentinel and fails a comparison below.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviLayoutProbeTests {
 
     /// Distinct value per probed field, so a shifted read lands on a value that
diff --git a/Tests/AetherEngineTests/DoviRpuGuardTests.swift b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
index 61e407cce..ff63c5229 100644
--- a/Tests/AetherEngineTests/DoviRpuGuardTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuGuardTests.swift
@@ -5,7 +5,7 @@ import Dovi
 
 /// libdovi aborts the process on a polynomial piece with linear interpolation. The guard must
 /// see that coming for an RPU whose CRC is perfectly valid, and must not flag real ones.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviRpuGuardTests {
 
     struct BitWriter {
diff --git a/Tests/AetherEngineTests/DoviShaderSyncTests.swift b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
index 1831287e7..9e134ce03 100644
--- a/Tests/AetherEngineTests/DoviShaderSyncTests.swift
+++ b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
@@ -4,7 +4,7 @@ import Metal
 @testable import AetherEngine
 
 /// Guards the Dolby Vision shader source integrity and parameter serialization.
-@Suite(.offCooperativePool)
+@Suite(.offCooperativePoolOneLane)
 struct DoviShaderSyncTests {
 
     static let metalAvailable = MTLCreateSystemDefaultDevice() != nil
diff --git a/Tests/AetherEngineTests/Support/OffCooperativePool.swift b/Tests/AetherEngineTests/Support/OffCooperativePool.swift
index 0934aa71a..fc7810f8f 100644
--- a/Tests/AetherEngineTests/Support/OffCooperativePool.swift
+++ b/Tests/AetherEngineTests/Support/OffCooperativePool.swift
@@ -1,4 +1,5 @@
 import Testing
+import Foundation
 @testable import AetherEngine
 
 /// Runs a test's body on `BlockingExecutor` instead of the Swift cooperative pool.
@@ -25,3 +26,60 @@ struct OffCooperativePoolTrait: SuiteTrait, TestTrait, TestScoping {
 extension Trait where Self == OffCooperativePoolTrait {
     static var offCooperativePool: Self { Self() }
 }
+
+/// `.offCooperativePool`, and one test case at a time across every suite that carries it.
+///
+/// For suites whose cases are long CPU or GPU loops rather than parked threads (the Dolby Vision
+/// composer and fuzz suites). Off the pool they no longer starve the one-thread CI job, but
+/// `BlockingExecutor` adds a thread per blocked job, so on their own they all ran at once and
+/// took the 3-core runner from the timing tests beside them. One lane keeps them to one core.
+/// The time a case waits for the lane counts against its `.timeLimit`, so a suite of short
+/// deadlock watchdogs (`DoviComposeAsyncTests`) takes the plain trait instead.
+struct OneLaneOffCooperativePoolTrait: SuiteTrait, TestTrait, TestScoping {
+    var isRecursive: Bool { true }
+
+    func provideScope(for test: Test, testCase: Test.Case?,
+                      performing function: @Sendable () async throws -> Void) async throws {
+        guard testCase != nil else { return try await function() }
+        await OneLane.shared.acquire()
+        defer { OneLane.shared.release() }
+        try await OffCooperativePoolTrait().provideScope(for: test, testCase: testCase, performing: function)
+    }
+}
+
+extension Trait where Self == OneLaneOffCooperativePoolTrait {
+    static var offCooperativePoolOneLane: Self { Self() }
+}
+
+private final class OneLane: @unchecked Sendable {
+    static let shared = OneLane()
+    private let lock = NSLock()
+    private var busy = false
+    private var waiters: [CheckedContinuation<Void, Never>] = []
+
+    func acquire() async {
+        await withCheckedContinuation { (turn: CheckedContinuation<Void, Never>) in
+            lock.lock()
+            if busy {
+                waiters.append(turn)
+                lock.unlock()
+            } else {
+                busy = true
+                lock.unlock()
+                turn.resume()
+            }
+        }
+    }
+
+    func release() {
+        lock.lock()
+        if waiters.isEmpty {
+            busy = false
+            lock.unlock()
+        } else {
+            let next = waiters.removeFirst()
+            lock.unlock()
+            next.resume()
+        }
+    }
+}

From f99c574e36a998862e33f0365586d771ea5744de Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 10:28:44 +0200
Subject: [PATCH 051/132] fix(dovi): #768 follow-up: bounded parameter-set ids,
 stall guard jumps the gap

- HEVCPictureOrderCount stores an SPS only with an id up to 15 and a PPS only
  with an id up to 63 naming an SPS up to 15 (7.4.3.2, 7.4.3.3). The maps were
  keyed by an unchecked ue(v), so a stream repeating parameter sets with fresh
  ids grew them by one entry per NAL. Test included.
- OrderedDelivery's stall guard moves the head straight to the oldest pending
  ticket instead of one missing number per turn. Same frames skipped, but a
  backlog far ahead of the head no longer spins the delivery queue.
- docs/architecture.md lists the four new files.
- The real-clip suites (DualLayerPictureAlignmentTests, DoviFelRealFileTests)
  demux whole files synchronously and now take `.offCooperativePoolOneLane`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Decoder/OrderedDelivery.swift    |  8 +++++++-
 .../AetherEngine/Video/HEVCPictureOrderCount.swift    |  6 ++++--
 Tests/AetherEngineTests/DoviFelRealFileTests.swift    |  1 +
 .../DualLayerPictureAlignmentTests.swift              |  1 +
 .../HEVCPictureOrderCountTests.swift                  | 11 +++++++++++
 docs/architecture.md                                  |  4 ++++
 6 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Decoder/OrderedDelivery.swift b/Sources/AetherEngine/Decoder/OrderedDelivery.swift
index 35da8b13e..3e0009a86 100644
--- a/Sources/AetherEngine/Decoder/OrderedDelivery.swift
+++ b/Sources/AetherEngine/Decoder/OrderedDelivery.swift
@@ -258,7 +258,13 @@ final class OrderedDelivery: @unchecked Sendable {
                     category: .swPlayback)
                 stallLogPending = true
             }
-            nextToEmit &+= 1
+            // Straight to the oldest frame that did arrive: stepping one missing ticket per turn
+            // spins the queue once per number when the backlog sits far ahead of the head.
+            guard let oldest = pending.keys.min(), oldest > nextToEmit else {
+                nextToEmit &+= 1
+                continue
+            }
+            nextToEmit = oldest
         }
     }
 
diff --git a/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift b/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift
index 49dfa5ff1..6681934a1 100644
--- a/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift
+++ b/Sources/AetherEngine/Video/HEVCPictureOrderCount.swift
@@ -78,7 +78,9 @@ struct HEVCPictureOrderCount {
         for p in present {
             guard r.skip(p.profile ? 88 : 0), r.skip(p.level ? 8 : 0) else { return }
         }
-        guard let id = r.ue(), let chroma = r.ue() else { return }
+        // sps_seq_parameter_set_id is at most 15 and pps_pic_parameter_set_id at most 63 (7.4.3.2,
+        // 7.4.3.3): a stream naming more would otherwise grow these maps by one entry per NAL.
+        guard let id = r.ue(), id <= 15, let chroma = r.ue() else { return }
         var separate = false
         if chroma == 3 { guard let f = r.flag() else { return }; separate = f }
         guard r.ue() != nil, r.ue() != nil, let window = r.flag() else { return }   // width, height
@@ -89,7 +91,7 @@ struct HEVCPictureOrderCount {
 
     private mutating func parsePPS(_ nal: UnsafePointer<UInt8>, _ len: Int) {
         var r = Self.reader(nal, len, limit: 32)
-        guard let id = r.ue(), let spsID = r.ue(), r.flag() != nil,   // dependent_slice_segments_enabled
+        guard let id = r.ue(), id <= 63, let spsID = r.ue(), spsID <= 15, r.flag() != nil,   // dependent_slice_segments_enabled
               let outputFlag = r.flag(), let extra = r.u(3) else { return }
         pps[id] = PPS(sps: spsID, outputFlagPresent: outputFlag, extraSliceHeaderBits: extra)
     }
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
index 992f4bd41..0e326ecb8 100644
--- a/Tests/AetherEngineTests/DoviFelRealFileTests.swift
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -9,6 +9,7 @@ import Foundation
 /// The fixtures (`fel-clip-a.mkv`, `fel-clip-b.mkv`, `fel-clip-c.mp4`) live in the
 /// directory named by `DV_FEL_TESTS_DIR`, or in `DV FEL Tests/` next to the package;
 /// they are not checked in, and every test skips when its file is absent.
+@Suite(.offCooperativePoolOneLane)
 struct DoviFelRealFileTests {
 
     static let fixtures = [
diff --git a/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift b/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
index dcd78572f..8ca3ea0ee 100644
--- a/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
+++ b/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
@@ -10,6 +10,7 @@ import AetherLibavutil
 /// (counting from the decoded POCs gives 2823: that also counts the last unit, whose EL is a lone IDR
 /// that pairs with its own BL picture but ranks two places off because two EL-less units precede it);
 /// the others share one GOP.
+@Suite(.offCooperativePoolOneLane)
 struct DualLayerPictureAlignmentTests {
 
     struct Walk {
diff --git a/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift b/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift
index 0826c231e..c4b67f057 100644
--- a/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift
+++ b/Tests/AetherEngineTests/HEVCPictureOrderCountTests.swift
@@ -310,6 +310,17 @@ struct HEVCPictureOrderCountTests {
         c.feedParameterSets([B.sps(pocLsbBits: 17), B.pps()])
         #expect(Self.feed(&c, B.slice(type: T.idrNLP, pocLsbBits: 17)) == nil)
     }
+
+    @Test("parameter set ids beyond the spec's 15 (SPS) and 63 (PPS) are not stored")
+    func rejectsOutOfRangeParameterSetIDs() {
+        var c = HEVCPictureOrderCount()
+        c.feedParameterSets([B.sps(id: 16, pocLsbBits: 8), B.pps(id: 1, spsID: 16), B.pps(id: 64, spsID: 0),
+                             B.sps(id: 0, pocLsbBits: 8)])
+        #expect(Self.feed(&c, B.slice(type: T.idrNLP, ppsID: 1, pocLsbBits: 8)) == nil, "PPS 1 names SPS 16")
+        #expect(Self.feed(&c, B.slice(type: T.idrNLP, ppsID: 64, pocLsbBits: 8)) == nil, "PPS 64 was not stored")
+        c.feedParameterSets([B.pps(id: 63, spsID: 15), B.sps(id: 15, pocLsbBits: 8)])
+        #expect(Self.feed(&c, B.slice(type: T.idrNLP, ppsID: 63, pocLsbBits: 8)) == .init(poc: 0, startsSequence: true))
+    }
 }
 
 private extension Array where Element == UInt8 {
diff --git a/docs/architecture.md b/docs/architecture.md
index 3746316d2..09a85edac 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -407,6 +407,9 @@ Sources/AetherEngine/
 ├── Decoder/
 │   ├── A53ReorderBuffer.swift               Decode-to-presentation reorder for SEI caption groups (#131)
 │   ├── A53SEIParser.swift                   A53/GA94 cc_data extraction from H.264/HEVC SEI NALs (#131)
+│   ├── DualLayerPictureAlignment.swift      SW FEL path (not routed yet): pairs each EL picture with the base picture of the same display slot (POC), falling back to access-unit pairing (#702)
+│   ├── FrameSideDataRing.swift              SW FEL path (not routed yet): fixed ring of per-frame RPU parameters and display metadata keyed by timestamp (#702)
+│   ├── OrderedDelivery.swift                SW FEL path (not routed yet): hands composed frames from the Metal completion queue to the renderer in decode order, with an epoch for seeks and a stall guard (#702)
 │   ├── CCDataParser.swift                   Parses the bare cc_data triplet stream from a demuxable CEA-608 caption track (#77)
 │   ├── CEA608Decoder.swift                  In-house CEA-608 line-21 decoder (field-1 / CC1), validated against FFmpeg ccaption_dec.c (#77)
 │   ├── DeinterlaceFilter.swift              SW path: persistent bwdif / yadif libavfilter graph, engages on the first interlaced frame
@@ -542,6 +545,7 @@ Sources/AetherEngine/
 │   ├── 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               libdovi RPU surgery for both routes. Native path: per-packet Profile 7 → 8.1 rewrite (convert type-62 RPU, drop type-63 EL). SW FEL path: `separateDualLayers` also lifts the EL into its own packet and returns the composer's reshaping parameters plus the 8.1 RPU attached as display metadata
 │   ├── DoviRpuConverter+Probe.swift         Diagnostic DV-conversion probe (`doviConvertProbe` / `DoviConvertProbeResult`), backs `aetherctl dovitest`
+│   ├── HEVCPictureOrderCount.swift          H.265 picture order count (8.3.1) of one layer from parameter sets and first slice headers, no decoding; nil for anything it cannot follow (#702)
 │   ├── DoviDisplayMetadata.swift            SW FEL path: sets `DolbyVisionRPUData` (the Profile 8.1 RPU minus its NAL header) and `DolbyCompatibilityID` (the CFString "1", never a number) on every emitted buffer, or clears both; tvOS consumes them in backboardd
 │   ├── Metal/
 │   │   ├── DoviFelComposer.swift            BL + EL + RPU composition: runtime-compiled pipelines, pooled P010 output, `composeAsync` bounded at `maxFramesInFlight` with completions on its own serial queue; RPU → `DoviMetalParams` parsing

From af54104d09a4912d95250f9005829d9efb9545bc Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 11:08:26 +0200
Subject: [PATCH 052/132] test: keep the #769 suites off the cooperative pool,
 drop two arrival races

- The dual-layer decoder suites and DoviCpuModelTests block on VideoToolbox
  and Metal; they run under .offCooperativePoolOneLane like the other DoVi
  compute suites, so the one-thread CI step keeps its pool thread.
- The packet balance check compared the process-wide PacketBalanceTracker
  against an exact baseline while other suites allocate packets; it now
  decodes 256 packets and bounds the drift, which a per-decode leak exceeds.
- Issue220 readAtEOFDoesNotConnect counted requests, and under load the
  open's speculative tail fetch landed after the settle window. It now
  asserts that no request starts at the file size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngineTests/DoviCpuModelTests.swift |  1 +
 .../DualLayerGpuSlotWaitTests.swift           |  2 +-
 .../DualLayerSeekRealignmentTests.swift       |  2 +-
 .../DualLayerStreamClassificationTests.swift  |  2 +-
 .../DualLayerVideoDecoderTests.swift          | 30 ++++++++++---------
 .../Issue220BoundedRangeTests.swift           |  5 ++--
 6 files changed, 23 insertions(+), 19 deletions(-)

diff --git a/Tests/AetherEngineTests/DoviCpuModelTests.swift b/Tests/AetherEngineTests/DoviCpuModelTests.swift
index 9d2786ed5..c407b2c29 100644
--- a/Tests/AetherEngineTests/DoviCpuModelTests.swift
+++ b/Tests/AetherEngineTests/DoviCpuModelTests.swift
@@ -15,6 +15,7 @@ import CoreVideo
 /// What it settles: arithmetic, piece selection, MMR term layout, NLQ, clamps. What it cannot: the
 /// spec readings the shader and the model share by construction (the chroma-site luma filter, the
 /// half-step NLQ reconstruction); those were settled against DoViBaker, an independent implementation.
+@Suite(.offCooperativePoolOneLane)
 struct DoviCpuModelTests {
 
     // MARK: - Planes
diff --git a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
index 2a494c1ed..49f507ff1 100644
--- a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
+++ b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
@@ -11,7 +11,7 @@ import Foundation
 /// `acquireSlot()` with no lock held, so `flush()` returns promptly. On the
 /// pre-fix code the wait sat inside `composeAsync` while the VideoToolbox
 /// thread held the decoder lock, and `flush()` hung behind it.
-@Suite(.serialized, .timeLimit(.minutes(1)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(1)))
 struct DualLayerGpuSlotWaitTests {
 
     /// Fake composer with an in-flight limit of 1. The first composition's
diff --git a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
index 79f5ae60d..015eb6eb4 100644
--- a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
+++ b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
@@ -11,7 +11,7 @@ import AetherLibavformat
 /// the side-data ring, and a seek lands on timestamps the pre-seek frames may already have used (a
 /// backward seek replays the same PTS keys). These tests drive the frame handlers with tagged
 /// synthetic buffers and check what the composer was asked to pair and what reached `onFrame`.
-@Suite(.serialized, .timeLimit(.minutes(2)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(2)))
 struct DualLayerSeekRealignmentTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
index 5fcadd62c..257f7c9d2 100644
--- a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
+++ b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
@@ -10,7 +10,7 @@ import AetherLibavcodec
 /// the enhancement decoder opens. A per-frame `disable_residual_flag` is a kernel flag
 /// (`DoviComposerFlags.disableResidual`, honoured by the composer) and must never shut
 /// off the enhancement layer for the rest of the session.
-@Suite(.serialized, .timeLimit(.minutes(1)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(1)))
 struct DualLayerStreamClassificationTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 2cce66221..62f564378 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -15,7 +15,7 @@ import Dovi
 /// asynchronously. These tests drive the two frame handlers directly with synthetic P010 buffers,
 /// using `primeForTesting` / `seedRPUForTesting` to stand in for what `decode(packet:)` sets up, so
 /// the pairing, ordering, metadata and flush behaviour is covered without a real stream.
-@Suite(.serialized, .timeLimit(.minutes(2)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(2)))
 struct DualLayerVideoDecoderTests {
 
     // MARK: - Fixtures
@@ -2552,8 +2552,6 @@ struct DualLayerVideoDecoderTests {
 
     @Test("DualLayerVideoDecoder reports streamClassification accurately and balances packets")
     func fel22StreamClassificationAndPacketBalance() throws {
-        let aliveBefore = PacketBalanceTracker.alive
-
         let primary = CountingFakeDecoder()
         let enhancement = CountingFakeDecoder()
         let decoder = DualLayerVideoDecoder(
@@ -2565,27 +2563,31 @@ struct DualLayerVideoDecoderTests {
 
         #expect(decoder.streamClassification == .undetermined)
 
-        // Feed a MEL packet
+        // Feed MEL packets
         let vps = Self.hevcNAL(type: 32, payload: [0x0c, 0x01, 0xff, 0xff])
         let sps = Self.hevcNAL(type: 33, payload: [0x01, 0x02, 0x20, 0x00])
         let pps = Self.hevcNAL(type: 34, payload: [0xc0, 0x73])
         let bl = Self.hevcNAL(type: 1, payload: [0x11, 0x22, 0x33, 0x44])
         let melRpu = Self.makeMelRpuBytes()
 
-        guard let melPkt = Self.makeAvccPacket([vps, sps, pps, bl, melRpu], pts: 1000) else {
-            Issue.record("Failed to make MEL packet")
-            return
+        // PacketBalanceTracker is process-wide and other suites allocate packets concurrently, so an
+        // exact baseline is a race. A packet leaked per decode shows up as one per iteration instead,
+        // far above what the rest of the run keeps in flight.
+        let iterations = 256
+        let aliveBefore = PacketBalanceTracker.alive
+        for i in 0..<iterations {
+            guard let melPkt = Self.makeAvccPacket([vps, sps, pps, bl, melRpu], pts: 1000 + Int64(i) * 1001) else {
+                Issue.record("Failed to make MEL packet")
+                return
+            }
+            decoder.decode(packet: melPkt)
+            var optMel: UnsafeMutablePointer<AVPacket>? = melPkt
+            trackedPacketFree(&optMel)
         }
 
-        decoder.decode(packet: melPkt)
-
-        var optMel: UnsafeMutablePointer<AVPacket>? = melPkt
-        trackedPacketFree(&optMel)
-
         // Classification must be MEL, not FEL
         #expect(decoder.streamClassification == .mel)
 
-        // PacketBalanceTracker must return to baseline
-        #expect(PacketBalanceTracker.alive == aliveBefore)
+        #expect(PacketBalanceTracker.alive - aliveBefore < iterations / 2)
     }
 }
diff --git a/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift b/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift
index cf81ed873..5988d3b17 100644
--- a/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift
+++ b/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift
@@ -124,12 +124,13 @@ struct Issue220BoundedRangeTests {
         // speculative tail fetch is issued concurrently and would otherwise arrive afterwards and
         // read as a connection this EOF read opened.
         try await waitForOriginToSettle(server)
-        let requestsBefore = server.rangeRequestCount
 
         #expect(reader.seek(offset: size, whence: SEEK_SET) == size)
         #expect(reader.read(into: buf, size: 4096) == FFmpegErr.eof)
         try await waitForOriginToSettle(server)
-        #expect(server.rangeRequestCount == requestsBefore,
+        // On the ranges, not the count: under load the open's speculative tail fetch can land after
+        // the settle window, and it is not a connection for the EOF read. That one asks for `size-`.
+        #expect(server.requestedRanges.allSatisfy { $0.start < size },
                 "a read at EOF opened a connection: \(server.requestedRanges)")
     }
 

From 495c8a6c491e40ef1181444f7230b251a916638c Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Thu, 15 Oct 2026 10:20:24 +0100
Subject: [PATCH 053/132] fix(decoder): makeBlockBuffer's failure path cannot
 release the block source twice

---
 .../AetherEngine/Decoder/HardwareVideoDecoder.swift    | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 7823a08b8..4e322adaa 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -150,6 +150,10 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     final class CustomBlockSource {
         var avBuf: UnsafeMutablePointer<AVBufferRef>?
         let dataPtr: UnsafeMutableRawPointer
+        /// Set by the block source's `FreeBlock`, which releases the retain the refCon carries. CoreMedia
+        /// may call it from inside a failed `CMBlockBufferCreateWithMemoryBlock` (after `AllocateBlock`),
+        /// and `makeBlockBuffer` must then not release that retain a second time.
+        var freeBlockRan = false
 
         /// `data` is the packet's own payload pointer. It is not always `buf->data`: the Matroska
         /// demuxer hands out packets whose `data` sits inside a larger buffer (observed at +4 on P7
@@ -188,6 +192,7 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             FreeBlock: { refCon, _memoryBlock, _size in
                 guard let refCon else { return }
                 let holder = Unmanaged<CustomBlockSource>.fromOpaque(refCon).takeRetainedValue()
+                holder.freeBlockRan = true
                 holder.releaseBuffer()
             },
             refCon: Unmanaged.passRetained(blockSource).toOpaque()
@@ -204,7 +209,10 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             flags: kCMBlockBufferAssureMemoryNowFlag,
             blockBufferOut: &blockBuffer
         )
-        if status != kCMBlockBufferNoErr, let refCon = source.refCon {
+        // `blockSource` is still held by this frame, so reading the flag is safe even after FreeBlock
+        // dropped the refCon's retain. On a failure CoreMedia calls FreeBlock synchronously or not at
+        // all; release here only in the second case.
+        if status != kCMBlockBufferNoErr, !blockSource.freeBlockRan, let refCon = source.refCon {
             Unmanaged<CustomBlockSource>.fromOpaque(refCon).takeRetainedValue().releaseBuffer()
         }
         return (blockBuffer, status)

From 42bc6051765c7e7c4a089e9b4dbfe5eeaf775ab2 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Thu, 15 Oct 2026 10:20:24 +0100
Subject: [PATCH 054/132] refactor(decoder): end-of-stream drain on the
 pipeline protocol; FEL route counts as VideoToolbox; epoch-adoption and
 drain-dispatch tests

---
 CHANGELOG.md                                  |  3 +
 .../Decoder/VideoDecoderTypes.swift           |  8 +++
 .../Native/SoftwarePlaybackHost.swift         | 13 ++--
 .../ActiveVideoDecoderTests.swift             | 11 ++++
 .../DualLayerVideoDecoderTests.swift          | 61 +++++++++++++++++++
 5 files changed, 92 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f6644297f..cee31d610 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,9 @@ the public-API contract.
 
 ### Fixed
 
+- **The Profile 7 dual-layer route reports VideoToolbox as its decoder** (#760). `activeVideoDecoder` and the software/hardware flag counted the single-layer VideoToolbox decoder only, so a title on the FEL route was labelled as software decoded.
+- **A failed `CMBlockBuffer` creation around a packet's payload no longer releases the packet reference twice** when CoreMedia has already freed the block source from inside the failing call.
+
 - **FLAC with blocks under 192 samples plays instead of failing to open** (#764). An MKV whose FLAC used
   small fixed blocks (`STREAMINFO` min = max = 144, 48 kHz stereo) died on the native path with
   `-11829 "Cannot Open"` (underlying `-12848`), and the same stream in a plain `.flac` file failed the
diff --git a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
index 800ba93ce..9702c8055 100644
--- a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
+++ b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
@@ -37,9 +37,17 @@ protocol VideoDecodingPipeline: AnyObject, Sendable {
     /// `nil` from a caller with no seek of its own to be invalidated by.
     func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?)
     func flush()
+    /// End of source or a live seam: delivers what the decoder still owes before the `flush()` the host
+    /// makes next. `flush()` of a decoder that delivers what it drains is enough, so the default does
+    /// nothing; a decoder whose `flush()` discards (the dual-layer one) overrides it. Seeks never call it.
+    func drainForEndOfStream()
     func close()
 }
 
+extension VideoDecodingPipeline {
+    func drainForEndOfStream() {}
+}
+
 enum VideoDecoderError: Error, LocalizedError {
     case noCodecParameters
     case unsupportedCodec(id: UInt32)
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index b2b7ddbbd..b4b2fa3c3 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -125,7 +125,12 @@ final class SoftwarePlaybackHost {
 
     /// Whether load selected VideoToolbox rather than libavcodec / dav1d for video decoding.
     /// Only meaningful after load has returned successfully.
-    var usesHardwareVideoDecoder: Bool { videoDecoder is HardwareVideoDecoder }
+    var usesHardwareVideoDecoder: Bool { Self.isVideoToolboxDecoder(videoDecoder) }
+
+    /// The FEL route's dual-layer decoder runs two VideoToolbox sessions, so it counts as hardware.
+    static func isVideoToolboxDecoder(_ decoder: any VideoDecodingPipeline) -> Bool {
+        decoder is HardwareVideoDecoder || decoder is DualLayerVideoDecoder
+    }
 
     /// AE#711 follow-up: the picture on screen now, read back from the renderer before a rebuild's
     /// `stop()` flushes it, so the engine can hold it over the new host's startup. Falls back to the
@@ -2649,7 +2654,7 @@ final class SoftwarePlaybackHost {
                 // next append, or finish when the source is gone and the
                 // ring is fully drained.
                 if sourceEnded() {
-                    (videoDecoder as? DualLayerVideoDecoder)?.drainForEndOfStream()
+                    videoDecoder.drainForEndOfStream()
                     videoDecoder.flush()
                     audioDecoder?.flush()
                     renderer.drainReorderBuffer()
@@ -3170,7 +3175,7 @@ final class SoftwarePlaybackHost {
                 freeParkedVideo()
                 // The dual-layer decoder's flush drops what its sessions and the GPU still hold,
                 // which here is the last frames of the stream: hand those over first.
-                (videoDecoder as? DualLayerVideoDecoder)?.drainForEndOfStream()
+                videoDecoder.drainForEndOfStream()
                 videoDecoder.flush()
                 audioDecoder?.flush()
                 renderer.drainReorderBuffer()
@@ -3200,7 +3205,7 @@ final class SoftwarePlaybackHost {
                         // its reference chain; the seam packet itself parks after this block.
                         waitForRenderer(.drainAll)
                         freeParkedVideo()
-                        (videoDecoder as? DualLayerVideoDecoder)?.drainForEndOfStream()
+                        videoDecoder.drainForEndOfStream()
                         videoDecoder.flush()
                         // AE#492: this flush is THIS thread's, made after the read and on behalf of
                         // the packet in hand. Retiring that packet along with the seam it opens
diff --git a/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift b/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift
index 8c17146a4..d4efe788e 100644
--- a/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/ActiveVideoDecoderTests.swift
@@ -62,4 +62,15 @@ struct ActiveVideoDecoderTests {
     func softwareAV1() async throws {
         try await checkLoadAndReload("av1.mp4", label: "dav1d AV1 (SW)")
     }
+
+    @Test("both VideoToolbox decoders, the dual-layer one included, report as hardware (#760)",
+          .timeLimit(.minutes(1)))
+    func videoToolboxDecodersCountAsHardware() {
+        let single = HardwareVideoDecoder()
+        let dual = DualLayerVideoDecoder(composer: nil)
+        defer { dual.close() }
+        #expect(SoftwarePlaybackHost.isVideoToolboxDecoder(single))
+        #expect(SoftwarePlaybackHost.isVideoToolboxDecoder(dual))
+        #expect(!SoftwarePlaybackHost.isVideoToolboxDecoder(SoftwareVideoDecoder()))
+    }
 }
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 34fea6930..79c17c014 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -988,6 +988,67 @@ struct DualLayerVideoDecoderTests {
         #expect(!decoder.rebuildSession())
     }
 
+    @Test("after a session rebuild both layers are back on the decoder's epoch, so later packets are accepted")
+    func rebuildAdoptsFeedEpoch() {
+        let primary = EpochRecordingFakeDecoder()
+        let enhancement = EpochRecordingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: enhancement
+        )
+        defer { decoder.close() }
+        decoder.flush()
+        let epoch = decoder.feedEpoch
+        #expect(epoch > 0)
+        // A rebuilt hardware decoder moves its own epoch; the dual decoder must put it back.
+        primary.epoch = epoch &+ 7
+        enhancement.epoch = epoch &+ 9
+        #expect(decoder.rebuildSession())
+        #expect(primary.epoch == epoch)
+        #expect(enhancement.epoch == epoch)
+        #expect(decoder.feedEpoch == epoch)
+    }
+
+    @Test("the host's drain reaches the dual-layer decoder through the pipeline protocol; a plain decoder's is a no-op")
+    func drainDispatchesThroughProtocol() {
+        let primary = FlushEmittingFakeDecoder()
+        let decoder = DualLayerVideoDecoder(
+            composer: ImmediateFakeComposer(),
+            primaryDecoder: primary,
+            enhancementDecoder: nil
+        )
+        defer { decoder.close() }
+        var flushedByDrain = 0
+        primary.emitFromInsideFlush = { flushedByDrain += 1 }
+        let pipeline: any VideoDecodingPipeline = decoder
+        pipeline.drainForEndOfStream()
+        #expect(flushedByDrain == 1)
+        // A decoder whose flush delivers needs no drain.
+        let plain: any VideoDecodingPipeline = FlushEmittingFakeDecoder()
+        plain.drainForEndOfStream()
+    }
+
+    private final class EpochRecordingFakeDecoder: SingleLayerVideoDecoder, @unchecked Sendable {
+        var onFrame: DecodedFrameHandler?
+        var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
+        var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+        var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+        var skipUntilPTS: CMTime?
+        var epoch: UInt64 = 0
+        var feedEpoch: UInt64 { epoch }
+        func open(stream: UnsafeMutablePointer<AVStream>, onFrame: @escaping DecodedFrameHandler) throws {
+            self.onFrame = onFrame
+        }
+        func open(parameterSets: [[UInt8]], timeBase: AVRational, onFrame: @escaping DecodedFrameHandler) throws {
+            self.onFrame = onFrame
+        }
+        func decode(packet: UnsafeMutablePointer<AVPacket>, epoch: UInt64?) {}
+        func flush() {}
+        func adoptFeedEpoch(_ epoch: UInt64) { self.epoch = epoch }
+        func close() { onFrame = nil }
+    }
+
     private final class SessionLossCount: @unchecked Sendable {
         private let lock = NSLock()
         private var count = 0

From eb4f16ff923a3d64150e49741001682f2f1bbe45 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 11:22:29 +0200
Subject: [PATCH 055/132] docs: drop the dolby-vision-fel.md link until #770
 adds the page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/architecture.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index bd54b20eb..e6d17c1e9 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -417,7 +417,7 @@ Sources/AetherEngine/
 │   ├── InterlaceProbe.swift                 Decodes a sample and applies the deinterlacer's own engagement predicate, so a declared field order that no frame backs up (PsF) stops costing a SW decode (#232)
 │   ├── VideoRoutingPolicy.swift             Pure codec-and-field-order dispatch rule: AV1 gated on HW, VP9/VP8/MPEG4/MPEG2/VC1 always SW, interlaced H.264 SW so bwdif can deinterlace (#107, verified against decoded frames on VOD, #232), plus a second-stage gate routing H.264 High 4:2:2/4:4:4/10 + HEVC Rext to SW where VideoToolbox has no HW decoder (#2)
 │   ├── HardwareVideoDecoder.swift           SW path: VideoToolbox HW HEVC / AV1 decoder for sources routed away from AVPlayer
-│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL. Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame; see [dolby-vision-fel.md](dolby-vision-fel.md)
+│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL. Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame
 │   ├── SoftwareVideoDecoder.swift           SW path: libavcodec/dav1d → CVPixelBuffer (NV12 / P010), HDR10+ side data
 │   ├── SubtitleDecoder.swift                Sidecar URL one-shot decode (text only); decodes several streams of one container in a single pass (#266)
 │   ├── VideoDecoderTypes.swift              DecodedFrameHandler typealias + VideoDecoderError

From 48acb61144e3b451c55d856de837ff4374b43a46 Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Thu, 15 Oct 2026 10:32:04 +0100
Subject: [PATCH 056/132] test(dovi): drop the task-scoped packet balance,
 unused since main bounds the drift instead

---
 .../Diagnostics/PacketBalanceTracker.swift    | 45 -------------------
 1 file changed, 45 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift b/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift
index f1fbff4f9..aae511efa 100644
--- a/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift
+++ b/Sources/AetherEngine/Diagnostics/PacketBalanceTracker.swift
@@ -14,18 +14,12 @@ enum PacketBalanceTracker {
         lock.lock()
         _allocs &+= 1
         lock.unlock()
-        #if DEBUG
-        scope?.recordAlloc()
-        #endif
     }
 
     static func recordFree() {
         lock.lock()
         _frees &+= 1
         lock.unlock()
-        #if DEBUG
-        scope?.recordFree()
-        #endif
     }
 
     static var alive: Int {
@@ -39,45 +33,6 @@ enum PacketBalanceTracker {
         defer { lock.unlock() }
         return _allocs
     }
-
-    #if DEBUG
-    /// The allocs and frees made by one task and the synchronous calls it makes. `alive` is
-    /// process-wide, so a test that compares it before and after reads every other test running in
-    /// parallel; a leak check scoped to the test's own task does not.
-    final class Scope: @unchecked Sendable {
-        private let lock = NSLock()
-        private var allocs = 0
-        private var frees = 0
-
-        var alive: Int {
-            lock.lock()
-            defer { lock.unlock() }
-            return allocs - frees
-        }
-
-        fileprivate func recordAlloc() {
-            lock.lock()
-            allocs &+= 1
-            lock.unlock()
-        }
-
-        fileprivate func recordFree() {
-            lock.lock()
-            frees &+= 1
-            lock.unlock()
-        }
-    }
-
-    @TaskLocal static var scope: Scope?
-
-    /// Runs `body` with a fresh `Scope` and returns it. Work `body` hands to another queue or thread
-    /// is not counted.
-    static func measure(_ body: () throws -> Void) rethrows -> Scope {
-        let scope = Scope()
-        try $scope.withValue(scope) { try body() }
-        return scope
-    }
-    #endif
 }
 
 /// Drop-in for av_packet_alloc() that records the alloc in PacketBalanceTracker.

From d3ff33e88613d966a50245efbfee616dfa6063c4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 11:38:46 +0200
Subject: [PATCH 057/132] fix(dovi): label the dual-layer route as hardware
 decode, log the no-Metal fallback

- usesHardwareVideoDecoder counted only HardwareVideoDecoder, so a session on
  the dual-layer route (VideoToolbox on both layers) published
  'libavcodec HEVC (SW)' as its decoder.
- With no Metal device the host fell back to the base layer alone without a
  line, after the engine had already logged the route as taken.
- docs/architecture.md links dolby-vision-fel.md again, now that the page
  exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift | 3 ++-
 docs/architecture.md                                   | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 4c916ca34..35f21a06f 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -125,7 +125,7 @@ final class SoftwarePlaybackHost {
 
     /// Whether load selected VideoToolbox rather than libavcodec / dav1d for video decoding.
     /// Only meaningful after load has returned successfully.
-    var usesHardwareVideoDecoder: Bool { videoDecoder is HardwareVideoDecoder }
+    var usesHardwareVideoDecoder: Bool { videoDecoder is HardwareVideoDecoder || videoDecoder is DualLayerVideoDecoder }
 
     /// AE#711 follow-up: the picture on screen now, read back from the renderer before a rebuild's
     /// `stop()` flushes it, so the engine can hold it over the new host's startup. Falls back to the
@@ -909,6 +909,7 @@ final class SoftwarePlaybackHost {
                 if let composer = DoviFelComposer() {
                     return DualLayerVideoDecoder(composer: composer)
                 }
+                EngineLog.emit("[SWHost] DV P7 dual-layer route: no Metal device for the composer, decoding the base layer alone", category: .swPlayback)
                 return HardwareVideoDecoder()
             } else {
                 return HardwareVideoDecoder()
diff --git a/docs/architecture.md b/docs/architecture.md
index e6d17c1e9..bd54b20eb 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -417,7 +417,7 @@ Sources/AetherEngine/
 │   ├── InterlaceProbe.swift                 Decodes a sample and applies the deinterlacer's own engagement predicate, so a declared field order that no frame backs up (PsF) stops costing a SW decode (#232)
 │   ├── VideoRoutingPolicy.swift             Pure codec-and-field-order dispatch rule: AV1 gated on HW, VP9/VP8/MPEG4/MPEG2/VC1 always SW, interlaced H.264 SW so bwdif can deinterlace (#107, verified against decoded frames on VOD, #232), plus a second-stage gate routing H.264 High 4:2:2/4:4:4/10 + HEVC Rext to SW where VideoToolbox has no HW decoder (#2)
 │   ├── HardwareVideoDecoder.swift           SW path: VideoToolbox HW HEVC / AV1 decoder for sources routed away from AVPlayer
-│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL. Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame
+│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL. Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame; see [dolby-vision-fel.md](dolby-vision-fel.md)
 │   ├── SoftwareVideoDecoder.swift           SW path: libavcodec/dav1d → CVPixelBuffer (NV12 / P010), HDR10+ side data
 │   ├── SubtitleDecoder.swift                Sidecar URL one-shot decode (text only); decodes several streams of one container in a single pass (#266)
 │   ├── VideoDecoderTypes.swift              DecodedFrameHandler typealias + VideoDecoderError

From adb554f4ad06e2947379a9ad6fa265d79eaca6ef Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Thu, 15 Oct 2026 10:48:38 +0100
Subject: [PATCH 058/132] docs(changelog): session-loss recovery and
 end-of-stream drain on the dual-layer route

---
 CHANGELOG.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ca1a2ca0..142fcbded 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,8 @@ the public-API contract.
 
 ### Fixed
 
+- **The Profile 7 dual-layer route recovers from a system session loss (#739).** A screen lock or sleep invalidates both VideoToolbox sessions; the host's recovery reached only `HardwareVideoDecoder`, so on the route audio played on over a frozen picture. `DualLayerVideoDecoder` now reports one loss per event, rebuilds both sessions and re-adopts its feed epoch; the host reaches it through the new internal `VideoSessionRebuilding` protocol.
+- **The Profile 7 dual-layer route shows the last frames at end of stream.** The end-of-source flush dropped what VideoToolbox still owed, the base frames waiting for an enhancement layer and the compositions in flight. `VideoDecodingPipeline.drainForEndOfStream()` (a no-op where `flush()` already delivers) drains both sessions with pairing live, sends a waiting base frame out alone, and waits for the composer; the host calls it before that flush. Seeks still discard.
 - **A failed `CMBlockBuffer` creation around a packet's payload no longer releases the packet reference twice** when CoreMedia has already freed the block source from inside the failing call.
 
 - **FLAC with blocks under 192 samples plays instead of failing to open** (#764). An MKV whose FLAC used

From 6aa12753b5e173118368d95f8a119b68c75b2d29 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 11:59:01 +0200
Subject: [PATCH 059/132] test(dovi): bound composeAsync on the GPU slots, not
 on delivery lag

completionsAreExactlyOnceAndBounded asserted issued-minus-delivered against
2 x maxFramesInFlight + 1. Only the GPU slots are bounded: a retired frame
waits on the delivery queue, which a loaded runner can starve (main CI after
#770 measured 18 against 7). It now reads the composer's peak slot count.

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

diff --git a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
index 48ecd8be7..e2cf13f19 100644
--- a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
+++ b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
@@ -175,16 +175,12 @@ struct DoviComposeAsyncTests {
         // inside composeAsync is what stops the loop from running away, so a
         // deadlock or a lost completion hangs here rather than passing quietly.
         //
-        // The semaphore bounds compositions on the GPU, and the slot is released
-        // when the command buffer retires rather than when the completion has
-        // run, so "issued minus completed" is looser than the semaphore's value:
-        // it also covers the call entering `wait` and the retired frames sitting
-        // on the delivery queue. What this asserts is that backpressure exists at
-        // all - without it the loop runs to `frames` before anything completes.
+        // The bound is on the GPU slots, read from the composer's own counter. "Issued minus
+        // delivered" is not bounded: a retired frame waits on the delivery queue, which a loaded
+        // runner can starve (CI measured 18 outstanding against a bound of 7).
         //
         // The loop runs on a thread of its own: `composeAsync` parks in a semaphore, which the
         // `.timeLimit` trait cannot interrupt on the test's own thread.
-        let bound = DoviFelComposer.maxFramesInFlight * 2 + 1
         let buffers = Buffers(bl: bl, el: el)
         Thread.detachNewThread {
             for i in 0..<frames {
@@ -198,7 +194,9 @@ struct DoviComposeAsyncTests {
         try await waitFor { counter.completed == frames }
         #expect(counter.completed == frames)
         #expect(counter.nonNil == frames)
-        #expect(counter.peakOutstanding <= bound)
+        let peakSlots = composer.takePeakSlotsInUse()
+        #expect(peakSlots >= 1)
+        #expect(peakSlots <= DoviFelComposer.maxFramesInFlight)
     }
 
     /// The decoder calls `composeAsync` with its own recursive lock held, and the

From 6a3e6dfa2996897b4bd05ee8111aba78bb35d2ee Mon Sep 17 00:00:00 2001
From: Pavel Kajaba <15980400+pkajaba@users.noreply.github.com>
Date: Thu, 15 Oct 2026 11:07:57 +0100
Subject: [PATCH 060/132] test: time-limited dual-layer suites leave the
 one-lane pool

The one-lane trait serialises a case behind every other lane case, and the
wait counts against the case's .timeLimit. On the CI runner the fuzz suites
hold the lane for ~85 s, so DualLayerStreamClassificationTests and
DualLayerGpuSlotWaitTests hit their 1-minute limit before they ran. The four
dual-layer suites with a time limit are hang watchdogs parked on VideoToolbox
or a semaphore, not CPU loops, so they take the plain .offCooperativePool, as
the trait's comment already asks of DoviComposeAsyncTests.
---
 Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift        | 2 +-
 Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift    | 2 +-
 .../AetherEngineTests/DualLayerStreamClassificationTests.swift | 2 +-
 Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift       | 2 +-
 Tests/AetherEngineTests/Support/OffCooperativePool.swift       | 3 ++-
 5 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
index 49f507ff1..c0dd98522 100644
--- a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
+++ b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
@@ -11,7 +11,7 @@ import Foundation
 /// `acquireSlot()` with no lock held, so `flush()` returns promptly. On the
 /// pre-fix code the wait sat inside `composeAsync` while the VideoToolbox
 /// thread held the decoder lock, and `flush()` hung behind it.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(1)))
+@Suite(.serialized, .offCooperativePool, .timeLimit(.minutes(1)))
 struct DualLayerGpuSlotWaitTests {
 
     /// Fake composer with an in-flight limit of 1. The first composition's
diff --git a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
index 015eb6eb4..d3621f2bc 100644
--- a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
+++ b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
@@ -11,7 +11,7 @@ import AetherLibavformat
 /// the side-data ring, and a seek lands on timestamps the pre-seek frames may already have used (a
 /// backward seek replays the same PTS keys). These tests drive the frame handlers with tagged
 /// synthetic buffers and check what the composer was asked to pair and what reached `onFrame`.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(2)))
+@Suite(.serialized, .offCooperativePool, .timeLimit(.minutes(2)))
 struct DualLayerSeekRealignmentTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
index 257f7c9d2..e156c7439 100644
--- a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
+++ b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
@@ -10,7 +10,7 @@ import AetherLibavcodec
 /// the enhancement decoder opens. A per-frame `disable_residual_flag` is a kernel flag
 /// (`DoviComposerFlags.disableResidual`, honoured by the composer) and must never shut
 /// off the enhancement layer for the rest of the session.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(1)))
+@Suite(.serialized, .offCooperativePool, .timeLimit(.minutes(1)))
 struct DualLayerStreamClassificationTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 79c17c014..29cda99d7 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -15,7 +15,7 @@ import Dovi
 /// asynchronously. These tests drive the two frame handlers directly with synthetic P010 buffers,
 /// using `primeForTesting` / `seedRPUForTesting` to stand in for what `decode(packet:)` sets up, so
 /// the pairing, ordering, metadata and flush behaviour is covered without a real stream.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(2)))
+@Suite(.serialized, .offCooperativePool, .timeLimit(.minutes(2)))
 struct DualLayerVideoDecoderTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/Support/OffCooperativePool.swift b/Tests/AetherEngineTests/Support/OffCooperativePool.swift
index fc7810f8f..22d7a86fe 100644
--- a/Tests/AetherEngineTests/Support/OffCooperativePool.swift
+++ b/Tests/AetherEngineTests/Support/OffCooperativePool.swift
@@ -34,7 +34,8 @@ extension Trait where Self == OffCooperativePoolTrait {
 /// `BlockingExecutor` adds a thread per blocked job, so on their own they all ran at once and
 /// took the 3-core runner from the timing tests beside them. One lane keeps them to one core.
 /// The time a case waits for the lane counts against its `.timeLimit`, so a suite of short
-/// deadlock watchdogs (`DoviComposeAsyncTests`) takes the plain trait instead.
+/// deadlock watchdogs (`DoviComposeAsyncTests`, the time-limited dual-layer decoder suites) takes
+/// the plain trait instead.
 struct OneLaneOffCooperativePoolTrait: SuiteTrait, TestTrait, TestScoping {
     var isRecursive: Bool { true }
 

From e39fd8d293bde53c50d749f32e288448a1a91cd0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 12:17:12 +0200
Subject: [PATCH 061/132] test: give the dual-layer lane suites a five-minute
 time limit

The one-lane trait's wait counts against .timeLimit, and on the main CI run
after #770 a one-line classifyStream test waited 71 s for the lane against a
one-minute suite limit. The four DualLayer suites that took the trait in the
#769 follow-up go to five minutes; the trait's doc says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift       | 2 +-
 Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift   | 2 +-
 .../DualLayerStreamClassificationTests.swift                  | 2 +-
 Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift      | 4 ++--
 Tests/AetherEngineTests/Support/OffCooperativePool.swift      | 3 ++-
 5 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
index 49f507ff1..0785c91a3 100644
--- a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
+++ b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
@@ -11,7 +11,7 @@ import Foundation
 /// `acquireSlot()` with no lock held, so `flush()` returns promptly. On the
 /// pre-fix code the wait sat inside `composeAsync` while the VideoToolbox
 /// thread held the decoder lock, and `flush()` hung behind it.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(1)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(5)))
 struct DualLayerGpuSlotWaitTests {
 
     /// Fake composer with an in-flight limit of 1. The first composition's
diff --git a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
index 015eb6eb4..94c70fa9f 100644
--- a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
+++ b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
@@ -11,7 +11,7 @@ import AetherLibavformat
 /// the side-data ring, and a seek lands on timestamps the pre-seek frames may already have used (a
 /// backward seek replays the same PTS keys). These tests drive the frame handlers with tagged
 /// synthetic buffers and check what the composer was asked to pair and what reached `onFrame`.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(2)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(5)))
 struct DualLayerSeekRealignmentTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
index 257f7c9d2..152c364dc 100644
--- a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
+++ b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
@@ -10,7 +10,7 @@ import AetherLibavcodec
 /// the enhancement decoder opens. A per-frame `disable_residual_flag` is a kernel flag
 /// (`DoviComposerFlags.disableResidual`, honoured by the composer) and must never shut
 /// off the enhancement layer for the rest of the session.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(1)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(5)))
 struct DualLayerStreamClassificationTests {
 
     // MARK: - Fixtures
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 62f564378..f3d918b0d 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -15,7 +15,7 @@ import Dovi
 /// asynchronously. These tests drive the two frame handlers directly with synthetic P010 buffers,
 /// using `primeForTesting` / `seedRPUForTesting` to stand in for what `decode(packet:)` sets up, so
 /// the pairing, ordering, metadata and flush behaviour is covered without a real stream.
-@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(2)))
+@Suite(.serialized, .offCooperativePoolOneLane, .timeLimit(.minutes(5)))
 struct DualLayerVideoDecoderTests {
 
     // MARK: - Fixtures
@@ -1399,7 +1399,7 @@ struct DualLayerVideoDecoderTests {
     }
 
     @Test("a slow onFrame does not block pairing or flush() behind the decoder lock",
-          .timeLimit(.minutes(1)))
+          .timeLimit(.minutes(5)))
     func slowOnFrameDoesNotBlockDecoderOperations() async throws {
         // The old `deliver()` took the decoder's lock and called `emit` (hence
         // `onFrame`) from inside it, so a slow host callback would have stalled
diff --git a/Tests/AetherEngineTests/Support/OffCooperativePool.swift b/Tests/AetherEngineTests/Support/OffCooperativePool.swift
index fc7810f8f..3085bc557 100644
--- a/Tests/AetherEngineTests/Support/OffCooperativePool.swift
+++ b/Tests/AetherEngineTests/Support/OffCooperativePool.swift
@@ -34,7 +34,8 @@ extension Trait where Self == OffCooperativePoolTrait {
 /// `BlockingExecutor` adds a thread per blocked job, so on their own they all ran at once and
 /// took the 3-core runner from the timing tests beside them. One lane keeps them to one core.
 /// The time a case waits for the lane counts against its `.timeLimit`, so a suite of short
-/// deadlock watchdogs (`DoviComposeAsyncTests`) takes the plain trait instead.
+/// deadlock watchdogs (`DoviComposeAsyncTests`) takes the plain trait instead, and a suite that
+/// carries this one sets no `.timeLimit` under five minutes: on CI a one-line test waited 71 s here.
 struct OneLaneOffCooperativePoolTrait: SuiteTrait, TestTrait, TestScoping {
     var isRecursive: Bool { true }
 

From 104fa4db93910fe8c7d98c4c9af68f53ba84b9b9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 12:43:26 +0200
Subject: [PATCH 062/132] fix(probes): pulse server ignores any unparsable
 Range header

serve.py answered a multi-range or otherwise malformed Range header with 416
while it already ignored `bytes=-`. RFC 9110 says to ignore a Range header the
server cannot parse, so every such header now falls back to the whole file.

Follow-up to #771.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Probes/DolbyVisionPulse/Scripts/serve.py | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/Probes/DolbyVisionPulse/Scripts/serve.py b/Probes/DolbyVisionPulse/Scripts/serve.py
index 3635cb7c5..504476f00 100755
--- a/Probes/DolbyVisionPulse/Scripts/serve.py
+++ b/Probes/DolbyVisionPulse/Scripts/serve.py
@@ -18,13 +18,10 @@ def send_head(self):
             return super().send_head()
         m = re.match(r"bytes=(\d*)-(\d*)$", rng.strip())
         size = os.path.getsize(path)
-        if not m:
-            self.send_error(416)
-            return None
-        a, b = m.groups()
-        if a == "" and b == "":
-            # `bytes=-` names no range at all: RFC 9110 says to ignore an unparsable Range header.
+        if not m or m.groups() == ("", ""):
+            # A multi-range, `bytes=-` or otherwise unparsable header: RFC 9110 says to ignore it.
             return super().send_head()
+        a, b = m.groups()
         if a == "":
             start, end = max(0, size - int(b)), size - 1
         else:

From 5f7df6de910b8f458b15fa256e0ca86194cdc861 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 13:10:03 +0200
Subject: [PATCH 063/132] fix(aetherctl): bound the pin test's threshold scan
 and the --cycle-el period

A threshold capture rule (`avgpq<=V`, `maxpq>=V`, ...) that the title never
reaches kept parsing every frame's RPU under the lock for the rest of the
session, which distorts the measurement it exists for. It now gives up after
`DoviPinTest.thresholdScanLimit` frames (7200, five minutes at 24 fps) and
logs that no frame matched the rule. `--cycle-el` takes a period of at least
0.1 s, the floor `--dv-pin` already had, so a tiny value no longer spins a
thread that floods stdout. The new files carry no em-dashes.

Follow-up to #772.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/AetherEngine+DolbyVisionTest.swift  |  4 +-
 .../Video/AetherEngine+FelProbe.swift         |  4 +-
 .../Video/DoviDisplayMetadataDebug.swift      | 43 +++++++++++--------
 .../AetherEngine/Video/DoviRpuSurvey.swift    | 12 +++---
 Sources/aetherctl/main.swift                  |  4 +-
 .../AetherEngineTests/DoviPinTestTests.swift  | 19 ++++++++
 docs/cli.md                                   |  2 +-
 7 files changed, 58 insertions(+), 30 deletions(-)

diff --git a/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift b/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
index 686c37f82..20ab6064a 100644
--- a/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
+++ b/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
@@ -16,7 +16,7 @@ extension AetherEngine {
     ///
     /// - Parameter spec: e.g. `"darkest:240,period:2"`, or nil to disarm.
     /// - Returns: false if `spec` carried no recognisable capture rule, in which case nothing was
-    ///   armed — a typo leaves playback alone rather than pinning something arbitrary.
+    ///   armed, a typo leaves playback alone rather than pinning something arbitrary.
     @discardableResult
     @_spi(Diagnostics)
     public static func armDolbyVisionPinTest(_ spec: String?) -> Bool {
@@ -25,7 +25,7 @@ extension AetherEngine {
             return true
         }
         guard let config = DoviDisplayMetadataDebug.parse(spec: spec) else {
-            EngineLog.emit("dv-pin: could not parse '\(spec)' — expected something like "
+            EngineLog.emit("dv-pin: could not parse '\(spec)', expected something like "
                            + "'darkest:240,period:2' or 'avgpq<=1200,period:2'. Not armed.",
                            category: .engine)
             return false
diff --git a/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift b/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
index d39426662..09f01281a 100644
--- a/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
+++ b/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
@@ -35,8 +35,8 @@ public struct FelProbeResult: Sendable {
     public let distinctDVPayloads: Int
     /// Byte length of the first RPU payload attached, for eyeballing against the bitstream.
     public let firstDVPayloadBytes: Int
-    /// Leading bytes of the first RPU payload, hex. A well-formed payload starts `19` — the
-    /// Dolby Vision RPU prefix — because the `unspec62` NAL's 2-byte header has been stripped.
+    /// Leading bytes of the first RPU payload, hex. A well-formed payload starts `19`, the
+    /// Dolby Vision RPU prefix, because the `unspec62` NAL's 2-byte header has been stripped.
     public let firstDVPayloadPrefix: String
 }
 
diff --git a/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift b/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
index 477517397..d37aeae71 100644
--- a/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
+++ b/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
@@ -6,17 +6,17 @@ import Dovi
 /// metadata, optionally toggling back to the live RPU on a fixed period.
 ///
 /// ## What the test proves
-/// Everything up to the `CVPixelBuffer` is verified on the host — the attachment is set, it carries
+/// Everything up to the `CVPixelBuffer` is verified on the host: the attachment is set, it carries
 /// the right bytes, it propagates to the `IOSurface`, it survives into the `CMSampleBuffer`. What no
 /// host test can reach is the last link: whether the tvOS compositor *reads* it off a client-supplied
 /// buffer on the `AVSampleBufferDisplayLayer` path (see `dolby-vision-fel.md §4.1`).
 ///
 /// So: hold the pixels constant and change only the metadata. This substitution happens after the GPU
-/// composer has already run and *only* touches the attachment — `rpuCache`, the reshaping
+/// composer has already run and *only* touches the attachment: `rpuCache`, the reshaping
 /// coefficients, the composed frame itself are all untouched, so the decoded pixels stay bit-identical
 /// whichever phase the toggle is in. Any brightness or saturation shift visible on the panel therefore
-/// came from the metadata and nothing else. Pinned to a frame with extreme L1 statistics — the darkest
-/// or brightest frame in the title, which `aetherctl dvsurvey` finds — the TV's display mapping is
+/// came from the metadata and nothing else. Pinned to a frame with extreme L1 statistics, the darkest
+/// or brightest frame in the title, which `aetherctl dvsurvey` finds, the TV's display mapping is
 /// told the wrong thing about the scene and should visibly misjudge it.
 ///
 /// A steady, in-sync 2-second pulse on the panel while the pixels are provably unchanged is the
@@ -26,20 +26,21 @@ import Dovi
 /// `AetherEngine.armDolbyVisionPinTest(_:)` from the host app (a debug menu), or `aetherctl play
 /// --dv-pin`. Grammar is comma-separated `key:value`, in any order:
 ///
-/// - `darkest:N` / `brightest:N` — watch the first `N` frames, keep the one with the lowest
+/// - `darkest:N` / `brightest:N`: watch the first `N` frames, keep the one with the lowest
 ///   (`darkest`) or highest (`brightest`) L1 `avg_pq`, pin to it. Self-calibrating and robust to
 ///   starting playback anywhere in the title.
-/// - `avgpq<=V` / `avgpq>=V` / `maxpq<=V` / `maxpq>=V` — pin to the first frame whose L1 `avg_pq`
+/// - `avgpq<=V` / `avgpq>=V` / `maxpq<=V` / `maxpq>=V`: pin to the first frame whose L1 `avg_pq`
 ///   or `max_pq` crosses `V` (a 12-bit PQ code). Use when `dvsurvey` has already told you the
-///   title's range and you want a specific frame.
-/// - `period:S` — seconds per phase, alternating pinned/live. `period:0` pins permanently. Defaults
+///   title's range and you want a specific frame. Gives up after `thresholdScanLimit` frames
+///   without a match.
+/// - `period:S`: seconds per phase, alternating pinned/live. `period:0` pins permanently. Defaults
 ///   to 2. A positive value below `minimumPeriod` (a pulse faster than a panel can show) is raised
 ///   to it, and a value that is not a finite number is ignored.
 ///
 /// `darkest:240,period:2` is the usual starting point: scan ten seconds, pin the
 /// darkest frame found, pulse every two seconds.
 ///
-/// Never reachable in Release — the whole file is `#if DEBUG`, and a private-framework-adjacent
+/// Never reachable in Release: the whole file is `#if DEBUG`, and a private-framework-adjacent
 /// diagnostic that rewrites what the display sees has no business in a shipping build.
 ///
 /// The state lives in a `DoviPinTest` instance. The engine uses one process-wide instance
@@ -57,6 +58,11 @@ final class DoviPinTest: @unchecked Sendable {
     /// Shortest phase `period:` may name. Below this the toggle is not visible on a panel anyway, and
     /// a tiny value would only make `elapsed / period` overflow an `Int`.
     static let minimumPeriod: TimeInterval = 0.1
+
+    /// Frames a threshold rule (`avgpq<=V` and friends) scans before it gives up. Without it a value
+    /// the title never reaches parses every frame for the rest of the session. 7200 is five minutes
+    /// at 24 fps.
+    static let thresholdScanLimit = 7200
     /// Longest phase `period:` may name (an hour); beyond it the pulse would never be seen.
     static let maximumPeriod: TimeInterval = 3600
 
@@ -115,8 +121,8 @@ final class DoviPinTest: @unchecked Sendable {
 
     /// Returns the RPU NAL that should actually be attached to this frame.
     ///
-    /// Called on the decode thread for every emitted frame. Returns `nal` unchanged — the only
-    /// behaviour that exists in an unarmed build — until a pin has been captured and the toggle is in
+    /// Called on the decode thread for every emitted frame. Returns `nal` unchanged, the only
+    /// behaviour that exists in an unarmed build, until a pin has been captured and the toggle is in
     /// its pinned phase.
     func substitute(_ nal: [UInt8]?) -> [UInt8]? {
         // Lines are collected under the lock and emitted after it: a log handler is arbitrary host
@@ -178,7 +184,9 @@ final class DoviPinTest: @unchecked Sendable {
             case .darkest(let frames), .brightest(let frames):
                 if st.scanned >= frames { commit(&st) }
             case .atMost, .atLeast:
-                if st.unparseableCount >= 300 && st.bestL1 == nil { commit(&st) }
+                if (st.unparseableCount >= 300 && st.bestL1 == nil) || st.scanned >= Self.thresholdScanLimit {
+                    commit(&st)
+                }
             }
             return
         }
@@ -194,15 +202,16 @@ final class DoviPinTest: @unchecked Sendable {
             if st.bestL1 == nil || l1.avg > st.bestL1!.avg { keep() }
             if st.scanned >= frames { commit(&st) }
         case .atMost(let f, let v):
-            if field(f) <= v { keep(); commit(&st) }
+            if field(f) <= v { keep(); commit(&st) } else if st.scanned >= Self.thresholdScanLimit { commit(&st) }
         case .atLeast(let f, let v):
-            if field(f) >= v { keep(); commit(&st) }
+            if field(f) >= v { keep(); commit(&st) } else if st.scanned >= Self.thresholdScanLimit { commit(&st) }
         }
     }
 
     private func commit(_ st: inout State) {
         guard let best = st.best, let l1 = st.bestL1 else {
-            st.pendingLogs.append("dv-pin: scan of \(st.scanned) frame(s) (\(st.unparseableCount) unparseable) found no parseable L1; test not armed")
+            let found = st.unparseableCount < st.scanned ? "no frame matching the rule" : "no parseable L1"
+            st.pendingLogs.append("dv-pin: scan of \(st.scanned) frame(s) (\(st.unparseableCount) unparseable) found \(found); test not armed")
             st.isDisarmed = true
             return
         }
@@ -210,7 +219,7 @@ final class DoviPinTest: @unchecked Sendable {
         st.pinnedL1 = l1
         st.pinnedSourceIndex = st.bestIndex
         st.armedAt = CFAbsoluteTimeGetCurrent()
-        st.pendingLogs.append(String(format: "dv-pin: captured frame %d after %d scanned — L1 min %d max %d avg %d (%.1f / %.1f nits max/avg), %d byte NAL; toggling every %.1fs",
+        st.pendingLogs.append(String(format: "dv-pin: captured frame %d after %d scanned, L1 min %d max %d avg %d (%.1f / %.1f nits max/avg), %d byte NAL; toggling every %.1fs",
                               st.bestIndex, st.scanned, Int(l1.min), Int(l1.max), Int(l1.avg),
                               DoviRpuSurvey.pqCodeToNits(l1.max), DoviRpuSurvey.pqCodeToNits(l1.avg),
                               best.count, st.config.period))
@@ -219,7 +228,7 @@ final class DoviPinTest: @unchecked Sendable {
     struct L1: Equatable { let min: UInt16; let max: UInt16; let avg: UInt16 }
 
     /// L1 statistics out of an `unspec62` NAL. Only called during the capture scan, which ends
-    /// after at most `frames` parses — the steady state does no libdovi work per frame.
+    /// after at most `frames` parses; the steady state does no libdovi work per frame.
     private static func parseL1(ofNAL nal: [UInt8]) -> L1? {
         nal.withUnsafeBufferPointer { buf -> L1? in
             guard let base = buf.baseAddress else { return nil }
diff --git a/Sources/AetherEngine/Video/DoviRpuSurvey.swift b/Sources/AetherEngine/Video/DoviRpuSurvey.swift
index d0e66df8c..46ae1cc4a 100644
--- a/Sources/AetherEngine/Video/DoviRpuSurvey.swift
+++ b/Sources/AetherEngine/Video/DoviRpuSurvey.swift
@@ -8,7 +8,7 @@ import Dovi
 ///
 /// This is the *other half* of an RPU from what `DoviMetalParams` carries. `DoviMetalParams` has
 /// the reshaping coefficients the GPU composer needs to rebuild pixels; this has the display
-/// metadata a Dolby Vision TV acts on — L1 frame statistics and L2 creative trims. Nothing here
+/// metadata a Dolby Vision TV acts on: L1 frame statistics and L2 creative trims. Nothing here
 /// feeds playback; it exists so `aetherctl dvsurvey` can tell an operator which frame of a title
 /// carries the most extreme metadata, which is the frame worth pinning for the on-device
 /// consumption test (see `DoviDisplayMetadataDebug`).
@@ -54,14 +54,14 @@ public struct DoviRpuSurveyResult: Sendable {
     public let rpuFailures: Int
     public let enhancementLayerType: String?
 
-    /// Frame with the lowest L1 `avg_pq` — the darkest frame in the survey. Ranked on `avg_pq`
+    /// Frame with the lowest L1 `avg_pq`, the darkest frame in the survey. Ranked on `avg_pq`
     /// rather than `max_pq` because `avg_pq` is what anchors the display-mapping curve's mid-tone,
     /// and because it is typically the field with the widest range in a title: a frame can hold a
     /// bright specular highlight (high `max_pq`) while being almost entirely black. Pinning this
     /// one while a bright scene plays tells the TV the scene is nearly dark, which should visibly
     /// crush it if the metadata is reaching the panel.
     public var darkestFrame: DoviRpuFrameSurvey? { frames.min { $0.l1AvgPQ < $1.l1AvgPQ } }
-    /// Frame with the highest L1 `avg_pq` — the brightest. The complementary poison: pinned over a
+    /// Frame with the highest L1 `avg_pq`, the brightest. The complementary poison: pinned over a
     /// dark scene the TV should stop protecting shadows and lift them.
     public var brightestFrame: DoviRpuFrameSurvey? { frames.max { $0.l1AvgPQ < $1.l1AvgPQ } }
 
@@ -101,7 +101,7 @@ public enum DoviRpuSurvey {
     /// Parses the display metadata out of one `unspec62` NAL.
     ///
     /// The NAL is converted to Profile 8.1 first, so what comes back is what would actually be
-    /// attached to the frame rather than what the Profile 7 bitstream held — the two agree on
+    /// attached to the frame rather than what the Profile 7 bitstream held; the two agree on
     /// L1/L2 by construction (`dovi_convert_rpu_with_mode` rewrites only the profile container),
     /// and surveying the converted form means a surprise there shows up here instead of on the TV.
     public static func parse(nal: UnsafePointer<UInt8>, length: Int, frameIndex: Int) -> DoviRpuFrameSurvey? {
@@ -170,7 +170,7 @@ extension AetherEngine {
 
     /// Walks a title's video stream and surveys every frame's Dolby Vision display metadata.
     ///
-    /// Runs the demuxer and `DoviRpuConverter` only — no decoders, no GPU — so it is fast enough to
+    /// Runs the demuxer and `DoviRpuConverter` only, no decoders, no GPU, so it is fast enough to
     /// sweep thousands of frames. Its purpose is picking the pin for the on-device consumption test:
     /// the operator arms `AetherEngine.armDolbyVisionPinTest(_:)` with `strongestPoison`'s frame.
     @_spi(Diagnostics)
@@ -199,7 +199,7 @@ extension AetherEngine {
             if packet.pointee.stream_index == videoIdx {
                 packetsProcessed += 1
                 if elType == nil { elType = DoviRpuConverter.enhancementLayerType(packet) }
-                // extractEL: false — the survey never touches pixels, so the EL is dead weight.
+                // extractEL: false; the survey never touches pixels, so the EL is dead weight.
                 let layers = DoviRpuConverter.separateDualLayers(packet, extractEL: false)
                 if let raw = layers.rpuData {
                     let idx = frames.count
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 7bf2af389..4e8ef3a1d 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -714,8 +714,8 @@ if first == "play" {
     // `--cycle-el <seconds>`: flip the FEL residual off and on every N seconds (starting with full FEL), so a
     // `--surface` window shows MEL-equivalent output (base layer + RPU mapping) against the full result.
     if let spec = takeStringFlag("--cycle-el", from: &rest) {
-        guard let period = Double(spec), period.isFinite, period > 0 else {
-            print("ERROR: --cycle-el takes a period in seconds, got '\(spec)'")
+        guard let period = Double(spec), period.isFinite, period >= 0.1 else {
+            print("ERROR: --cycle-el takes a period of at least 0.1 seconds, got '\(spec)'")
             exit(64)
         }
         if !playFel {
diff --git a/Tests/AetherEngineTests/DoviPinTestTests.swift b/Tests/AetherEngineTests/DoviPinTestTests.swift
index bc0f9c442..e78e2532c 100644
--- a/Tests/AetherEngineTests/DoviPinTestTests.swift
+++ b/Tests/AetherEngineTests/DoviPinTestTests.swift
@@ -41,6 +41,25 @@ struct DoviPinTestTests {
         #expect(failures.count == 1, "Expected exactly 1 disarm log line, got: \(failures)")
     }
 
+    @Test("a threshold rule the title never reaches gives up after the scan limit", .offCooperativePoolOneLane)
+    func thresholdRuleGivesUpAfterScanLimit() throws {
+        let nal = DoviComposedFrameRpuTests.felNAL
+        let hit = DoviPinTest(emit: { _ in })
+        hit.configure(try #require(DoviPinTest.parse(spec: "maxpq>=0,period:2")))
+        _ = hit.substitute(nal)
+        #expect(hit.isPinned, "the fixture must parse, or the rest of this test proves nothing")
+
+        let sink = Sink()
+        let pin = DoviPinTest(emit: { sink.append($0) })
+        pin.configure(try #require(DoviPinTest.parse(spec: "maxpq>=4096,period:2")))
+        for _ in 1..<DoviPinTest.thresholdScanLimit { _ = pin.substitute(nal) }
+        #expect(pin.isArmed)
+        _ = pin.substitute(nal)
+        #expect(!pin.isArmed)
+        #expect(!pin.isPinned)
+        #expect(sink.lines.filter { $0.contains("found no frame matching the rule") }.count == 1)
+    }
+
     @Test("an unarmed pin test returns every frame's RPU unchanged")
     func unarmedIsTransparent() {
         let pin = DoviPinTest(emit: { _ in })
diff --git a/docs/cli.md b/docs/cli.md
index e1c051a5c..977c3926e 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -260,7 +260,7 @@ live-only session took a rebuild that rejoins at the edge.
 
 `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.
 
-`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route. It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` (a release build refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
+`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route. It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` (at least 0.1) flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` (a release build refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
 
 `--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 476e45dc1c0b53b572f77dc5dc4da50a6138760a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 14:00:32 +0200
Subject: [PATCH 064/132] test(source-open): stop assuming the first open
 request reaches the wire

Three SourceOpenRecoveryTests assumed that the first, bounded data request
always reaches the origin before its first-byte deadline cancels it. On a
loaded runner it does not: the reader cancels it after 0.15 s before
URLSession has sent it, so the alternate open-ended request is the only one
the origin ever sees. CI run 38725408590 failed exactly so: "Cancelling the
alternate data open" waited for `requests.count == 2`, the trigger never
fired, and the retry ran into its 30 s budget (`requestTimeout` instead of
`CancellationError`).

Reproduced deterministically by setting the suite's firstByteTimeout to
1 us: the same three tests fail (the cancel test with the CI's exact error),
and with this change all ten pass under that setting as well as at the
real values.

- The cancel trigger keys on the alternate request's shape (`bytes=0-`)
  instead of an arrival count.
- The cold-recovery test silences requests by shape rather than parking
  arrival index 0, and checks that the recovered connection is the only
  open-ended request.
- The unanswered-open test treats two ranged GETs as a ceiling, since either
  can be cancelled before it is sent.

The engine is unchanged; its behaviour was correct in every case.

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

diff --git a/Tests/AetherEngineTests/SourceOpenRecoveryTests.swift b/Tests/AetherEngineTests/SourceOpenRecoveryTests.swift
index 35b64cd74..f63e12f21 100644
--- a/Tests/AetherEngineTests/SourceOpenRecoveryTests.swift
+++ b/Tests/AetherEngineTests/SourceOpenRecoveryTests.swift
@@ -47,21 +47,27 @@ struct SourceOpenRecoveryTests {
 
     @Test("A silent initial request reaches the alternate request shape within the host budget")
     func coldRequestRecovery() async throws {
-        let origin = try ProbeHTTPTestOrigin(data: bytes, stage: .headers)
+        // Silence is keyed on the request shape, not on arrival order: on a loaded runner the first
+        // request can be cancelled at its first-byte deadline before it ever reaches the wire, and
+        // then the alternate request is the first one the origin sees.
+        let silence = ProbeTestGate()
+        let origin = try ProbeHTTPTestOrigin(data: bytes, response: { request, _ in
+            if request.range != "bytes=0-" { silence.wait() }
+            return nil
+        })
         let source = url(origin)
         OriginRequestBudget.shared.setHostLimit(1, for: source)
         let reader = AVIOReader(url: source, boundedInitialFetch: 4096,
             sourceOpenPolicy: .init(firstByteTimeout: 0.2, sizeProbeTimeout: 2))
-        defer { reader.markClosed(); reader.close(); origin.stop() }
-        let job = ProbeTestJob { try reader.open() }
-        try await waitFor { origin.blocked.entered }
-        try await job.outcome().get()
+        defer { reader.markClosed(); reader.close(); silence.open(); origin.stop() }
+        try await ProbeTestJob { try reader.open() }.outcome().get()
         #expect(reader.isSeekable)
         #expect(try await readPrefix(reader) == bytes.prefix(16))
         #expect(OriginRequestBudget.shared.snapshot(for: source)?.peakInflight == 1)
         #expect(origin.requests.map(\.method).allSatisfy { $0 == "GET" })
-        #expect(origin.requests.contains { $0.range == "bytes=0-" })
-        #expect(origin.requests.count == 2, "the recovered data connection must be retained, not reprobed")
+        #expect(origin.requests.filter { $0.range == "bytes=0-" }.count == 1,
+                "the recovered data connection must be retained, not reprobed")
+        #expect(origin.requests.count <= 2)
         #expect(origin.failure == nil)
     }
 
@@ -200,7 +206,9 @@ struct SourceOpenRecoveryTests {
         if case .failure(let error) = result {
             #expect(error as? AVIOReaderError == .requestTimeout)
         } else { Issue.record("no response is not a successful sequential open") }
-        #expect(origin.requests.count == 2)
+        // Either request can be cancelled at its deadline before it reaches the wire on a loaded
+        // runner, so the count is a ceiling: two ranged GETs at most, never an unranged one.
+        #expect(origin.requests.count <= 2)
         #expect(origin.requests.allSatisfy { $0.method == "GET" && $0.range != nil })
         #expect(OriginRequestBudget.shared.snapshot(for: source)?.inflight == 0)
     }
@@ -215,7 +223,11 @@ struct SourceOpenRecoveryTests {
             sourceOpenPolicy: .init(firstByteTimeout: 0.15, sizeProbeTimeout: 30))
         defer { reader.close(); gate.open(); origin.stop() }
         let job = ProbeTestJob { try reader.open() }
-        let teardown = ProbeTestTrigger(when: { origin.requests.count == 2 || job.isFinished }) {
+        // Keyed on the alternate request's shape: the first request can be cancelled before it
+        // reaches the wire on a loaded runner, so counting arrivals can wait for one that never comes.
+        let teardown = ProbeTestTrigger(when: {
+            origin.requests.contains { $0.range == "bytes=0-" } || job.isFinished
+        }) {
             reader.markClosed()
         }
         let result = try await job.outcome()

From df6dc0f4b2467a62785fbf315674d5f544429b91 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 14:50:49 +0200
Subject: [PATCH 065/132] fix(renderer): keep the arrival-order floor at or
 below the clock

Follow-up to #773.

- A slot the clock has passed is given up only while the floor stays at or
  below the clock. After a seek to a target off the frame grid the seeded
  frontier walks the target's grid, and the old step could promise past the
  first frame due after the seek (217 of 2000 swept seek phases and clock lags).
- More than 64 frames waiting behind a hole give the hole up. With decode more
  than a second behind the clock the clock no longer counts, so the floor held
  until the next flush and `ahead` grew by a frame each time.
- The minimum-upcoming expectation is only set when no flush came in between,
  so a pre-seek floor cannot outlive the flush and hold back a backward seek.
- End of stream resets the expectation, since a hole in the last GOP would
  otherwise leave it below the tail with no frame left to move it.
- Arrival order is used for 10 to 120 fps only. A declared rate below the real
  one promises past B-frames still to come.
- Tests: the off-grid seek with a running clock, the hole past the clock gap,
  a bogus rate; one test name and one comment corrected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Renderer/PresentationFloor.swift          | 15 ++++++-
 .../Renderer/SampleBufferRenderer.swift       | 22 ++++++++--
 .../PresentationFloorTests.swift              | 42 +++++++++++++++++--
 3 files changed, 71 insertions(+), 8 deletions(-)

diff --git a/Sources/AetherEngine/Renderer/PresentationFloor.swift b/Sources/AetherEngine/Renderer/PresentationFloor.swift
index aa383f671..df6ec3b69 100644
--- a/Sources/AetherEngine/Renderer/PresentationFloor.swift
+++ b/Sources/AetherEngine/Renderer/PresentationFloor.swift
@@ -28,6 +28,9 @@ struct PresentationFloor {
 
     /// How far past the frontier the clock may be and still give up slots, in seconds.
     static let maxClockGap: Double = 1
+    /// Most frames `ahead` may hold before the slot under its head is given up without the clock.
+    /// Far past any GOP's reordering, so it only fires when a hole has outlived `maxClockGap`.
+    static let maxAhead = 64
 
     init(interval: Double) {
         self.interval = interval
@@ -68,13 +71,21 @@ struct PresentationFloor {
         // A clock more than `maxClockGap` past the frontier is not this stream's: a renderer not yet
         // attached to its synchronizer runs on host time.
         let clock = clockSeconds.flatMap { $0.isFinite && $0 - f <= Self.maxClockGap ? $0 : nil }
+        // A hole the clock can no longer reach (decode fell more than `maxClockGap` behind) would hold
+        // the floor until the next flush and grow `ahead` by a frame each time.
+        if ahead.count > Self.maxAhead, let head = ahead.first {
+            f = max(f, head - interval)
+        }
         while true {
             if let next = ahead.first, next < f + 1.5 * interval {
                 step.contiguous.append(next)
                 f = max(f, next)
                 ahead.removeFirst()
-            } else if let clock, f + interval < clock {
-                f += interval  // a slot the clock has passed: anything still owed there is late anyway
+            } else if let clock, f + 1.5 * interval <= clock {
+                // A slot the clock has passed: anything still owed there is late anyway. The step
+                // leaves the floor at or below the clock, since after an off-grid seek the frontier
+                // is not on the stream's grid and a real slot can sit just past the clock.
+                f += interval
             } else {
                 break
             }
diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 7573205d1..2005ea562 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -87,13 +87,17 @@ final class SampleBufferRenderer: @unchecked Sendable {
     func setArrivalOrderHandover(frameRate: Double?) {
         reorderLock.lock()
         defer { reorderLock.unlock() }
-        if #available(visionOS 1.1, *), let rate = frameRate, rate.isFinite, rate > 0 {
+        if #available(visionOS 1.1, *), let rate = frameRate, Self.arrivalOrderFrameRates.contains(rate) {
             arrivalFloor = PresentationFloor(interval: 1 / rate)
         } else {
             arrivalFloor = nil
         }
     }
 
+    /// Rates the floor trusts. A declared rate below the real one would promise past B-frames still to
+    /// come, and a bogus `avg_frame_rate` in the thousands would walk the grid a slot at a time.
+    static let arrivalOrderFrameRates: ClosedRange<Double> = 10...120
+
     var handsOverInArrivalOrder: Bool {
         reorderLock.lock()
         defer { reorderLock.unlock() }
@@ -588,14 +592,21 @@ final class SampleBufferRenderer: @unchecked Sendable {
         if step.belowFloor { _framesBelowFloor += 1 }
         let belowCount = _framesBelowFloor
         let floor = arrivalFloor?.floor
+        let generation = _flushGeneration
         reorderLock.unlock()
 
         flushFrame(pixelBuffer: pixelBuffer, pts: pts, hdr10PlusData: hdr10PlusData,
                    displayOrderSpacing: step.contiguous)
         if let raised = step.raisedFloor, #available(visionOS 1.1, *) {
             let source = CMTime(seconds: raised, preferredTimescale: 90_000)
-            videoRenderer.presentationTimeExpectation =
-                .minimumUpcoming(timeline?.rendererTime(forSource: source) ?? source)
+            // A flush in between dropped this promise along with the frames it covered; setting it
+            // now would hold the first frame of a backward seek below a pre-seek floor.
+            reorderLock.lock()
+            if generation == _flushGeneration {
+                videoRenderer.presentationTimeExpectation =
+                    .minimumUpcoming(timeline?.rendererTime(forSource: source) ?? source)
+            }
+            reorderLock.unlock()
         }
         if step.belowFloor, belowCount == 1 || belowCount % 250 == 0 {
             EngineLog.emit(
@@ -647,6 +658,11 @@ final class SampleBufferRenderer: @unchecked Sendable {
     /// Send all buffered frames to the display layer (call at EOF).
     func drainReorderBuffer() {
         reorderLock.lock()
+        // Arrival order: nothing is held, but a hole in the last GOP would leave the promise below
+        // the tail with no further frame to move it.
+        if arrivalFloor != nil, #available(visionOS 1.1, *) {
+            videoRenderer.presentationTimeExpectation = .none
+        }
         let remaining = reorderBuffer
         reorderBuffer.removeAll()
         if let newest = remaining.last { _lastReleasedPtsSeconds = CMTimeGetSeconds(newest.1) }
diff --git a/Tests/AetherEngineTests/PresentationFloorTests.swift b/Tests/AetherEngineTests/PresentationFloorTests.swift
index db4ae3875..c2cbb9612 100644
--- a/Tests/AetherEngineTests/PresentationFloorTests.swift
+++ b/Tests/AetherEngineTests/PresentationFloorTests.swift
@@ -50,7 +50,7 @@ struct PresentationFloorTests {
         return (floor, shown, violations)
     }
 
-    @Test("In display order the floor follows every frame", arguments: [0, 4, 8, 16])
+    @Test("In display or decode order the floor never passes a frame still to come", arguments: [0, 4, 8, 16])
     func neverPassesAFrameStillToCome(gop: Int) {
         let order = gop == 0 ? Array(0..<96) : Self.decodeOrder(gop: gop, frames: 96)
         #expect(Set(order) == Set(0..<96), "the generator covers every frame once")
@@ -64,7 +64,7 @@ struct PresentationFloorTests {
 
     @Test("The floor rises within a GOP, not only at its end")
     func risesInsideTheGOP() {
-        // GOP of 8: 0, 8, 4, 2, 1, 3, 6, 5, 7. Once 1 arrives, 0..4 are contiguous.
+        // GOP of 8: 0, 8, 4, 2, 1, 3, 6, 5, 7. Once 1 arrives, 0..2 are contiguous.
         var floor = PresentationFloor(interval: Self.interval)
         var raised: [Double?] = []
         for i in [0, 8, 4, 2, 1] { raised.append(floor.record(Double(i) * Self.interval, clockSeconds: nil).raisedFloor) }
@@ -107,11 +107,45 @@ struct PresentationFloorTests {
         let order = [0, 1, 2, 4, 5, 6, 7, 8]
         let stuck = Self.walk(order)
         #expect(abs(stuck.floor.floor - 2.5 * Self.interval) < 1e-9)
-        let moving = Self.walk(order, clock: { k in k >= 5 ? 3.5 * Self.interval : nil })
+        let moving = Self.walk(order, clock: { k in k >= 5 ? 3.6 * Self.interval : nil })
         #expect(abs(moving.floor.floor - 8.5 * Self.interval) < 1e-9)
         #expect(moving.violations == 0)
     }
 
+    @Test("After an off-grid seek a running clock never promises past a frame not yet due",
+          arguments: [0.1, 0.25, 0.51, 0.75, 0.9])
+    func offGridSeekWithARunningClock(phase: Double) {
+        let target = (100 + phase) * Self.interval
+        let order = Self.decodeOrder(gop: 8, frames: 48, startingAt: 96).filter { Double($0) * Self.interval >= target }
+        for lag in stride(from: 0.0, through: 0.9, by: 0.05) {
+            // The clock was seeked to the target and runs while the first frames past it arrive. Only a
+            // frame the clock has not reached yet is owed; one it has passed is late with or without
+            // the floor.
+            var floor = PresentationFloor(interval: Self.interval)
+            floor.reset(start: target)
+            var owedBelowFloor = 0
+            for (k, index) in order.enumerated() {
+                let clock = target + (lag + Double(k) * 0.1) * Self.interval
+                _ = floor.record(Double(index) * Self.interval, clockSeconds: clock)
+                owedBelowFloor += order[(k + 1)...].filter {
+                    let t = Double($0) * Self.interval
+                    return t >= clock && t < floor.floor
+                }.count
+            }
+            #expect(owedBelowFloor == 0, "phase \(phase), lag \(lag)")
+        }
+    }
+
+    @Test("A hole the clock can no longer reach is given up once enough frames pile up behind it")
+    func holePastTheClockGap() {
+        var floor = PresentationFloor(interval: Self.interval)
+        for i in 0..<3 { _ = floor.record(Double(i) * Self.interval, clockSeconds: nil) }
+        // Frame 3 is lost and the clock is far past the frontier, so it does not count.
+        for i in 4..<200 { _ = floor.record(Double(i) * Self.interval, clockSeconds: 1000) }
+        #expect(floor.ahead.count <= PresentationFloor.maxAhead + 1)
+        #expect(abs(floor.floor - 199.5 * Self.interval) < 1e-9)
+    }
+
     @Test("A frame below the promised floor is flagged and does not move it")
     func belowFloorIsFlagged() {
         var floor = PresentationFloor(interval: Self.interval)
@@ -220,6 +254,8 @@ struct ArrivalOrderHandoverTests {
         #expect(!renderer.handsOverInArrivalOrder)
         renderer.setArrivalOrderHandover(frameRate: .nan)
         #expect(!renderer.handsOverInArrivalOrder)
+        renderer.setArrivalOrderHandover(frameRate: 90_000)
+        #expect(!renderer.handsOverInArrivalOrder, "a bogus rate is not a grid")
         renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: true))
         let pixels = Self.makePixelBuffer()
         for i in [0, 4, 2, 1, 3] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }

From 66c14590c360bfba15d78b464341a6e3a0bd2cb9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 15:28:37 +0200
Subject: [PATCH 066/132] fix(dovi): open the FEL preroll after an off-grid
 seek, at 60 fps and after a paused seek

Follow-up to #774.

- A seek or resume target between two frames left the preroll gate shut
  about half the time, so the picture froze for the 2 s timeout. The floor
  was seeded a whole frame below the target, and the first frame past it
  joined only within half a frame of the target. Otherwise the frontier
  waited for the clock, which the preroll holds still. The seed now sits
  half a frame below the target, which makes the first frame contiguous
  and promises nothing below the threshold.
- At 60 fps the look-ahead window (nine frames, 0.15 s) admitted less than
  the 0.167 s preroll, so every start timed out. The preroll is now capped
  one frame inside the window.
- A seek landed while paused anchors at rate 0 without asking the gate, and
  the play that followed started the clock with nothing queued. Sodalite's
  scrub commits that way. `setRate` now starts a standing clock through the
  preroll on a session that has one. While a preroll is pending,
  `play()` no longer reads the held clock as stalled (AE#549).
- A cancelled preroll stops polling instead of running at 500 Hz until its
  gate opens or it times out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/AudioOutput.swift  | 21 ++++++++
 .../Native/SoftwarePlaybackHost.swift         |  3 +-
 .../Renderer/PresentationFloor.swift          |  8 ++-
 .../Renderer/SampleBufferRenderer.swift       | 10 +++-
 .../AetherEngineTests/VideoPrerollTests.swift | 51 +++++++++++++++++++
 5 files changed, 89 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index 46c352e5e..7a365d59f 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -172,6 +172,13 @@ final class AudioOutput: @unchecked Sendable {
         // A host resumes right after it arms the clock; while a preroll waits, that rate is the one
         // the preroll starts at, not a start of its own.
         if rate > 0, updatePrerollRate(rate) { return }
+        // A clock that stands still starts through the preroll on a session that has one: a seek
+        // landed while paused anchors at rate 0 and never asks the gate, so the play that follows
+        // would otherwise start it with nothing queued.
+        if rate > 0, synchronizer.rate == 0, videoPrerollSatisfied?(currentTime.seconds) != nil {
+            seekClock(to: currentTime, rate: rate)
+            return
+        }
         cancelPreroll()
         let at = synchronizer.currentTime()
         EngineLog.emit("[AudioOutput] setRate \(rate) at t=\(String(format: "%.3f", timeline.sourceSeconds(forRenderer: at.seconds)))", category: .swPlayback)
@@ -431,7 +438,21 @@ final class AudioOutput: @unchecked Sendable {
     private var prerollRate: Float?  // guarded by lock; non-nil while a preroll waits: the rate it starts at
     private let prerollQueue = DispatchQueue(label: "aether.audio.preroll", qos: .userInteractive)
 
+    /// Whether a preroll holds the clock at rate 0 to start it later. A host must not read that
+    /// standing clock as stalled (AE#549) and restart it.
+    var prerollPending: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return prerollRate != nil
+    }
+
     private func pollPreroll(gen: Int, time: CMTime, started: CFTimeInterval) {
+        // A pause, seek or stop since: this chain is over. Without the check every cancelled preroll
+        // polled on at 500 Hz, taking both locks, until its gate opened or it timed out.
+        lock.lock()
+        let current = prerollGeneration == gen && prerollRate != nil
+        lock.unlock()
+        guard current else { return }
         let ready = videoPrerollSatisfied?(time.seconds) != false
         let waited = CACurrentMediaTime() - started
         if !ready, waited < Self.prerollTimeout {
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 80072aefc..9426f8804 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1293,7 +1293,8 @@ final class SoftwarePlaybackHost {
         switch RendererClockResume.onPlay(
             hostPaused: pausedByHost,
             clockArmed: clockArmed,
-            synchronizerRate: audioOutput?.rate ?? 0,
+            // A clock a preroll holds (#774) is about to start, not stalled.
+            synchronizerRate: audioOutput?.prerollPending == true ? lastRate : audioOutput?.rate ?? 0,
             rebuffering: demuxDiag.snapshot.rebuffering,
             parkedAtEndOfMedia: didParkClockAtEnd
         ) {
diff --git a/Sources/AetherEngine/Renderer/PresentationFloor.swift b/Sources/AetherEngine/Renderer/PresentationFloor.swift
index df6ec3b69..8c72dc4e5 100644
--- a/Sources/AetherEngine/Renderer/PresentationFloor.swift
+++ b/Sources/AetherEngine/Renderer/PresentationFloor.swift
@@ -50,9 +50,13 @@ struct PresentationFloor {
     /// Forgets everything (a flush). `start` is the lowest timestamp that can still arrive, when the
     /// caller knows it: after a seek the first frame past the skip threshold need not be the lowest
     /// one to come, since B-frames below it arrive after it in decode order, so the frontier starts
-    /// just below the threshold rather than at that frame.
+    /// just below the threshold rather than at that frame. Half a frame below, not a whole one: a seek
+    /// target is not on the frame grid, and from a whole frame below the first frame past it joins
+    /// only when it lies within half a frame of the target. Otherwise the frontier waited for the clock,
+    /// which a preroll holds still (#774), so about every second seek ran into the preroll timeout.
+    /// The floor this seeds is the threshold itself, which no admitted frame is below.
     mutating func reset(start: Double? = nil) {
-        frontier = start.map { $0 - interval }
+        frontier = start.map { $0 - 0.5 * interval }
         ahead.removeAll()
         floor = -.infinity
     }
diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 3025494ee..5cc33d51f 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -176,6 +176,14 @@ final class SampleBufferRenderer: @unchecked Sendable {
     /// 90 to 100 ms at a start and 0.3 to 0.9 s after a seek.
     static let felPrerollSeconds = 0.167
 
+    /// `felPrerollSeconds`, capped one frame inside the look-ahead window: with the clock held still,
+    /// `mayEnqueueAnotherFrame` admits nothing past `felVideoLookaheadFrames` frames ahead of it, so
+    /// at 60 fps (nine frames, 0.15 s) a 0.167 s preroll could never fill and every start waited out
+    /// `AudioOutput.prerollTimeout`.
+    static func felPrerollSeconds(frameRate: Double) -> Double {
+        min(felPrerollSeconds, Double(felVideoLookaheadFrames - 1) / frameRate)
+    }
+
     /// The FEL path's preroll gate for `AudioOutput.videoPrerollSatisfied`: true once frames up to
     /// `felPrerollSeconds` past `clock` (source seconds) are in the layer, nil off the FEL path. On
     /// the arrival-order path only the frontier counts, the newest timestamp with every earlier slot
@@ -186,7 +194,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
         guard let rate = felFrameRate, clock.isFinite else { return nil }
         let handed = arrivalFloor != nil ? arrivalFloor?.frontier : _lastReleasedPtsSeconds
         guard let handed else { return false }
-        return handed + 1 / rate - clock >= Self.felPrerollSeconds
+        return handed + 1 / rate - clock >= Self.felPrerollSeconds(frameRate: rate)
     }
 
     /// Combined queue-readiness and look-ahead gate, called BEFORE decode so excess frames stay compressed.
diff --git a/Tests/AetherEngineTests/VideoPrerollTests.swift b/Tests/AetherEngineTests/VideoPrerollTests.swift
index 0f0fda319..052def52e 100644
--- a/Tests/AetherEngineTests/VideoPrerollTests.swift
+++ b/Tests/AetherEngineTests/VideoPrerollTests.swift
@@ -67,6 +67,42 @@ struct VideoPrerollTests {
         #expect(renderer.felPrerollSatisfied(clock: target) == true)
     }
 
+    @Test("After a seek to a target between two frames the gate still opens without a running clock",
+          arguments: [0.1, 0.4, 0.6, 0.9])
+    @MainActor
+    func gateOpensAfterAnOffGridSeek(phase: Double) {
+        let renderer = SampleBufferRenderer()
+        renderer.setFELLookahead(enabled: true, frameRate: 24)
+        renderer.setArrivalOrderHandover(frameRate: 24)
+        let pixels = Self.makePixelBuffer()
+        let target = (100 + phase) / 24
+        renderer.setSkipThreshold(CMTime(seconds: target, preferredTimescale: 90000))
+        // Decode order from the GOP's anchor below the target, as the decoder delivers it after a seek.
+        for i in PresentationFloorTests.decodeOrder(gop: 8, frames: 24, startingAt: 96) {
+            renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i))
+        }
+        #expect(renderer.felPrerollSatisfied(clock: target) == true)
+        #expect(renderer.framesBelowFloor == 0)
+    }
+
+    @Test("At 60 fps the preroll fits inside the look-ahead window")
+    @MainActor
+    func prerollFitsTheLookaheadAt60() {
+        let renderer = SampleBufferRenderer()
+        renderer.setFELLookahead(enabled: true, frameRate: 60)
+        renderer.setArrivalOrderHandover(frameRate: 60)
+        let pixels = Self.makePixelBuffer()
+        // Everything the look-ahead admits with the clock held at 0.
+        var admitted = 0
+        while SampleBufferRenderer.mayEnqueueAnotherFrame(
+            rendererReady: true, felFrameRate: 60, framePTS: Double(admitted) / 60,
+            clockSeconds: 0, clockArmed: true) {
+            renderer.enqueue(pixelBuffer: pixels, pts: CMTime(value: Int64(admitted), timescale: 60))
+            admitted += 1
+        }
+        #expect(renderer.felPrerollSatisfied(clock: 0) == true, "\(admitted) frames admitted")
+    }
+
     // MARK: - Clock
 
     /// A gate the test opens by hand.
@@ -126,6 +162,21 @@ struct VideoPrerollTests {
         #expect(!started)
     }
 
+    @Test("A play after a seek landed while paused starts through the preroll", .timeLimit(.minutes(1)))
+    func playAfterAPausedSeekPrerolls() async throws {
+        let output = AudioOutput()
+        let gate = Gate()
+        output.videoPrerollSatisfied = { _ in gate.isOpen }
+        output.seekClock(to: CMTime(seconds: 5, preferredTimescale: 90000), rate: 0)
+        #expect(!output.prerollPending, "a paused seek does not ask the gate")
+        output.setRate(1)
+        #expect(output.synchronizer.rate == 0, "nothing is queued yet")
+        #expect(output.prerollPending, "the host must not read this clock as stalled")
+        gate.set(true)
+        try await waitFor { output.synchronizer.rate == 1 }
+        #expect(!output.prerollPending)
+    }
+
     @Test("A gate that never opens starts the clock after the timeout", .timeLimit(.minutes(1)))
     func timesOut() async throws {
         let output = AudioOutput()

From 3211d6258553b79df0634174d42030eb7523d919 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 16:27:41 +0200
Subject: [PATCH 067/132] fix(swhost): refuse a memory-store cursor before any
 chunk changes state

A cursor whose offset failed the final check had already turned the chunks between the head
and its target volatile, leaving unread data in front of the reader reclaimable. Checked
first now. Also rewraps the memoryPacketStoreBudget doc comment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift | 7 +++++--
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift     | 7 ++++---
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
index 9ddb45edf..d4580d967 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
@@ -176,6 +176,11 @@ final class SoftwarePacketMemoryFIFO: @unchecked Sendable {
         defer { lock.unlock() }
         try requireUsable()
         try validateLocked(cursor)
+        // Checked before any chunk changes state: a refused cursor must not leave unread chunks
+        // volatile in front of the reader.
+        guard Int(cursor.offset) + 8 <= (try chunkLocked(cursor.chunkID)).used else {
+            throw SoftwarePacketDiskFIFO.Failure.invalidCursor
+        }
         if cursor.chunkID < headID {
             try reclaimLocked(from: cursor.chunkID, through: headID - 1)
         } else {
@@ -183,8 +188,6 @@ final class SoftwarePacketMemoryFIFO: @unchecked Sendable {
             var id = headID
             while id < cursor.chunkID { try chunkLocked(id).setVolatile(true); id += 1 }
         }
-        let chunk = try chunkLocked(cursor.chunkID)
-        guard Int(cursor.offset) + 8 <= chunk.used else { throw SoftwarePacketDiskFIFO.Failure.invalidCursor }
         headID = cursor.chunkID
         headOffset = Int(cursor.offset)
         recordCount = writtenRecordCount - cursor.recordIndex
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 2252582ba..270947715 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -28,9 +28,10 @@ final class SoftwarePlaybackHost {
     /// the session retention budget apply. On an Apple TV 4K (A12) the disk store's appends took
     /// 100 to 600 ms while a download ran and the demux thread stalled behind them, so video it had
     /// parked was decoded late and dropped: 22 to 42 drops in a 150 s soak of a 4K title, against
-    /// 0 to 3 in 8 of 9 runs with the store in memory (one run had 26, not seen again). The forward window is 96 MB (about 8 s of a 95 Mbit/s
-    /// title, on top of the forward-seconds limit); played history up to 128 MB stays volatile, so
-    /// the kernel may take it back and a seek into what it took refetches. Peak footprint of a 4K
+    /// 0 to 3 in 8 of 9 runs with the store in memory (one run had 26, not seen again). The forward
+    /// window is 96 MB (about 8 s of a 95 Mbit/s title, on top of the forward-seconds limit); played
+    /// history up to 128 MB stays volatile, so the kernel may take it back and a seek into what it
+    /// took refetches. Peak footprint of a 4K
     /// FEL session on the A12: ~655 MB against ~580 MB with the disk store.
     nonisolated static let memoryPacketStoreBudget: (forwardBytes: Int, historyBytes: Int)? = {
         #if os(tvOS)

From 8205d535f74cbb9776dd8d594e0f90109f948e4d Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Thu, 15 Oct 2026 22:51:58 +0800
Subject: [PATCH 068/132] fix(video): recover H264 VOD parameter changes
 through compatible decoding

---
 CHANGELOG.md                                  |   7 +
 .../AetherEngine/AetherEngine+Loading.swift   |  14 ++
 .../AetherEngine+SoftwarePathEscalation.swift |  21 ++
 Sources/AetherEngine/AetherEngine.swift       |   9 +-
 .../Native/SoftwarePathEscalation.swift       |   2 +
 .../Video/H264ConfigurationTracker.swift      | 114 ++++++++++
 .../Video/HLSSegmentProducer.swift            |  22 ++
 .../Video/HLSVideoEngine+LiveReopen.swift     |   8 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   |  17 ++
 .../H264ConfigurationTrackerTests.swift       | 204 ++++++++++++++++++
 docs/architecture.md                          |  10 +
 docs/formats.md                               |  15 ++
 12 files changed, 439 insertions(+), 4 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/H264ConfigurationTracker.swift
 create mode 100644 Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04d7f2a09..343b7dcb5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,13 @@ the public-API contract.
 
 ### Fixed
 
+- **H.264 VOD with in-band parameter changes recovers through compatible decoding.** When an IDR
+  references SPS/PPS that differ from the AVC initialization, the producer stops before writing that
+  sample into the stale native segment. Automatic routing uses the existing software-path takeover,
+  preserving a pending seek or cold-resume position and the session transport. Repeated or unused
+  parameter sets keep the native route; an explicitly selected route or disabled escalation is honored.
+
+
 - **The Profile 7 dual-layer route recovers from a system session loss (#739).** A screen lock or sleep
   invalidates both VideoToolbox sessions; the host's recovery reached only `HardwareVideoDecoder`, so on
   the route audio played on over a frozen picture. `DualLayerVideoDecoder` now reports one loss per
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index a7b7da3a6..dec40fabd 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1157,6 +1157,13 @@ extension AetherEngine {
         // #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.
+        session.onVODVideoConfigurationChanged = { [weak self, weak session] epoch, summary in
+            Task { @MainActor in
+                guard let self, let session else { return }
+                await self.handleVODVideoConfigurationChange(session: session, epoch: epoch,
+                    summary: summary, generation: generation)
+            }
+        }
         session.onVODSourceFailed = { [weak self, weak session] code, reason, kind in
             Task { @MainActor in
                 guard let self, let session, self.nativeVideoSession === session else {
@@ -1323,6 +1330,13 @@ extension AetherEngine {
             try checkLoadCurrent(generation)
         }
         self.nativeVideoSession = session
+        if let event = session.pendingVODVideoConfigurationMismatch {
+            await handleVODVideoConfigurationChange(session: session, epoch: event.epoch,
+                summary: event.summary, generation: generation, reportRefusal: false)
+            try checkLoadCurrent(generation)
+            // If no takeover occurred, the explicitly selected route cannot serve this source.
+            throw HLSVideoEngine.HLSVideoEngineError.openFailed(reason: event.summary)
+        }
         isSourceSeekable = session.openedSourceIsSeekable
         // AE#270: anchor the display axis on the container's own start time, which is what `duration` is
         // measured from. Taking it from the session rather than latching the first published shift keeps a
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index 784152394..a5bb806a3 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -15,6 +15,27 @@ import Foundation
 /// whether the software path can serve this source at all, so a source it cannot serve costs a
 /// refusal here rather than a second dead session.
 extension AetherEngine {
+    @MainActor
+    func handleVODVideoConfigurationChange(session: HLSVideoEngine, epoch: UInt64,
+                                           summary: String, generation: UInt64,
+                                           reportRefusal: Bool = true) async {
+        guard loadGeneration == generation, nativeVideoSession === session,
+              session.pendingVODVideoConfigurationMismatch?.epoch == epoch else { return }
+        let request = SoftwarePathEscalation.Request(
+            domain: SoftwarePathEscalation.videoConfigurationErrorDomain, code: 0,
+            message: summary, positionSeconds: positionForSessionRebuild)
+        let allowed = SoftwarePathEscalation.shouldEscalate(errorDomain: request.domain,
+            availability: .init(alreadyEscalated: softwarePathEscalationBudget.isSpent,
+                preferredDecodePath: loadedOptions.preferredDecodePath,
+                nativeRemoteHLS: loadedOptions.nativeRemoteHLS,
+                hostAllowsEscalation: loadedOptions.escalatesToSoftwarePath))
+        guard allowed else {
+            if reportRefusal, !softwarePathEscalationBudget.isSpent { publishError(Self.absorbedFailure(request)) }
+            return
+        }
+        await escalateToSoftwarePath(request, expectedGeneration: generation)
+    }
+
 
     /// 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).
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 00906db0f..077470911 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2894,7 +2894,9 @@ public final class AetherEngine: ObservableObject {
     /// `#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 {
+    nonisolated static func rebuildPosition(state: PlaybackState, clock: Double, underReconstruction: Double?,
+                                            pendingSeek: Double? = nil) -> Double {
+        if let pendingSeek, pendingSeek.isFinite, pendingSeek >= 0 { return pendingSeek }
         guard let parked = underReconstruction else { return clock }
         switch state {
         case .loading: return parked
@@ -3634,7 +3636,10 @@ public final class AetherEngine: ObservableObject {
 
     /// The playhead a rebuild of this session has to come back to (#464 round 2).
     var positionForSessionRebuild: Double {
-        Self.rebuildPosition(state: state, clock: currentTime, underReconstruction: positionUnderReconstruction)
+        let pending = !isLive && nativeHost != nil
+            ? pendingRecoverySeekClockTarget.map { displaySeconds(forPlaylistSeconds: $0) } : nil
+        return Self.rebuildPosition(state: state, clock: currentTime,
+            underReconstruction: positionUnderReconstruction, pendingSeek: pending)
     }
 
     /// The transport state a rebuild of this session has to come back in (#464 round 2). Asks the
diff --git a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
index c4c61e744..5bec546a1 100644
--- a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
@@ -98,6 +98,7 @@ enum SoftwarePathEscalation {
 
     /// The domain of a media failure, i.e. AVFoundation could not make sense of what it was served.
     static let mediaErrorDomain = "CoreMediaErrorDomain"
+    static let videoConfigurationErrorDomain = "AetherEngine.VideoConfiguration"
 
     /// 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
@@ -121,5 +122,6 @@ enum SoftwarePathEscalation {
         // 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 || errorDomain == liveJoinErrorDomain
+            || errorDomain == videoConfigurationErrorDomain
     }
 }
diff --git a/Sources/AetherEngine/Video/H264ConfigurationTracker.swift b/Sources/AetherEngine/Video/H264ConfigurationTracker.swift
new file mode 100644
index 000000000..f8eb4069f
--- /dev/null
+++ b/Sources/AetherEngine/Video/H264ConfigurationTracker.swift
@@ -0,0 +1,114 @@
+import Foundation
+
+/// Pump-local evidence that an AVC access unit no longer matches the sample description.
+/// Merely repeating SPS/PPS, or announcing an unused set, is not a decoder failure.
+/// No frames are decoded and only parameter sets / short slice headers are copied.
+struct H264ConfigurationTracker {
+    struct Mismatch: Sendable, Equatable {
+        let width: Int
+        let height: Int
+        let spsID: Int
+        let ppsID: Int
+        var summary: String { "H264 active SPS/PPS differs from native init: \(width)x\(height), SPS=\(spsID), PPS=\(ppsID)" }
+    }
+
+    private let baselineSPS: [Int: [UInt8]]
+    private let baselinePPS: [Int: [UInt8]]
+    private var sps: [Int: [UInt8]]
+    private var pps: [Int: [UInt8]]
+
+    init?(avcC: [UInt8]) {
+        guard avcC.count >= 7, avcC[0] == 1, [0, 1, 3].contains(avcC[4] & 3) else { return nil }
+        var cursor = 6
+        var sequences: [Int: [UInt8]] = [:], pictures: [Int: [UInt8]] = [:]
+        func readSet() -> [UInt8]? {
+            guard cursor + 2 <= avcC.count else { return nil }
+            let size = Int(avcC[cursor]) * 256 + Int(avcC[cursor + 1]); cursor += 2
+            guard size > 0, size <= avcC.count - cursor else { return nil }
+            defer { cursor += size }
+            return Array(avcC[cursor..<(cursor + size)])
+        }
+        for _ in 0..<Int(avcC[5] & 31) {
+            guard let nal = readSet(), let id = Self.sequenceID(nal),
+                  Self.dimensions(nal) != nil, sequences[id] == nil else { return nil }
+            sequences[id] = nal
+        }
+        guard cursor < avcC.count else { return nil }
+        let count = Int(avcC[cursor]); cursor += 1
+        for _ in 0..<count {
+            guard let nal = readSet(), let ids = Self.pictureIDs(nal),
+                  sequences[ids.sps] != nil, pictures[ids.pps] == nil else { return nil }
+            pictures[ids.pps] = nal
+        }
+        guard !sequences.isEmpty, !pictures.isEmpty else { return nil }
+        baselineSPS = sequences; baselinePPS = pictures
+        sps = sequences; pps = pictures
+    }
+
+    /// All length fields must be valid before any observation is committed. In particular a
+    /// truncated packet cannot poison the state used to judge the next IDR.
+    mutating func observe(_ bytes: UnsafeBufferPointer<UInt8>, lengthSize: Int) -> Mismatch? {
+        guard [1, 2, 4].contains(lengthSize) else { return nil }
+        var cursor = 0, ranges: [Range<Int>] = []
+        while cursor < bytes.count {
+            guard bytes.count - cursor >= lengthSize, ranges.count < 4096 else { return nil }
+            var size = 0
+            for i in 0..<lengthSize { size = (size << 8) | Int(bytes[cursor + i]) }
+            cursor += lengthSize
+            guard size > 0, size <= bytes.count - cursor, bytes[cursor] & 0x80 == 0 else { return nil }
+            ranges.append(cursor..<(cursor + size)); cursor += size
+        }
+        var sequences = sps, pictures = pps
+        var mismatch: Mismatch?
+        for range in ranges {
+            switch bytes[range.lowerBound] & 31 {
+            case 7:
+                guard range.count <= 65535 else { return nil }
+                let nal = Array(bytes[range])
+                guard let id = Self.sequenceID(nal), Self.dimensions(nal) != nil else { return nil }
+                sequences[id] = nal
+            case 8:
+                guard range.count <= 65535 else { return nil }
+                let nal = Array(bytes[range])
+                guard let ids = Self.pictureIDs(nal) else { return nil }
+                pictures[ids.pps] = nal
+            case 5:
+                // Read in NAL order: sets announced after a slice do not describe that slice.
+                let prefix = Array(bytes[range.lowerBound..<min(range.upperBound, range.lowerBound + 33)])
+                guard let id = Self.slicePPS(prefix), let picture = pictures[id],
+                      let ids = Self.pictureIDs(picture), let sequence = sequences[ids.sps],
+                      let size = Self.dimensions(sequence) else { continue }
+                if baselinePPS[id] != picture || baselineSPS[ids.sps] != sequence {
+                    mismatch = Mismatch(width: size.width, height: size.height, spsID: ids.sps, ppsID: id)
+                }
+            default: break
+            }
+        }
+        sps = sequences; pps = pictures
+        return mismatch
+    }
+
+    private static func sequenceID(_ nal: [UInt8]) -> Int? {
+        guard nal.count >= 5, nal[0] & 0x9f == 7 else { return nil }
+        var r = H264SPS.BitReader(H264SPS.unescape(Array(nal.dropFirst())))
+        guard r.u(24) != nil, let id = r.ue(), id < 32 else { return nil }
+        return id
+    }
+    private static func pictureIDs(_ nal: [UInt8]) -> (pps: Int, sps: Int)? {
+        guard nal.count >= 2, nal[0] & 0x9f == 8 else { return nil }
+        var r = H264SPS.BitReader(H264SPS.unescape(Array(nal.dropFirst())))
+        guard let p = r.ue(), p < 256, let s = r.ue(), s < 32 else { return nil }
+        return (p, s)
+    }
+    private static func slicePPS(_ nal: [UInt8]) -> Int? {
+        guard nal.count >= 2, nal[0] & 0x9f == 5, nal[0] & 0x60 != 0 else { return nil }
+        var r = H264SPS.BitReader(H264SPS.unescape(Array(nal.dropFirst())))
+        guard r.ue() != nil, let type = r.ue(), type <= 9, type % 5 == 2,
+              let p = r.ue(), p < 256 else { return nil }
+        return p
+    }
+    private static func dimensions(_ nal: [UInt8]) -> (width: Int, height: Int)? {
+        guard let d = H264SPS.dimensions(fromNAL: nal), d.width <= 16384, d.height <= 16384 else { return nil }
+        return d
+    }
+}
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 8400f243b..5395ef0e7 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -343,6 +343,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
     /// keyframe's in-band sets against this triggers a versioned-init muxer rotation (the same EXT-X-MAP path SSAI
     /// uses), independent of whether the demuxer emits AV_PKT_DATA_NEW_EXTRADATA. Set at gate-open and each rotation.
     private var activeMuxerVideoExtradata: [UInt8]?
+    private var vodH264Configuration: H264ConfigurationTracker?
 
     /// #133 follow-up diag: count of same-PID in-band parameter-set changes rotated in place, surfaced in the log.
     private var samePIDReinitCount = 0
@@ -1283,6 +1284,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         case stopRequested
         case readError(code: Int32)
         case muxerFailed
+        case videoConfigurationChanged(summary: String)
         /// AE#222: the first cut could not write moov because the audio sample entry is packet-derived
         /// (E-AC-3/AC-3/TrueHD) and the source's first segment carries no audio packet. The pump captured a
         /// real audio frame on its way out (`capturedAudioMoovPrimeFrame`); the host rebuilds with it as the
@@ -1305,6 +1307,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
             case .stopRequested: return "stopRequested"
             case .readError(let code): return "readError(\(code))"
             case .muxerFailed: return "muxerFailed"
+            case .videoConfigurationChanged: return "videoConfigurationChanged"
             case .needsAudioSampleEntryPrime: return "needsAudioSampleEntryPrime"
             case .keyframeStarvation: return "keyframeStarvation"
             case .sourceReplay: return "sourceReplay"
@@ -1556,6 +1559,12 @@ final class HLSSegmentProducer: @unchecked Sendable {
             isLive: isLive,
             codecIsH264: a53CodecKind == .h264,
             framingIsAnnexB: a53NALFraming == .annexB)
+        if !isLive, a53CodecKind == .h264, case .lengthPrefixed = a53NALFraming {
+            let extra = video.extradataOverride ?? video.codecpar.pointee.extradata.map {
+                Array(UnsafeBufferPointer(start: $0, count: Int(video.codecpar.pointee.extradata_size)))
+            }
+            if let extra { vodH264Configuration = H264ConfigurationTracker(avcC: extra) }
+        }
         self.convertP7Active = video.convertP7ToProfile81
         self.audioConfig = audio
         self.cache = cache
@@ -3481,6 +3490,19 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         }
                     }
                 }
+                // AVC VOD can carry new SPS/PPS even while its file header stays unchanged.
+                // Inspect on the producer queue, before the first stale-init sample is written.
+                // An active IDR reference is required; unused/repeated sets do not change routing.
+                if packet.pointee.stream_index == videoStreamIndex,
+                   case .lengthPrefixed(let size) = a53NALFraming,
+                   let data = packet.pointee.data, packet.pointee.size > 0,
+                   let mismatch = vodH264Configuration?.observe(
+                    UnsafeBufferPointer(start: data, count: Int(packet.pointee.size)), lengthSize: size) {
+                    EngineLog.emit("[HLSSegmentProducer] \(mismatch.summary); stopping stale-init VOD epoch=\(epoch)",
+                                   category: .session)
+                    exitReason = .videoConfigurationChanged(summary: mismatch.summary)
+                    break readLoop
+                }
                 av_packet_free_side_data(packet)
 
                 let pktStreamIdx = packet.pointee.stream_index
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index 80072bdad..2aaa5f526 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -87,7 +87,7 @@ extension HLSVideoEngine {
             return true
         case .sourceReplay, .eof, .readError, .keyframeStarvation:
             return !sourceReopenable
-        case .stopRequested, .muxerFailed, .backpressureWedge, .needsAudioSampleEntryPrime:
+        case .stopRequested, .muxerFailed, .backpressureWedge, .needsAudioSampleEntryPrime, .videoConfigurationChanged:
             // muxerFailed / needsAudioSampleEntryPrime: handleLiveMuxerFailure and the AE#222 arm rebuild
             // the producer into the SAME provider, so an eager halt here would 503 the very provider the
             // rebuild is about to serve; both arms halt themselves once their budget is exhausted.
@@ -256,6 +256,10 @@ extension HLSVideoEngine {
             return
         }
         guard !alreadyRecovering else { return }
+        if case .videoConfigurationChanged(let summary) = reason {
+            recordVODVideoConfigurationMismatch(prod, summary: summary)
+            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 {
@@ -390,7 +394,7 @@ extension HLSVideoEngine {
             provider?.markLiveProductionHalted()
         }
         switch reason {
-        case .stopRequested, .muxerFailed, .backpressureWedge, .needsAudioSampleEntryPrime:
+        case .stopRequested, .muxerFailed, .backpressureWedge, .needsAudioSampleEntryPrime, .videoConfigurationChanged:
             // muxerFailed and needsAudioSampleEntryPrime never reach here (their arms above return first).
             return
         case .sourceReplay:
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 1712d19e9..bea52ad96 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -753,6 +753,23 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// source that is gone, and the reader's `-1` cannot say which, so the kind is decided here
     /// and published rather than inferred from the code downstream.
     var onVODSourceFailed: (@Sendable (Int32, String, PlaybackErrorKind) -> Void)?
+    var onVODVideoConfigurationChanged: (@Sendable (UInt64, String) -> Void)?
+    private var vodVideoConfigurationMismatch: (epoch: UInt64, summary: String)?
+
+    /// Retained because the first pump can finish before loadNative installs this session.
+    var pendingVODVideoConfigurationMismatch: (epoch: UInt64, summary: String)? {
+        restartLock.lock(); defer { restartLock.unlock() }
+        guard let event = vodVideoConfigurationMismatch, producer?.epoch == event.epoch else { return nil }
+        return event
+    }
+
+    func recordVODVideoConfigurationMismatch(_ prod: HLSSegmentProducer, summary: String) {
+        restartLock.lock()
+        guard !isLiveSession, producer === prod else { restartLock.unlock(); return }
+        vodVideoConfigurationMismatch = (prod.epoch, summary)
+        restartLock.unlock()
+        onVODVideoConfigurationChanged?(prod.epoch, summary)
+    }
 
     /// The one way a VOD session surfaces a terminal source failure (#370 follow-up).
     ///
diff --git a/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift b/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
new file mode 100644
index 000000000..c781e71f1
--- /dev/null
+++ b/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
@@ -0,0 +1,204 @@
+import Foundation
+import Combine
+import Testing
+import CoreVideo
+import AetherLibavformat
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+@Suite("H264 VOD configuration compatibility", .serialized, .offCooperativePool, .timeLimit(.minutes(2)))
+struct H264ConfigurationTrackerTests {
+    private let sps = Self.hex("6764001facd9405005bb016a02040280000003008000001e078c18cb")
+    private let changed = Self.hex("6764001facd9404c057fbc05a828282a000003000200000300781e30632c")
+    private let pps: [UInt8] = [0x68, 0xef, 0xbc, 0xb0]
+    private let idr: [UInt8] = [0x65, 0x88, 0x84, 0]
+    private static func hex(_ text: String) -> [UInt8] {
+        stride(from: 0, to: text.count, by: 2).map { offset in
+            let start = text.index(text.startIndex, offsetBy: offset)
+            return UInt8(text[start..<text.index(start, offsetBy: 2)], radix: 16)!
+        }
+    }
+    private func avcc() -> [UInt8] {
+        [1, 100, 0, 31, 255, 225, 0, UInt8(sps.count)] + sps + [1, 0, UInt8(pps.count)] + pps
+    }
+    private func packet(_ nals: [[UInt8]], size: Int = 4) -> [UInt8] {
+        nals.flatMap { nal in
+            (0..<size).reversed().map { UInt8((nal.count >> ($0 * 8)) & 255) } + nal
+        }
+    }
+    private func observe(_ tracker: inout H264ConfigurationTracker, _ nals: [[UInt8]], size: Int = 4) -> H264ConfigurationTracker.Mismatch? {
+        packet(nals, size: size).withUnsafeBufferPointer { tracker.observe($0, lengthSize: size) }
+    }
+
+    @Test("Repeated sets and ordinary IDRs keep the native path")
+    func repeatedSets() throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc()))
+        for _ in 0..<5 { #expect(observe(&tracker, [sps, pps, idr]) == nil) }
+        #expect(observe(&tracker, [idr]) == nil)
+    }
+    @Test("Same-ID parameter changes are judged by the slice's actual references", arguments: [1, 2, 4])
+    func activeChange(size: Int) throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc()))
+        let result = observe(&tracker, [changed, pps, idr], size: size)
+        #expect(result?.width == 1216)
+        #expect(result?.height == 684)
+        #expect(result?.spsID == 0)
+        #expect(result?.ppsID == 0)
+    }
+    @Test("Announcing an unused PPS does not reroute playback")
+    func unusedPictureSet() throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc()))
+        #expect(observe(&tracker, [[0x68, 0x58], idr]) == nil) // PPS 1 refers to SPS 0; slice uses PPS 0
+    }
+    @Test("A changed set is retained until an IDR actually uses it")
+    func separateSets() throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc()))
+        #expect(observe(&tracker, [changed]) == nil)
+        #expect(observe(&tracker, [[0x41, 0x9a, 0, 0]]) == nil)
+        #expect(observe(&tracker, [idr]) != nil)
+        #expect(observe(&tracker, [sps, idr]) == nil)
+    }
+    @Test("NAL ordering does not apply future parameter sets to an earlier slice")
+    func nalOrdering() throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc()))
+        #expect(observe(&tracker, [idr, changed]) == nil)
+        #expect(observe(&tracker, [idr]) != nil)
+    }
+    @Test("Truncated lengths and malformed parameter sets cannot poison later decisions")
+    func malformedInput() throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc()))
+        for tail: [UInt8] in [[0xff,0xff,0xff,0xff], [0,0], [0,0,0,0], [0,0,0,2,0xe7,0]] {
+            let bytes = packet([changed]) + tail
+            #expect(bytes.withUnsafeBufferPointer { tracker.observe($0, lengthSize: 4) } == nil)
+            #expect(observe(&tracker, [idr]) == nil)
+        }
+        #expect(observe(&tracker, [[0x67], idr]) == nil)
+        #expect(observe(&tracker, [idr]) == nil)
+        #expect(H264ConfigurationTracker(avcC: Array(avcc().dropLast())) == nil)
+        #expect(H264ConfigurationTracker(avcC: [1,2,3]) == nil)
+    }
+    @Test("The new media verdict respects explicit route, host and once-only constraints")
+    func escalationPolicy() {
+        let domain = SoftwarePathEscalation.videoConfigurationErrorDomain
+        #expect(SoftwarePathEscalation.shouldEscalate(errorDomain: domain,
+            availability: .init(alreadyEscalated: false, preferredDecodePath: .automatic, nativeRemoteHLS: false)))
+        for a in [
+            SoftwarePathEscalation.Availability(alreadyEscalated: true, preferredDecodePath: .automatic, nativeRemoteHLS: false),
+            .init(alreadyEscalated: false, preferredDecodePath: .software, nativeRemoteHLS: false),
+            .init(alreadyEscalated: false, preferredDecodePath: .automatic, nativeRemoteHLS: false, hostAllowsEscalation: false),
+            .init(alreadyEscalated: false, preferredDecodePath: .automatic, nativeRemoteHLS: true)
+        ] { #expect(!SoftwarePathEscalation.shouldEscalate(errorDomain: domain, availability: a)) }
+    }
+    @Test("A reload retains the pending user seek instead of the producer or frozen clock")
+    func pendingSeekPosition() {
+        #expect(AetherEngine.rebuildPosition(state: .seeking, clock: 10, underReconstruction: nil, pendingSeek: 585.9) == 585.9)
+        #expect(AetherEngine.rebuildPosition(state: .paused, clock: 10, underReconstruction: nil, pendingSeek: 0) == 0)
+        #expect(AetherEngine.rebuildPosition(state: .loading, clock: 0, underReconstruction: 585.9) == 585.9)
+        #expect(AetherEngine.rebuildPosition(state: .playing, clock: 10, underReconstruction: nil, pendingSeek: .nan) == 10)
+    }
+
+    private final class Results: @unchecked Sendable {
+        let lock = NSLock()
+        private var dimensions: [String] = []
+        private var exit: HLSSegmentProducer.PumpExitReason?
+        func frame(_ buffer: CVPixelBuffer) { lock.lock(); defer { lock.unlock() }; dimensions.append("\(CVPixelBufferGetWidth(buffer))x\(CVPixelBufferGetHeight(buffer))") }
+        func finish(_ reason: HLSSegmentProducer.PumpExitReason) { lock.lock(); defer { lock.unlock() }; exit = reason }
+        var frames: [String] { lock.lock(); defer { lock.unlock() }; return dimensions }
+        var reason: HLSSegmentProducer.PumpExitReason? { lock.lock(); defer { lock.unlock() }; return exit }
+    }
+    private func demuxer() throws -> Demuxer {
+        let dem = Demuxer()
+        try dem.open(reader: DataIOReader(data: Self.synthetic), formatHint: "mp4")
+        return dem
+    }
+    @Test("Actual changing-size MP4 is decoded through both changes by the existing compatible decoder")
+    func compatibleDecoder() throws {
+        let dem = try demuxer(); defer { dem.close() }
+        let stream = try #require(dem.stream(at: dem.videoStreamIndex))
+        let result = Results(), decoder = SoftwareVideoDecoder()
+        decoder.decodesSingleThreaded = true
+        try decoder.open(stream: stream) { buffer, _, _ in result.frame(buffer) }
+        defer { decoder.close() }
+        while let pkt = try dem.readPacket() {
+            if pkt.pointee.stream_index == dem.videoStreamIndex { decoder.decode(packet: pkt) }
+            var owned: UnsafeMutablePointer<AVPacket>? = pkt; av_packet_free(&owned)
+        }
+        #expect(result.frames.count == 72)
+        #expect(Array(result.frames.prefix(24)) == Array(repeating: "128x96", count: 24))
+        #expect(Array(result.frames.dropFirst(24).prefix(24)) == Array(repeating: "192x128", count: 24))
+        #expect(Array(result.frames.suffix(24)) == Array(repeating: "128x96", count: 24))
+    }
+    @Test("The real producer stops before writing changed-configuration video into its original init", arguments: [false, true])
+    func producerStopsOnChange(coldResume: Bool) async throws {
+        let dem = try demuxer(); defer { dem.close() }
+        let stream = try #require(dem.stream(at: dem.videoStreamIndex))
+        if coldResume { #expect(dem.seek(to: 2.0)) }
+        let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)
+        defer { cache.close() }
+        let result = Results()
+        let producer = try HLSSegmentProducer(demuxer: dem, videoStreamIndex: dem.videoStreamIndex,
+            video: .init(codecpar: UnsafePointer(stream.pointee.codecpar), timeBase: stream.pointee.time_base, codecTagOverride: nil),
+            cache: cache, videoFallbackDurationPts: 100000, desiredFirstVideoTfdtPts: 0,
+            segmentBoundaries: [0, 4800000, 7200000])
+        producer.onPumpFinished = { result.finish($0) }
+        producer.start()
+        defer { producer.stop(); _ = producer.waitForFinish(timeout: 2) }
+        try await waitFor { result.reason != nil }
+        try await waitFor { producer.waitForFinish(timeout: 0) }
+        guard case .videoConfigurationChanged = result.reason else { Issue.record("expected typed config exit, got \(String(describing: result.reason))"); return }
+        #expect(cache.count == 0, "a partial stale-config segment must not be cached")
+    }
+
+    @Test("A superseded pump cannot reroute a successor, and a retained early verdict is epoch-specific")
+    func stalePumpVerdict() throws {
+        let dem = try demuxer(); defer { dem.close() }
+        let stream = try #require(dem.stream(at: dem.videoStreamIndex))
+        let cache = SegmentCache(forwardWindow: 4, backwardWindow: 4)
+        defer { cache.close() }
+        func producer(epoch: UInt64) throws -> HLSSegmentProducer {
+            try HLSSegmentProducer(demuxer: dem, videoStreamIndex: dem.videoStreamIndex,
+                video: .init(codecpar: UnsafePointer(stream.pointee.codecpar), timeBase: stream.pointee.time_base, codecTagOverride: nil),
+                cache: cache, videoFallbackDurationPts: 100000, desiredFirstVideoTfdtPts: 0,
+                segmentBoundaries: [0, 7200000], epoch: epoch)
+        }
+        let engine = HLSVideoEngine(url: URL(fileURLWithPath: "/synthetic.mp4"), dvModeAvailable: false)
+        let old = try producer(epoch: 1), current = try producer(epoch: 2)
+        engine.producer = current
+        engine.handlePumpFinished(old, reason: .videoConfigurationChanged(summary: "synthetic change"))
+        #expect(engine.pendingVODVideoConfigurationMismatch == nil)
+        engine.handlePumpFinished(current, reason: .videoConfigurationChanged(summary: "synthetic change"))
+        #expect(engine.pendingVODVideoConfigurationMismatch?.epoch == 2)
+        engine.producer = old
+        #expect(engine.pendingVODVideoConfigurationMismatch == nil)
+        engine.producer = nil
+        #expect(engine.pendingVODVideoConfigurationMismatch == nil)
+    }
+
+    @Test("A complete cold load follows the compatibility takeover and retains its paused resume", .timeLimit(.minutes(1)))
+    @MainActor
+    func fullColdResume() async throws {
+        let file = FileManager.default.temporaryDirectory.appendingPathComponent("h264-change-\(UUID().uuidString).mp4")
+        try Self.synthetic.write(to: file)
+        defer { try? FileManager.default.removeItem(at: file) }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        var events: [SoftwarePathEscalationEvent] = []
+        let subscription = engine.softwarePathEscalations.sink { events.append($0) }
+        defer { subscription.cancel() }
+        try await engine.load(url: file, startPosition: 2.0,
+            options: LoadOptions(suppressDisplayCriteria: true, autoplay: false))
+        #expect(engine.loadedOptions.preferredDecodePath == .software)
+        #expect(engine.softwareHost != nil)
+        #expect(events.count == 1)
+        #expect(events.first?.absorbedFailure.underlyingDomain == SoftwarePathEscalation.videoConfigurationErrorDomain)
+        #expect(events.first?.positionSeconds == 2.0)
+        #expect(engine.state == .paused)
+        #expect(abs(engine.positionForSessionRebuild - 2.0) < 0.1)
+    }
+
+    // Generated solid-colour H.264, 12 fps, 128x96 -> 192x128 -> 128x96, 24 frames per run.
+    // x264 main/bframes=0/repeat-headers=1/keyint=12/scenecut=0; stream-copy into MP4.
+    // Contains no user media or external fixtures.
+    private static let synthetic = Data(base64Encoded: "AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAARYbW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAF3AAAQAAAQAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAA4J0cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAF3AAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAIAAAABgAAAAAAAkZWR0cwAAABxlbHN0AAAAAAAAAAEAABdwAAAAAAABAAAAAAL6bWRpYQAAACBtZGhkAAAAAAAAAAAAAAAAAAAwAAABIABVxAAAAAAALWhkbHIAAAAAAAAAAHZpZGUAAAAAAAAAAAAAAABWaWRlb0hhbmRsZXIAAAACpW1pbmYAAAAUdm1oZAAAAAEAAAAAAAAAAAAAACRkaW5mAAAAHGRyZWYAAAAAAAAAAQAAAAx1cmwgAAAAAQAAAmVzdGJsAAAAuXN0c2QAAAAAAAAAAQAAAKlhdmMxAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAIAAYABIAAAASAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGP//AAAAL2F2Y0MBTUAK/+EAF2dNQArZAg2wEQAAAwABAAADABgPEiZIAQAFaOvDyyAAAAAQcGFzcAAAAAEAAAABAAAAFGJ0cnQAAAAAAAATEgAAExIAAAAYc3R0cwAAAAAAAAABAAAASAAABAAAAAAoc3RzcwAAAAAAAAAGAAAAAQAAAA0AAAAZAAAAJQAAADEAAAA9AAAAHHN0c2MAAAAAAAAAAQAAAAEAAABIAAAAAQAAATRzdHN6AAAAAAAAAAAAAABIAAACywAAAA4AAAASAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAWgAAAA4AAAASAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAACzwAAAA8AAAATAAAAFAAAABQAAAAUAAAAFAAAABQAAAAUAAAAFAAAABQAAAAUAAAAXgAAAA8AAAATAAAAFAAAABQAAAAUAAAAFAAAABQAAAAUAAAAFAAAABQAAAATAAACywAAAA4AAAASAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAWgAAAA4AAAASAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAEwAAABMAAAATAAAAFHN0Y28AAAAAAAAAAQAABIgAAABidWR0YQAAAFptZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAAC1pbHN0AAAAJal0b28AAAAdZGF0YQAAAAEAAAAATGF2ZjYyLjEyLjEwMgAAAAhmcmVlAAAOVm1kYXQAAAAXZ01ACtkCDbARAAADAAEAAAMAGA8SJkgAAAAFaOvDyyAAAAJuBgX//2rcRem95tlIt5Ys2CDZI+7veDI2NCAtIGNvcmUgMTY1IHIzMjIyIGIzNTYwNWEgLSBILjI2NC9NUEVHLTQgQVZDIGNvZGVjIC0gQ29weWxlZnQgMjAwMy0yMDI1IC0gaHR0cDovL3d3dy52aWRlb2xhbi5vcmcveDI2NC5odG1sIC0gb3B0aW9uczogY2FiYWM9MSByZWY9MyBkZWJsb2NrPTE6MDowIGFuYWx5c2U9MHgxOjB4MTExIG1lPWhleCBzdWJtZT03IHBzeT0xIHBzeV9yZD0xLjAwOjAuMDAgbWl4ZWRfcmVmPTEgbWVfcmFuZ2U9MTYgY2hyb21hX21lPTEgdHJlbGxpcz0xIDh4OGRjdD0wIGNxbT0wIGRlYWR6b25lPTIxLDExIGZhc3RfcHNraXA9MSBjaHJvbWFfcXBfb2Zmc2V0PS0yIHRocmVhZHM9MyBsb29rYWhlYWRfdGhyZWFkcz0xIHNsaWNlZF90aHJlYWRzPTAgbnI9MCBkZWNpbWF0ZT0xIGludGVybGFjZWQ9MCBibHVyYXlfY29tcGF0PTAgY29uc3RyYWluZWRfaW50cmE9MCBiZnJhbWVzPTAgd2VpZ2h0cD0yIGtleWludD0xMiBrZXlpbnRfbWluPTEgc2NlbmVjdXQ9MCBpbnRyYV9yZWZyZXNoPTAgcmNfbG9va2FoZWFkPTEyIHJjPWNyZiBtYnRyZWU9MSBjcmY9MjMuMCBxY29tcD0wLjYwIHFwbWluPTAgcXBtYXg9NjkgcXBzdGVwPTQgaXBfcmF0aW89MS40MCBhcT0xOjEuMDAAgAAAADFliIQO//7jq/gU0a+hz3ekUTev9GNPzxSXbPITNz7p7w7e/dKvNRLGVo4gAEUARNdRAAAACkGaOxDv/qmWAdcAAAAOQZpPCGTKYQ7//qmWAdcAAAAPQZpyeEPJlMCHf/6plgHXAAAAD0GaknhDyZTAh3/+qZYB1wAAAA9BmrJ4Q8mUwId//qmWAdcAAAAPQZrSeEPJlMCHf/6plgHXAAAAD0Ga8nhDyZTAh3/+qZYB1wAAAA9BmxJ4Q8mUwId//qmWAdcAAAAPQZsyeEPJlMCHf/6plgHXAAAAD0GbUnhDyZTAh3/+qZYB1wAAAA9Bm3J4Q8mUwId//qmWAdcAAAAXZ01ACtkCDbARAAADAAEAAAMAGA8SJkgAAAAFaOvDyyAAAAAyZYiCAR/+5+P8CmsrEcS/TVAozem13Ki6NeHVxiFPV496VvShGB0NowomRTgACoALC1IAAAAKQZo7EO/+qZYB1wAAAA5Bmk8IZMphDv/+qZYB1wAAAA9BmnJ4Q8mUwId//qmWAdcAAAAPQZqSeEPJlMCHf/6plgHXAAAAD0GasnhDyZTAh3/+qZYB1wAAAA9BmtJ4Q8mUwId//qmWAdcAAAAPQZryeEPJlMCHf/6plgHXAAAAD0GbEnhDyZTAh3/+qZYB1wAAAA9BmzJ4Q8mUwId//qmWAdcAAAAPQZtSeEPJlMCG//6nhAOmAAAAD0GbcnhDyZTAhn/+nhANiQAAABZnTUAK2QMEbARAAAADAEAAAAYDxImSAAAABWjrw8sgAAACbgYF//9q3EXpvebZSLeWLNgg2SPu73gyNjQgLSBjb3JlIDE2NSByMzIyMiBiMzU2MDVhIC0gSC4yNjQvTVBFRy00IEFWQyBjb2RlYyAtIENvcHlsZWZ0IDIwMDMtMjAyNSAtIGh0dHA6Ly93d3cudmlkZW9sYW4ub3JnL3gyNjQuaHRtbCAtIG9wdGlvbnM6IGNhYmFjPTEgcmVmPTMgZGVibG9jaz0xOjA6MCBhbmFseXNlPTB4MToweDExMSBtZT1oZXggc3VibWU9NyBwc3k9MSBwc3lfcmQ9MS4wMDowLjAwIG1peGVkX3JlZj0xIG1lX3JhbmdlPTE2IGNocm9tYV9tZT0xIHRyZWxsaXM9MSA4eDhkY3Q9MCBjcW09MCBkZWFkem9uZT0yMSwxMSBmYXN0X3Bza2lwPTEgY2hyb21hX3FwX29mZnNldD0tMiB0aHJlYWRzPTQgbG9va2FoZWFkX3RocmVhZHM9MSBzbGljZWRfdGhyZWFkcz0wIG5yPTAgZGVjaW1hdGU9MSBpbnRlcmxhY2VkPTAgYmx1cmF5X2NvbXBhdD0wIGNvbnN0cmFpbmVkX2ludHJhPTAgYmZyYW1lcz0wIHdlaWdodHA9MiBrZXlpbnQ9MTIga2V5aW50X21pbj0xIHNjZW5lY3V0PTAgaW50cmFfcmVmcmVzaD0wIHJjX2xvb2thaGVhZD0xMiByYz1jcmYgbWJ0cmVlPTEgY3JmPTIzLjAgcWNvbXA9MC42MCBxcG1pbj0wIHFwbWF4PTY5IHFwc3RlcD00IGlwX3JhdGlvPTEuNDAgYXE9MToxLjAwAIAAAAA2ZYiEDv/+46v4FNhQVHRMxSj+hbRjT88Ul2zyEzccr/4LaIPONJvMMbtZDakAAKOAE6F3vuhBAAAAC0GaOxDv/qmWAFNAAAAAD0GaTwhkymEO//6plgBTQQAAABBBmnJ4Q8mUwId//qmWAFNAAAAAEEGaknhDyZTAh3/+qZYAU0EAAAAQQZqyeEPJlMCHf/6plgBTQQAAABBBmtJ4Q8mUwId//qmWAFNBAAAAEEGa8nhDyZTAh3/+qZYAU0EAAAAQQZsSeEPJlMCHf/6plgBTQAAAABBBmzJ4Q8mUwId//qmWAFNAAAAAEEGbUnhDyZTAh3/+qZYAU0EAAAAQQZtyeEPJlMCHf/6plgBTQAAAABZnTUAK2QMEbARAAAADAEAAAAYDxImSAAAABWjrw8sgAAAAN2WIggEf/ufj/AptfMRxOnYY+vfW13Ki6NeHVxiFPILozHYyXiM13/cmd8Ndx3AAbcAK8NnxMuAAAAALQZo7EO/+qZYAU0EAAAAPQZpPCGTKYQ7//qmWAFNBAAAAEEGacnhDyZTAh3/+qZYAU0EAAAAQQZqSeEPJlMCHf/6plgBTQAAAABBBmrJ4Q8mUwId//qmWAFNAAAAAEEGa0nhDyZTAh3/+qZYAU0EAAAAQQZryeEPJlMCHf/6plgBTQAAAABBBmxJ4Q8mUwId//qmWAFNAAAAAEEGbMnhDyZTAh3/+qZYAU0EAAAAQQZtSeEPJlMCG//6nhACkgAAAAA9Bm3J4Q8mUwIZ//p4QAn8AAAAXZ01ACtkCDbARAAADAAEAAAMAGA8SJkgAAAAFaOvDyyAAAAJuBgX//2rcRem95tlIt5Ys2CDZI+7veDI2NCAtIGNvcmUgMTY1IHIzMjIyIGIzNTYwNWEgLSBILjI2NC9NUEVHLTQgQVZDIGNvZGVjIC0gQ29weWxlZnQgMjAwMy0yMDI1IC0gaHR0cDovL3d3dy52aWRlb2xhbi5vcmcveDI2NC5odG1sIC0gb3B0aW9uczogY2FiYWM9MSByZWY9MyBkZWJsb2NrPTE6MDowIGFuYWx5c2U9MHgxOjB4MTExIG1lPWhleCBzdWJtZT03IHBzeT0xIHBzeV9yZD0xLjAwOjAuMDAgbWl4ZWRfcmVmPTEgbWVfcmFuZ2U9MTYgY2hyb21hX21lPTEgdHJlbGxpcz0xIDh4OGRjdD0wIGNxbT0wIGRlYWR6b25lPTIxLDExIGZhc3RfcHNraXA9MSBjaHJvbWFfcXBfb2Zmc2V0PS0yIHRocmVhZHM9MyBsb29rYWhlYWRfdGhyZWFkcz0xIHNsaWNlZF90aHJlYWRzPTAgbnI9MCBkZWNpbWF0ZT0xIGludGVybGFjZWQ9MCBibHVyYXlfY29tcGF0PTAgY29uc3RyYWluZWRfaW50cmE9MCBiZnJhbWVzPTAgd2VpZ2h0cD0yIGtleWludD0xMiBrZXlpbnRfbWluPTEgc2NlbmVjdXQ9MCBpbnRyYV9yZWZyZXNoPTAgcmNfbG9va2FoZWFkPTEyIHJjPWNyZiBtYnRyZWU9MSBjcmY9MjMuMCBxY29tcD0wLjYwIHFwbWluPTAgcXBtYXg9NjkgcXBzdGVwPTQgaXBfcmF0aW89MS40MCBhcT0xOjEuMDAAgAAAADFliIQO//7jq/gU0a+hz3ekUTev9GNPzxSXbPITNz7p7w7e/dKvNRLGVo4gAEUARNdRAAAACkGaOxDv/qmWAdcAAAAOQZpPCGTKYQ7//qmWAdcAAAAPQZpyeEPJlMCHf/6plgHXAAAAD0GaknhDyZTAh3/+qZYB1wAAAA9BmrJ4Q8mUwId//qmWAdcAAAAPQZrSeEPJlMCHf/6plgHXAAAAD0Ga8nhDyZTAh3/+qZYB1wAAAA9BmxJ4Q8mUwId//qmWAdcAAAAPQZsyeEPJlMCHf/6plgHXAAAAD0GbUnhDyZTAh3/+qZYB1wAAAA9Bm3J4Q8mUwId//qmWAdcAAAAXZ01ACtkCDbARAAADAAEAAAMAGA8SJkgAAAAFaOvDyyAAAAAyZYiCAR/+5+P8CmsrEcS/TVAozem13Ki6NeHVxiFPV496VvShGB0NowomRTgACoALC1IAAAAKQZo7EO/+qZYB1wAAAA5Bmk8IZMphDv/+qZYB1wAAAA9BmnJ4Q8mUwId//qmWAdcAAAAPQZqSeEPJlMCHf/6plgHXAAAAD0GasnhDyZTAh3/+qZYB1wAAAA9BmtJ4Q8mUwId//qmWAdcAAAAPQZryeEPJlMCHf/6plgHXAAAAD0GbEnhDyZTAh3/+qZYB1wAAAA9BmzJ4Q8mUwId//qmWAdcAAAAPQZtSeEPJlMCG//6nhAOmAAAAD0GbcnhDyZTAhn/+nhANiQ==")!
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index f82ee8048..a934bbdf7 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -22,6 +22,16 @@ Source URL ──► Demuxer ──► HLSSegmentProducer ──► SegmentCache
 
 Why HLS-fMP4 for the native path instead of feeding `AVPlayer` the source URL directly: AVPlayer's progressive-download path won't accept arbitrary MKV containers, and even for MP4 sources it's brittle around Dolby Vision sample-description quirks and EAC3 `dec3` box variants. The HLS-fMP4 wrapper is the most permissive surface AVPlayer exposes; libavformat's `hls` muxer produces bytes byte-identical to `ffmpeg -f hls -hls_segment_type fmp4`, which is what Apple's HLS spec is defined against.
 
+**AVC VOD configuration changes are judged before native muxing.** `H264ConfigurationTracker`
+starts from the producer’s effective `avcC`, follows length-prefixed SPS/PPS in NAL order, and checks
+the pair referenced by an IDR against that baseline. A mismatch exits the pump with a typed reason
+before the changed sample is written; the session retains the verdict for a pump that finishes before
+its owning load is installed. Producer epoch and load generation checks reject superseded events.
+The existing `SoftwarePathEscalation` takeover owns recovery under its normal route and host opt-in
+constraints. Rebuilding uses the pending user seek, or the actual playhead, never the producer’s
+read-ahead position. This avoids relying on a static VOD playlist refreshing an `EXT-X-MAP` after it
+has already been loaded.
+
 **Item diagnostics must not become playback work.** `accessLog()` and `errorLog()` can synchronously
 wait on AVFoundation's media-service queues, even when called from an item notification. The video
 host's log notifications and failure dump, the audio-only error observer, and outgoing-item counter
diff --git a/docs/formats.md b/docs/formats.md
index df8520da8..4a4e7ce2b 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -24,6 +24,21 @@ That list is the supported set, not the compiled set. The FFmpeg build also carr
 
 Interlaced sources (DVD-rip MPEG-2, SD / HD broadcast H.264) are deinterlaced through a persistent bwdif graph (yadif fallback) that engages on the first interlaced frame and costs nothing on progressive content. The dispatch decision lives in `AetherEngine.load` (`VideoRoutingPolicy`), gated per source on `VTCapabilityProbe`, codec id, declared field order, and on VOD the decode sample that verifies it.
 
+### H.264 VOD with changing parameter sets
+
+A length-prefixed H.264 file can retain its original `avcC` while later samples carry different
+SPS/PPS, including a resolution change under the same parameter-set IDs. Native HLS can then play
+audio without displaying video, including after seeking or reopening at that position. The producer
+checks the parameter sets actually referenced by an IDR before writing it into the native segment;
+repeated sets and announcements that no IDR uses do not change the route.
+
+In automatic mode, with `escalatesToSoftwarePath` enabled, a confirmed mismatch uses the existing
+native-to-software takeover. The software decoder accepts the changing frame dimensions, while the
+rebuild preserves the requested seek/resume position and session transport. This can briefly buffer
+and costs software decoding CPU; the native-only features described below are unavailable on that
+route. Explicit decode-path choices and disabled escalation are honored, with an error when the native
+initialization cannot serve the source. Live Annex-B configuration rotation is unchanged.
+
 ### MP4 without composition offsets
 
 Some writers emit a sample table with no `ctts` while the H.264 or HEVC bitstream still reorders pictures.

From a16ad600bc5342f3f9328d52a925503a862ef4e9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 17:09:17 +0200
Subject: [PATCH 069/132] fix(live): only a refusal gets the live ingest's
 minute of retries (#778 follow-up)

PR #778 gave every failed refresh and segment fetch 60 s of steady
retries, transport errors and any 5xx included. A dead channel or a lost
network then sat behind a spinner for up to a minute (measured 59.7 s
on the loopback) before the host's reopen or fallback got a turn.

Only the refusal statuses (429, 503, 509) get the 60 s budget now;
anything else keeps the 12 s that bridges a single CDN timeout. A retry
loop keeps the longest budget it has seen, so one transport blip inside
a refusal window does not end it.

The playlist Retry-After is also cleared before every attempt, so a
value left over from an earlier refusal is never applied to a later one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  6 ++-
 .../IO/HLSIngest/HLSLiveIngestReader.swift    | 40 +++++++++++++------
 .../HLSLiveIngestRefusalTests.swift           | 36 +++++++++++++++++
 3 files changed, 68 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dfaf6ed90..c22d6690a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,8 +49,10 @@ the public-API contract.
   goes on refusing a session it evicted, while a fresh session from the loaded URL is admitted at
   once. The ingest retried 1, 2 and 4 s apart and went terminal at 12 s, which on the software path
   ended the session, and each refusal armed the origin's request pacer, so the host's reload then
-  waited up to 10 s for its first request. A refused or unreachable refresh is now asked again every
-  second, or after the origin's Retry-After up to 5 s, for up to 60 s, and so is a refused segment. A
+  waited up to 10 s for its first request. A refused refresh (429, 503, 509) is now asked again every
+  second, or after the origin's Retry-After up to 5 s, for up to 60 s, and so is a refused segment; an
+  unreachable origin or any other 5xx keeps the 12 s budget, so a dead channel or a lost network still
+  reaches the host's reopen or fallback as soon as before. A
   session URL the loaded URL led to through redirects is asked for afresh through the loaded URL once
   it has been refused twice, or at once when it answers as gone (a 4xx other than 429 and 408); the
   playlist tracker follows MEDIA-SEQUENCE, so the segments continue where they left off. The live
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 9880a3b9c..554e2c79d 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -585,8 +585,8 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         }
     }
 
-    /// How long a live refresh is retried while the origin refuses it (429, 5xx including 509) or
-    /// cannot be reached. It outlasts what a session holds ahead of the playhead, so a refusal that
+    /// How long a live refresh is retried while the origin refuses it (`refusalStatuses`: 429, 503,
+    /// 509). It outlasts what a session holds ahead of the playhead, so a refusal that
     /// ends while the picture is still playing from it is never seen: the host's own stall handling
     /// steps in once that runs dry. A connection-limited IPTV panel answers 509 for as long as another
     /// device on the account holds its last slot, which is seconds to tens of seconds when that device
@@ -594,6 +594,19 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     /// terminal well inside such a window, and on the software path that ended the session.
     static let refreshRetryBudget: TimeInterval = 60
 
+    /// How long a refresh or segment is retried when the origin cannot be reached or answers with any
+    /// other 5xx. That is not a refusal that lifts by itself: a dead channel or a lost network would
+    /// otherwise sit behind a spinner for a minute before the host's reopen or fallback gets a turn.
+    /// FIFO and producer buffer give 10 to 20 s of slack, so 12 s still bridges a single CDN timeout.
+    static let unreachableRetryBudget: TimeInterval = 12
+
+    /// The retry budget for a failure with this HTTP status, nil for a transport error. A retry loop
+    /// keeps the longest budget it has seen, so one transport blip inside a refusal does not end it.
+    static func retryBudget(forStatus status: Int?) -> TimeInterval {
+        guard let status, refusalStatuses.contains(status) else { return unreachableRetryBudget }
+        return refreshRetryBudget
+    }
+
     /// The steady wait between those retries. One small request a second, never growing: a refusal of
     /// this kind lifts the moment the other device lets its slot go, and a growing backoff only adds
     /// to the wait after that. An origin's own Retry-After stretches it, up to `maximumRetryWait`.
@@ -621,11 +634,12 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     /// once. Returns the playlist and the URL it was read from, which later refreshes use.
     private func refreshMediaPlaylist(_ mediaURL: URL, canReresolve: Bool) async throws -> (HLSMediaPlaylist, URL) {
         let startedAt = Date()
-        let deadline = startedAt.addingTimeInterval(Self.refreshRetryBudget)
+        var budget = Self.unreachableRetryBudget
         var url = mediaURL
         var failures = 0
         while true {
             try Task.checkCancellation()
+            startLock.withLock { _playlistRetryAfter = nil }
             do {
                 let (playlist, finalURL) = try await fetchPlaylist(url)
                 guard case .media(let media) = playlist else {
@@ -652,7 +666,8 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     continue
                 }
                 failures += 1
-                try await waitBeforeRetrying(error, failures: failures, deadline: deadline)
+                budget = max(budget, Self.retryBudget(forStatus: status))
+                try await waitBeforeRetrying(error, failures: failures, deadline: startedAt.addingTimeInterval(budget))
                 url = Self.nextRefreshURL(after: failures, current: url, sessionURL: mediaURL,
                                           loadedURL: playlistURL, canReresolve: canReresolve)
             } catch is CancellationError {
@@ -660,7 +675,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
             } catch {
                 if (error as? URLError)?.code == .cancelled { throw error }
                 failures += 1
-                try await waitBeforeRetrying(error, failures: failures, deadline: deadline)
+                try await waitBeforeRetrying(error, failures: failures, deadline: startedAt.addingTimeInterval(budget))
                 url = Self.nextRefreshURL(after: failures, current: url, sessionURL: mediaURL,
                                           loadedURL: playlistURL, canReresolve: canReresolve)
             }
@@ -694,10 +709,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     }
 
     private func waitBeforeRetrying(_ error: Error, failures: Int, deadline: Date) async throws {
-        let retryAfter = startLock.withLock { () -> TimeInterval? in
-            defer { _playlistRetryAfter = nil }
-            return _playlistRetryAfter
-        }
+        let retryAfter = startLock.withLock { _playlistRetryAfter }
         let delay = Self.retryWait(retryAfter: retryAfter)
         guard Date().addingTimeInterval(delay) < deadline else { throw error }
         if failures <= Self.loggedRetries || failures % Self.retryLogStride == 0 {
@@ -780,11 +792,13 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     private func fetchSegment(_ url: URL, duration: Double) async throws -> Data {
         var lastStatus = -1
         let limit = BoundedFetch.segmentLimit(forDuration: duration)
-        let deadline = Date().addingTimeInterval(Self.refreshRetryBudget)
+        let startedAt = Date()
+        var budget = Self.unreachableRetryBudget
         var attempt = 0
         while true {
             if Task.isCancelled { throw CancellationError() }
             var retryAfter: TimeInterval?
+            var status: Int?
             do {
                 let (data, response): (Data, URLResponse)
                 do {
@@ -796,6 +810,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     throw HLSIngestError.playlistInvalid(reason: "segment exceeds \(limit) bytes")
                 }
                 lastStatus = (response as? HTTPURLResponse)?.statusCode ?? -1
+                status = lastStatus
                 if (200..<300).contains(lastStatus) { return data }
                 if lastStatus == 404 { return Data() } // slid out of provider window; tracker advances regardless
                 if (400..<500).contains(lastStatus) && lastStatus != 429 {
@@ -807,9 +822,10 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
             catch { /* transport blip: retry */ }
             attempt += 1
             // Two quick retries for a blip, as before; then the steady pace of a refused refresh,
-            // for as long as the refresh itself would keep trying.
+            // within the same budget the refresh would get for this failure.
             let delay = attempt <= 2 ? 0.5 * Double(attempt) : Self.retryWait(retryAfter: retryAfter)
-            guard Date().addingTimeInterval(delay) < deadline else {
+            budget = max(budget, Self.retryBudget(forStatus: status))
+            guard Date().addingTimeInterval(delay) < startedAt.addingTimeInterval(budget) else {
                 throw HLSIngestError.playlistUnreachable(status: lastStatus)
             }
             try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
diff --git a/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift b/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift
index 32f0f3d57..2069f3d28 100644
--- a/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift
+++ b/Tests/AetherEngineTests/HLSLiveIngestRefusalTests.swift
@@ -316,6 +316,42 @@ struct HLSLiveIngestRefusalTests {
         #expect(origin.requestCount("/media.m3u8") == 2)
     }
 
+    @Test("a broken refresh that is not a refusal ends on the short budget")
+    func brokenRefreshEndsOnShortBudget() async throws {
+        // 502 is a broken gateway, not an origin saying "not now": a dead channel must reach the
+        // host's reopen or fallback after the short budget, not after the minute a refusal gets.
+        let origin = try #require(ScriptedOrigin { path, index in
+            if path == "/media.m3u8" {
+                return index == 0
+                    ? .init(status: 200, body: Self.playlist(count: 8, endList: false))
+                    : .init(status: 502)
+            }
+            if let segment = Self.segmentIndex(path) { return .init(status: 200, body: Self.segment(segment)) }
+            return .init(status: 404)
+        })
+        defer { origin.stop() }
+
+        let reader = HLSLiveIngestReader(playlistURL: origin.url("/media.m3u8"))
+        defer { reader.close() }
+
+        let startedAt = Date()
+        let joined = (1..<8).map(Self.segment).reduce(Data(), +)
+        _ = try await drain(reader, expectedBytes: joined.count + 1)
+        #expect(reader.terminalError == .playlistUnreachable(status: 502))
+        #expect(Date().timeIntervalSince(startedAt) < HLSLiveIngestReader.refreshRetryBudget / 2)
+    }
+
+    @Test("only a refusal gets the long retry budget")
+    func retryBudgets() {
+        for status in [429, 503, 509] {
+            #expect(HLSLiveIngestReader.retryBudget(forStatus: status) == HLSLiveIngestReader.refreshRetryBudget)
+        }
+        for status: Int? in [500, 502, 504, nil] {
+            #expect(HLSLiveIngestReader.retryBudget(forStatus: status) == HLSLiveIngestReader.unreachableRetryBudget)
+        }
+        #expect(HLSLiveIngestReader.unreachableRetryBudget < HLSLiveIngestReader.refreshRetryBudget)
+    }
+
     @Test("the wait between retries is a second, or what the origin asks for up to five")
     func retryWaits() {
         #expect(HLSLiveIngestReader.retryWait(retryAfter: nil) == 1)

From f958a04fd1062a35f9db7b156e3c8fbd4560814a Mon Sep 17 00:00:00 2001
From: orut34iop <h64ut2qg5lou013@gmail.com>
Date: Thu, 15 Oct 2026 23:18:29 +0800
Subject: [PATCH 070/132] test: await H264 cold-resume compatibility readiness

---
 Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift b/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
index c781e71f1..63bbd04ed 100644
--- a/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
+++ b/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
@@ -175,7 +175,7 @@ struct H264ConfigurationTrackerTests {
         #expect(engine.pendingVODVideoConfigurationMismatch == nil)
     }
 
-    @Test("A complete cold load follows the compatibility takeover and retains its paused resume", .timeLimit(.minutes(1)))
+    @Test("A cold resume reaches the compatibility path and retains its paused position", .timeLimit(.minutes(1)))
     @MainActor
     func fullColdResume() async throws {
         let file = FileManager.default.temporaryDirectory.appendingPathComponent("h264-change-\(UUID().uuidString).mp4")
@@ -188,6 +188,9 @@ struct H264ConfigurationTrackerTests {
         defer { subscription.cancel() }
         try await engine.load(url: file, startPosition: 2.0,
             options: LoadOptions(suppressDisplayCriteria: true, autoplay: false))
+        // The producer can discover the configuration change after load returns. Wait for
+        // the asynchronous takeover to settle before inspecting its route, event and position.
+        try await waitFor { engine.softwareHost != nil && engine.state == .paused }
         #expect(engine.loadedOptions.preferredDecodePath == .software)
         #expect(engine.softwareHost != nil)
         #expect(events.count == 1)

From 1d6c5a097ca8c07ac8f9dc7ca492944d49bdc384 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 17:35:46 +0200
Subject: [PATCH 071/132] fix(airplay): the refused-master fallback rejoins a
 live playlist instead of seeking it to 0

The #227 watchdog fallback swapped a live item onto the media playlist at the armed
position, which for a live session is 0: the start of the window, the seek LiveReloadPolicy
exists to avoid. It now rejoins at the player's join point, like the #780 route-change swap.
The swap's log reason also names a forward-only source by what it is, not by the
sequential-origin reason, whether or not it is live.

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26bfb76e8..edd311350 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -163,7 +163,9 @@ the public-API contract.
   address (and back onto the loopback when the receiver lets go), as it already did for a sequential
   origin. The session, its ingest and its segment cache carry on, so the source is asked for nothing
   again; the swapped item rejoins its live playlist at the player's join point, as a live reload does
-  (`AirPlayPlaylistDecision.routeChangeHop`).
+  (`AirPlayPlaylistDecision.routeChangeHop`, #780, thanks @jpsts). The fallback for a receiver that
+  refuses the master (#227) rejoins a live playlist the same way, instead of seeking the media playlist
+  to the start of its window.
 
 ## [7.36.0] - 2026-10-13
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index db34aeffa..4bb9c7926 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -6909,7 +6909,11 @@ public final class AetherEngine: ObservableObject {
         session.markServingMediaAfterFallback()
         nativeSubtitleRenditionsServed = false
         airPlayServedMasterToReceiver = false
-        host.swapItem(url: airPlayHostSwapped(mediaURL), startPosition: position)
+        // A live session rejoins its playlist at the player's join point (`LiveReloadPolicy`): a seek to the
+        // armed position would point the item at the start of the window.
+        host.swapItem(url: airPlayHostSwapped(mediaURL),
+                      startPosition: loadedOptions.isLive ? nil : position,
+                      skipInitialSeek: LiveReloadPolicy.skipInitialSeek(isLive: loadedOptions.isLive, isRejoin: true))
         host.play()
     }
 
@@ -6983,9 +6987,9 @@ public final class AetherEngine: ObservableObject {
         let position: Double? = loadedOptions.isLive ? nil : currentTime
         let served = airPlayAdjustedPlayback(url: loopback, session: session)
         nativeSubtitleRenditionsServed = served.subtitleRenditionsServed
-        let reason = loadedOptions.isLive
-            ? "a live session on a forward-only source cannot be rebuilt, #526"
-            : "the source cannot be reopened past byte 0"
+        let reason = loadedOptions.sequentialOrigin && !loadedOptions.isLive
+            ? "the source cannot be reopened past byte 0"
+            : "a forward-only custom source cannot be rebuilt, #526"
         EngineLog.emit(
             "[AirPlay] external playback \(airPlayActive ? "active (wireless)" : "ended") -> item swap to "
             + "\(served.url.absoluteString) "

From 9ccdfd07df0222b626e889311fe3804e8de5f6e5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 18:10:54 +0200
Subject: [PATCH 072/132] fix(demux): a jump back anchors the connection at the
 landing instead of detouring (#782)

A producer restart behind the reader's window was served like a parse read: serial 4 MB detour
blocks until 8 MB had gone by, each paying the origin's first byte, while the old connection kept
streaming ahead. performRestart now tells the reader after its seek that playback moved, and the
first backward read it cannot serve from memory re-anchors the streaming connection there. A
resident detour block still serves first; parse reads keep the #69 detour policy.

Measured with aetherctl against a 400 ms / 40 Mbit/s origin (MKV and MP4, two runs each): a jump
back 404 -> 340 landed in 3.2-3.3 s instead of 6.7-7.1 s, first segment 1.8 s instead of 4.2 s,
detour blocks per run 6 -> 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |   7 ++
 .../AetherEngine/Demuxer/AVIOProvider.swift   |   5 +
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  34 ++++++
 Sources/AetherEngine/Demuxer/Demuxer.swift    |   4 +
 .../AetherEngine/Video/HLSVideoEngine.swift   |   2 +
 .../Issue782RestartReanchorTests.swift        | 108 ++++++++++++++++++
 6 files changed, 160 insertions(+)
 create mode 100644 Tests/AetherEngineTests/Issue782RestartReanchorTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index edd311350..79294e442 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,13 @@ the public-API contract.
 
 ### Fixed
 
+- **A jump back opens one connection at the landing instead of three serial detour fetches** (#782,
+  thanks @tweakapps). On the native path a producer restart behind the reader's window was served the
+  way a parse read is: one 4 MB detour block per request, serially, until 8 MB had gone by, while the old
+  connection kept streaming ahead. A restart now tells the reader it repositioned playback, so the first
+  read it cannot serve from memory anchors the streaming connection there (a resident detour block still
+  serves first). Against a 400 ms, 40 Mbit/s origin a 64 s jump back landed in 3.3 s instead of 6.7 s,
+  with its first segment in 1.8 s instead of 4.2 s, the same cost as a long jump forward.
 - **A live HLS source refused for a while keeps its session.** An IPTV panel that limits an account's
   connections answers a live playlist refresh with 509 while another device holds the last slot, and
   goes on refusing a session it evicted, while a fresh session from the loaded URL is admitted at
diff --git a/Sources/AetherEngine/Demuxer/AVIOProvider.swift b/Sources/AetherEngine/Demuxer/AVIOProvider.swift
index 207c733bb..78e959da9 100644
--- a/Sources/AetherEngine/Demuxer/AVIOProvider.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOProvider.swift
@@ -77,12 +77,17 @@ protocol AVIOProvider: AnyObject {
     /// AE#585: the index pass is over, so the next read that lands outside a resident span is
     /// playback's. Default no-op.
     func endIndexPass()
+
+    /// AE#782: the demuxer was just repositioned for playback (a producer restart), so the next read
+    /// that needs the network is where playback continues, not index work that returns. Default no-op.
+    func notePlaybackRepositioned()
 }
 
 extension AVIOProvider {
     func markOpenPhaseFinished() {}
     func beginIndexPass() {}
     func endIndexPass() {}
+    func notePlaybackRepositioned() {}
     var currentSourceOffset: Int64? { nil }
     var sourceSurvivesReopen: Bool { false }
 }
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 193e93dfb..ed60a3440 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -1031,6 +1031,11 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// work rather than playback. winCond-guarded.
     private var indexPassActive = false
 
+    /// AE#782: a producer restart repositioned the demuxer. The next backward read that needs the
+    /// network re-anchors the streaming connection there at once, instead of serving the new playback
+    /// position as serial 4 MB detour blocks until `detourReanchorBytes` have gone by. winCond-guarded.
+    private var playbackRepositionPending = false
+
     /// Playback path (known size + prefetch) or live feeds. Live always uses the
     /// persistent reader; the streaming reader has no reconnect machinery.
     private var usePersistentReader: Bool {
@@ -2298,9 +2303,31 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             }
 
             let curPosition = position
+            let repositionedForPlayback = playbackRepositionPending
+            if curPosition >= winStart { playbackRepositionPending = false }
 
             if curPosition < winStart {
                 winCond.unlock()
+                // AE#782: a producer restart landed here, so this is where playback continues, not a
+                // parse read that returns. Bytes already resident still serve first; the first miss
+                // anchors the connection here. Detouring cost a jump back three serial 4 MB fetches
+                // (~2 s each against a 400 ms origin) before the 8 MB re-anchor below, while the old
+                // connection kept streaming ahead of a position nobody would read.
+                if repositionedForPlayback, detourEligible {
+                    if case .served(let n, _) = serveFromDetour(into: buf.advanced(by: totalRead),
+                                                               maxLen: requestSize - totalRead,
+                                                               at: curPosition, allowFetch: false) {
+                        diag.recordDetourServe(ms: 0, fetched: false)
+                        winCond.lock(); position = curPosition + Int64(n); winCond.broadcast(); winCond.unlock()
+                        totalRead += n
+                        continue
+                    }
+                    winCond.lock(); playbackRepositionPending = false; winCond.unlock()
+                    detourResetRun()
+                    sweepIdleDetourBlocks(force: true)
+                    timedReconnect(seek: true, at: curPosition)
+                    continue
+                }
                 // Backward random-access read (MP4 parse ping-pong, or a large backward scrub).
                 // Serve via the pooled detour cache so the anchored streaming connection is NOT
                 // torn down (the reconnect storm + origin 429, AetherEngine#69).
@@ -3141,6 +3168,13 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         winCond.unlock()
     }
 
+    /// AE#782: see `playbackRepositionPending`.
+    func notePlaybackRepositioned() {
+        winCond.lock()
+        playbackRepositionPending = true
+        winCond.unlock()
+    }
+
     /// Which cold-start span answered, so the log can name the round trip that did not happen
     /// rather than leaving its absence to be inferred.
     enum SpanServe {
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 847ccc0fd..c7a20fc65 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -922,6 +922,10 @@ public final class Demuxer: @unchecked Sendable {
     /// AE#585: ends the bracket above. Safe to call without a matching `beginIndexPass`.
     func endIndexPass() { avioProvider?.endIndexPass() }
 
+    /// AE#782: a producer restart just seeked here, so the reader anchors its connection at the next
+    /// read it cannot serve from memory instead of detouring.
+    func notePlaybackRepositioned() { avioProvider?.notePlaybackRepositioned() }
+
     /// Default 5 MB/5s budgets miss sparse PGS/DVB tracks on 10-20 GB Blu-ray rips.
     /// 50 MB/60 s ensures codec params are populated without noticeably slowing open.
     private func applyProbeBudget(_ ctx: UnsafeMutablePointer<AVFormatContext>) {
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 1712d19e9..36076a76b 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -4422,6 +4422,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             let absoluteTargetSeconds = Double(targetStartPts) * Double(videoTb.num) / Double(videoTb.den)
             activeDem.seek(to: absoluteTargetSeconds)
         }
+        // AE#782: after the seek, so a container whose seek reads (a TS bisection) spends none of it.
+        activeDem.notePlaybackRepositioned()
         // Re-arm bridge PTS rebase so the encoder timeline starts from the new demuxer cursor.
         ab?.startSegment()
         seekMs = msSince(seekStart)
diff --git a/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift b/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift
new file mode 100644
index 000000000..8bb6cf354
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift
@@ -0,0 +1,108 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// AE#782: a producer restart behind the reader's window used to be served as serial 4 MB detour
+/// blocks until 8 MB of it had gone by, which is the parse-read policy (#69), not playback's. A
+/// restart now tells the reader, and the first backward read it cannot serve from memory anchors the
+/// streaming connection at the landing.
+@Suite("AE#782 restart re-anchors at the landing")
+struct Issue782RestartReanchorTests {
+
+    private static let chunk = 256 * 1024
+
+    private func readForward(_ reader: AVIOReader, _ buf: UnsafeMutablePointer<UInt8>, bytes: Int) -> Bool {
+        var read = 0
+        while read < bytes {
+            let n = Int(reader.read(into: buf, size: Int32(Self.chunk)))
+            if n <= 0 { return false }
+            read += n
+        }
+        return true
+    }
+
+    private func matchesPattern(_ buf: UnsafeMutablePointer<UInt8>, count: Int, at offset: Int64) -> Bool {
+        (0..<count).allSatisfy { buf[$0] == ThrottledOriginServer.patternByte(at: offset + Int64($0)) }
+    }
+
+    @Test("a backward read after a playback reposition opens the connection there, not a detour block",
+          .timeLimit(.minutes(2)))
+    func repositionAnchorsAtLanding() throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000, 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()
+        reader.markOpenPhaseFinished()
+
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: Self.chunk)
+        defer { buf.deallocate() }
+        #expect(readForward(reader, buf, bytes: 13 * 1024 * 1024))
+
+        let landing: Int64 = 5 * 1024 * 1024 + 4321
+        #expect(reader.seek(offset: landing, whence: Int32(SEEK_SET)) == landing)
+        reader.notePlaybackRepositioned()
+        let n = Int(reader.read(into: buf, size: Int32(Self.chunk)))
+        #expect(n > 0)
+        #expect(matchesPattern(buf, count: n, at: landing), "the landing served the wrong bytes")
+
+        #expect(reader.detourResidentBlocksForTesting == 0, "the landing was served as a detour block")
+        #expect(server.requestedRanges.contains { $0.start == landing },
+                "no connection was anchored at the landing: \(server.requestedRanges.map(\.start))")
+    }
+
+    @Test("without the reposition the same read is still a detour, so the parse-read policy is unchanged",
+          .timeLimit(.minutes(2)))
+    func parseReadStillDetours() throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000, 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()
+        reader.markOpenPhaseFinished()
+
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: Self.chunk)
+        defer { buf.deallocate() }
+        #expect(readForward(reader, buf, bytes: 13 * 1024 * 1024))
+
+        let landing: Int64 = 5 * 1024 * 1024 + 4321
+        #expect(reader.seek(offset: landing, whence: Int32(SEEK_SET)) == landing)
+        #expect(reader.read(into: buf, size: Int32(Self.chunk)) > 0)
+        #expect(reader.detourResidentBlocksForTesting == 1)
+        #expect(!server.requestedRanges.contains { $0.start == landing })
+    }
+
+    @Test("a resident detour block still serves the landing, and the first miss past it anchors",
+          .timeLimit(.minutes(2)))
+    func residentBlockServesFirst() throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000, 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()
+        reader.markOpenPhaseFinished()
+
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: Self.chunk)
+        defer { buf.deallocate() }
+        #expect(readForward(reader, buf, bytes: 13 * 1024 * 1024))
+
+        // An earlier scrub left block 1 (4 to 8 MB) resident.
+        #expect(reader.seek(offset: 4 * 1024 * 1024, whence: Int32(SEEK_SET)) == 4 * 1024 * 1024)
+        #expect(reader.read(into: buf, size: Int32(Self.chunk)) > 0)
+        #expect(reader.detourResidentBlocksForTesting == 1)
+        let requestsBefore = server.requestedRanges.count
+
+        let landing: Int64 = 6 * 1024 * 1024
+        #expect(reader.seek(offset: landing, whence: Int32(SEEK_SET)) == landing)
+        reader.notePlaybackRepositioned()
+        #expect(reader.read(into: buf, size: Int32(Self.chunk)) > 0)
+        #expect(server.requestedRanges.count == requestsBefore, "a resident landing went to the network")
+
+        #expect(readForward(reader, buf, bytes: 3 * 1024 * 1024))
+        let blockEnd: Int64 = 8 * 1024 * 1024
+        #expect(server.requestedRanges.contains { $0.start == blockEnd },
+                "the first miss past the resident block did not anchor there: \(server.requestedRanges.map(\.start))")
+        #expect(!server.requestedRanges.contains { $0.start == blockEnd && $0.end == blockEnd + 4 * 1024 * 1024 - 1 },
+                "the first miss past the resident block was fetched as a detour block")
+    }
+}

From 1b2de7a07f471fb021d52a338e6eabe0823575be Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 18:36:35 +0200
Subject: [PATCH 073/132] fix(build): spell out the CFRRewriter initializer for
 toolchains before Swift 6.4 (#787)

CFRRewriter has private stored properties with defaults. Swift 6.4 leaves
those out of the memberwise initializer, earlier compilers make the whole
initializer private, so the .reconstruct branch and the #511 tests failed
to compile on Xcode 26 (Swift 6.3.3 reported).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                               | 2 ++
 .../AetherEngine/Video/H264MatroskaSlotPermutation.swift   | 7 +++++++
 2 files changed, 9 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 79294e442..1f2112d09 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,8 @@ the public-API contract.
 
 ### Fixed
 
+- **The package builds again on toolchains before Swift 6.4** (#787). `H264MatroskaSlotPermutation.CFRRewriter` (from #762) relied on Swift 6.4 leaving private stored properties with a default out of the memberwise initializer; earlier compilers make that initializer private, so `swift build` failed on Xcode 26. The initializer is now written out. No behavior change.
+
 - **A jump back opens one connection at the landing instead of three serial detour fetches** (#782,
   thanks @tweakapps). On the native path a producer restart behind the reader's window was served the
   way a parse read is: one 4 MB detour block per request, serially, until 8 MB had gone by, while the old
diff --git a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
index 4b1deebd5..e8252c856 100644
--- a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
+++ b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
@@ -225,6 +225,13 @@ enum H264MatroskaSlotPermutation {
         private var anchorPTS: Int64?
         private var decodeIndex: Int64 = 0
 
+        // Spelled out: before Swift 6.4 the private stored properties made the memberwise init private (#787).
+        init(step: Int64, pocStep: Int64, videoDelay: Int) {
+            self.step = step
+            self.pocStep = pocStep
+            self.videoDelay = videoDelay
+        }
+
         mutating func noteSeek() {
             anchorPTS = nil
             decodeIndex = 0

From fec79e151dca0a72fbf2ea36a6f75c7673f0ffd5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 19:19:17 +0200
Subject: [PATCH 074/132] fix(audio): the audio pick skips object audio a build
 has no decoder for (#777)

With a trait off, TrueHD Atmos or DTS:X still won the automatic pick within
its language, and then played through the channel bridge like any other
track. The pick now ranks a codec only when its decoder is linked. The
ranking tests run only with their trait, plus one that runs without.

Also: the README trait example names 7.37.0 (7.36.0 has no traits), and CI
builds the tests with the traits off, not just the library.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/ci.yml                      |  2 +-
 CHANGELOG.md                                  |  5 +--
 Package.resolved                              |  2 +-
 README.md                                     |  2 +-
 Sources/AetherEngine/AetherEngine+Probe.swift | 22 +++++++++++--
 .../AudioLanguageSelectionTests.swift         | 31 ++++++++++++++-----
 docs/api.md                                   |  2 +-
 7 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index abd5aa7fa..7078fc2d3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,7 +39,7 @@ jobs:
 
       # The object-audio decoder libraries are traits a host can turn off; keep that build compiling.
       - name: swift build (traits off)
-        run: swift build --disable-default-traits --scratch-path .build-notraits
+        run: swift build --disable-default-traits --build-tests --scratch-path .build-notraits
 
       # 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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fadf60b2d..9f75b1eda 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -47,8 +47,9 @@ the public-API contract.
   keeps today's build. A host that cannot ship one of them turns its trait off
   (`.package(url:..., traits: [])`, or the package's traits in Xcode): the library is neither linked
   nor resolved, and its codec keeps the channel bridge whatever `objectAudioRendering` asks, with the
-  reason in the session log. The manifest moves to swift-tools-version 6.1, which traits need. CI also
-  builds with both traits off. See README › Package traits.
+  reason in the session log, and the automatic audio pick no longer prefers it. The manifest moves to
+  swift-tools-version 6.1, which traits need. CI also builds the engine and its tests with both traits
+  off. See README › Package traits.
 
 ### Fixed
 
diff --git a/Package.resolved b/Package.resolved
index 7392d3c55..ec0c324b3 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "186f06d8998fc1834706d0e0cb7e529a778f970a85f160f26a6ac2fc7c8e4ee2",
+  "originHash" : "a663fca4626d82f009da9299baa967b3baccc87955a9a0c978003f268b8503c6",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
diff --git a/README.md b/README.md
index 21a1a6c53..4f811f947 100644
--- a/README.md
+++ b/README.md
@@ -665,7 +665,7 @@ The two object-audio decoder libraries are behind package traits, both on by def
 A host that cannot ship one of the libraries turns its trait off; the library is then neither linked nor resolved (it drops out of the host's `Package.resolved`), and the session log says why the codec stayed on the bridge (`built without the TrueHDObjectAudio trait`). In a package manifest, list the traits to keep (an empty list keeps none):
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.36.0", traits: [])
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.37.0", traits: [])
 ```
 
 In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: []` on the package). `swift build --disable-default-traits` builds the engine itself that way.
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index 4a2a279a5..727c97dde 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -681,7 +681,7 @@ extension AetherEngine {
     /// TrueHD that FFmpeg marked Atmos while probing (mlpdec sets the profile from the major sync), and
     /// not a commentary. `TrackInfo.isAtmos` stays the E-AC-3 JOC answer it is documented as.
     nonisolated static func isRenderableTrueHDAtmos(_ track: TrackInfo) -> Bool {
-        track.codec.lowercased() == "truehd" && !track.isCommentary && !track.isExternal
+        linksTrueHDObjectDecoder && track.codec.lowercased() == "truehd" && !track.isCommentary && !track.isExternal
             && track.profile == trueHDAtmosProfileName
     }
 
@@ -694,13 +694,31 @@ extension AetherEngine {
     /// `TrackInfo.codec` is the decoder's name, `dca` for libavcodec's DTS decoder; `dts` is the
     /// codec's own name, which a build without the decoder would report.
     nonisolated static func isRenderableDTSX(_ track: TrackInfo) -> Bool {
-        ["dca", "dts"].contains(track.codec.lowercased()) && !track.isCommentary && !track.isExternal
+        linksDTSXObjectDecoder && ["dca", "dts"].contains(track.codec.lowercased()) && !track.isCommentary && !track.isExternal
             && dtsxProfileNames.contains(track.profile ?? "")
     }
 
     nonisolated private static let dtsxProfileNames = Set([AV_PROFILE_DTS_HD_MA_X, AV_PROFILE_DTS_HD_MA_X_IMAX]
         .compactMap { VideoStreamFormat.profileName(codecID: AV_CODEC_ID_DTS, profile: $0) })
 
+    /// Whether the build links the codec's object decoder (#777: its package trait). Without it the codec
+    /// keeps the channel bridge, so the pick has no heights to prefer it for.
+    nonisolated static let linksTrueHDObjectDecoder: Bool = {
+        #if TrueHDObjectAudio
+        return true
+        #else
+        return false
+        #endif
+    }()
+
+    nonisolated static let linksDTSXObjectDecoder: Bool = {
+        #if DTSXObjectAudio
+        return true
+        #else
+        return false
+        #endif
+    }()
+
     /// The tracks object rendering keeps the heights of.
     nonisolated static func isRenderableObjectAudio(_ track: TrackInfo) -> Bool {
         isRenderableTrueHDAtmos(track) || isRenderableDTSX(track)
diff --git a/Tests/AetherEngineTests/AudioLanguageSelectionTests.swift b/Tests/AetherEngineTests/AudioLanguageSelectionTests.swift
index 7c3cc3dd7..34ca4abe3 100644
--- a/Tests/AetherEngineTests/AudioLanguageSelectionTests.swift
+++ b/Tests/AetherEngineTests/AudioLanguageSelectionTests.swift
@@ -94,7 +94,8 @@ struct AudioLanguageSelectionTests {
                              : profile.flatMap { VideoStreamFormat.profileName(codecID: codecID, profile: $0) })
     }
 
-    @Test("with rendering on, DTS:X wins within its language like TrueHD Atmos; plain DTS-HD MA does not")
+    @Test("with rendering on, DTS:X wins within its language like TrueHD Atmos; plain DTS-HD MA does not",
+          .enabled(if: AetherEngine.linksDTSXObjectDecoder))
     func dtsxWinsWithinLanguage() {
         // `dca` is what the probe reports for DTS: TrackInfo.codec is the decoder's name.
         let tracks = [audio(1, "eng", codec: "ac3"), audio(2, "eng", codec: "dca", profile: AV_PROFILE_DTS_HD_MA_X),
@@ -115,7 +116,8 @@ struct AudioLanguageSelectionTests {
                                               prefersObjectAudio: true) == 1)
     }
 
-    @Test("with rendering on, TrueHD Atmos beats DTS and plain TrueHD of the preferred language")
+    @Test("with rendering on, TrueHD Atmos beats DTS and plain TrueHD of the preferred language",
+          .enabled(if: AetherEngine.linksTrueHDObjectDecoder))
     func trueHDAtmosWinsWithinLanguage() {
         let tracks = [audio(1, "eng", codec: "dts"), audio(2, "eng", codec: "truehd", atmos: true),
                       audio(3, "ger", codec: "truehd", atmos: true)]
@@ -128,7 +130,8 @@ struct AudioLanguageSelectionTests {
                                               prefersObjectAudio: true) == 2)
     }
 
-    @Test("it never crosses a language, and an override still wins")
+    @Test("it never crosses a language, and an override still wins",
+          .enabled(if: AetherEngine.linksTrueHDObjectDecoder))
     func neverAcrossLanguage() {
         let tracks = [audio(1, "ger", codec: "dts"), audio(2, "eng", codec: "truehd", atmos: true)]
         #expect(AetherEngine.selectAudioIndex(tracks: tracks, override: nil, preferredLanguages: ["de"],
@@ -137,7 +140,8 @@ struct AudioLanguageSelectionTests {
                                               prefersObjectAudio: true) == 1)
     }
 
-    @Test("without a language preference it replaces the default track with TrueHD Atmos in that track's language")
+    @Test("without a language preference it replaces the default track with TrueHD Atmos in that track's language",
+          .enabled(if: AetherEngine.linksTrueHDObjectDecoder))
     func replacesDefaultInItsLanguage() {
         let tracks = [audio(1, "eng", codec: "dts"), audio(2, "ger", codec: "truehd", atmos: true),
                       audio(3, "eng", codec: "truehd", atmos: true)]
@@ -151,14 +155,16 @@ struct AudioLanguageSelectionTests {
                 "no language to compare, so the default stays")
     }
 
-    @Test("a commentary in TrueHD Atmos does not displace the film")
+    @Test("a commentary in TrueHD Atmos does not displace the film",
+          .enabled(if: AetherEngine.linksTrueHDObjectDecoder))
     func commentaryStaysBehind() {
         let tracks = [audio(1, "eng", codec: "dts"), audio(2, "eng", codec: "truehd", atmos: true, commentary: true)]
         #expect(AetherEngine.selectAudioIndex(tracks: tracks, override: nil, preferredLanguages: ["en"],
                                               prefersObjectAudio: true) == 1)
     }
 
-    @Test("a preference nothing matches still lets the default's language take its TrueHD Atmos track")
+    @Test("a preference nothing matches still lets the default's language take its TrueHD Atmos track",
+          .enabled(if: AetherEngine.linksTrueHDObjectDecoder))
     func unmatchedPreferenceFallsBackToDefaultLanguage() {
         // Sodalite always sends the device locale; on a German box a film with only English audio
         // matches nothing and plays its default track.
@@ -167,7 +173,8 @@ struct AudioLanguageSelectionTests {
                                               prefersObjectAudio: true, defaultIndex: 1) == 2)
     }
 
-    @Test("the fallback keeps the dub: a region both tags state and disagree on is another track")
+    @Test("the fallback keeps the dub: a region both tags state and disagree on is another track",
+          .enabled(if: AetherEngine.linksTrueHDObjectDecoder))
     func fallbackKeepsTheDub() {
         let tracks = [audio(1, "es-ES", codec: "dts"), audio(2, "es-419", codec: "truehd", atmos: true)]
         #expect(AetherEngine.selectAudioIndex(tracks: tracks, override: nil, preferredLanguages: [],
@@ -176,4 +183,14 @@ struct AudioLanguageSelectionTests {
         #expect(AetherEngine.selectAudioIndex(tracks: same, override: nil, preferredLanguages: [],
                                               prefersObjectAudio: true, defaultIndex: 1) == 2)
     }
+
+    @Test("built without an object decoder's trait, the pick does not prefer that codec",
+          .disabled(if: AetherEngine.linksTrueHDObjectDecoder && AetherEngine.linksDTSXObjectDecoder))
+    func withoutTraitNothingIsPreferred() {
+        let tracks = [audio(1, "eng", codec: "ac3"), audio(2, "eng", codec: "truehd", atmos: true),
+                      audio(3, "eng", codec: "dca", profile: AV_PROFILE_DTS_HD_MA_X)]
+        let expected = AetherEngine.linksTrueHDObjectDecoder ? 2 : AetherEngine.linksDTSXObjectDecoder ? 3 : 1
+        #expect(AetherEngine.selectAudioIndex(tracks: tracks, override: nil, preferredLanguages: ["en"],
+                                              prefersObjectAudio: true) == Int32(expected))
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 36c740670..7b3bd3147 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1187,7 +1187,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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. |
-| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731). `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Each codec needs its package trait (`TrueHDObjectAudio`, `DTSXObjectAudio`, both on by default); with one turned off, that codec keeps the channel bridge. |
+| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731). `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Each codec needs its package trait (`TrueHDObjectAudio`, `DTSXObjectAudio`, both on by default); with one turned off, that codec keeps the channel bridge and the automatic audio pick no longer prefers it. |
 | `confirmAtmos` | false | Background per-track JOC confirmation, republishing `audioTracks` as tracks confirm. Never on the start path; skipped for live and forward-only readers. |
 | `preferredAudioLanguages` | empty | First-frame audio pick from the engine's single probe. Ordered BCP-47 / ISO 639 tags; region and script are normalized and rank within one preference (#590). An explicit `audioSourceStreamIndex` still wins. |
 | `preferredSubtitleLanguages` | empty | Post-load subtitle activation on the host-overlay path. Ranks language specificity (an explicitly opposite script is rejected, not demoted) before the descriptor axis. Pure convenience: no reload and no pre-probe, unlike the audio equivalent. |

From b4ca3cd4894631074c2b55f54afa9651db78d37a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 19:39:37 +0200
Subject: [PATCH 075/132] fix(hls): declare a BANDWIDTH the densest segment
 fits under (#783)

The master declared twice the container's average bitrate. A VBR ending in
an HEVC Matroska file with Opus bridged to FLAC ran past it and AVPlayer
logged -12318 "Segment exceeds specified bandwidth for variant".

When the plan's boundaries are container index entries, the byte positions
the index records at them give each segment's source bitrate. The highest
of them, with 20% headroom plus the bridged track's ceiling (FLAC at its
PCM rate, E-AC-3 and APAC at their configured rate), now raises the
declaration, up to four times the average and never past 160 Mbit/s, so an
implausible measurement cannot leave a variant AVPlayer refuses to pick.
Twice the average stays the floor.

Measured with aetherctl serve on a 60 s HEVC file averaging 20.1 Mbit/s:
densest served segment 55.6 Mbit/s, declaration 40.2 -> 68.2 Mbit/s.

Re #783

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  12 ++
 .../Audio/AudioTranscodingBridge.swift        |  19 +++
 .../Audio/Spatial/SpatialAudioBridge.swift    |   2 +
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  10 +-
 .../HLSVideoEngine+SegmentPlanning.swift      |  21 +++
 .../AetherEngine/Video/HLSVideoEngine.swift   |  19 ++-
 .../Video/VideoSegmentProvider.swift          |  37 ++++-
 .../Issue783PeakBandwidthTests.swift          | 138 ++++++++++++++++++
 8 files changed, 252 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue783PeakBandwidthTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f75b1eda..0b4715a38 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,6 +53,18 @@ the public-API contract.
 
 ### Fixed
 
+- **A remuxed title declares a `BANDWIDTH` its densest segment fits under** (#783, thanks @hp561). The
+  master declared twice the container's average, and a VBR ending in an HEVC Matroska file with three
+  Opus tracks bridged to FLAC ran past it: AVPlayer logged -12318 "Segment exceeds specified bandwidth
+  for variant". When the plan's boundaries are container index entries, the byte positions the index
+  records at them now give each segment's source bitrate, and the highest of them (with 20% headroom,
+  plus the bridged track's ceiling: FLAC at its PCM rate, E-AC-3 and APAC at their configured rate)
+  raises the declaration, up to four times the average and never past 160 Mbit/s, so an implausible
+  measurement cannot leave a variant AVPlayer refuses to pick. Twice the average stays the floor, so no
+  declaration goes down. On a 60 s HEVC file averaging 20.1 Mbit/s whose densest served segment carried
+  55.6 Mbit/s, the declaration went from 40.2 to 68.2 Mbit/s. The I-frame variant keeps reusing the
+  main figure, which bounds any keyframe of it.
+
 - **The package builds again on toolchains before Swift 6.4** (#787). `H264MatroskaSlotPermutation.CFRRewriter` (from #762) relied on Swift 6.4 leaving private stored properties with a default out of the memberwise initializer; earlier compilers make that initializer private, so `swift build` failed on Xcode 26. The initializer is now written out. No behavior change.
 
 - **A jump back opens one connection at the landing instead of three serial detour fetches** (#782,
diff --git a/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift b/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift
index a9207b3ff..30d9dcf75 100644
--- a/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift
@@ -23,6 +23,10 @@ protocol AudioTranscodingBridge: AnyObject, Sendable {
     /// Nil reads the count off `encoderCodecpar`.
     var servedChannelCount: Int? { get }
 
+    /// AE#783: the most bits per second the delivered track can carry, which the master's
+    /// `BANDWIDTH` has to cover.
+    var peakOutputBitRate: Int64 { get }
+
     /// Decode, transcode and return 0+ packets in `encoderTimeBase`. The caller owns them and frees
     /// them with `trackedPacketFree` after muxing.
     func feed(packet: UnsafePointer<AVPacket>) throws -> [UnsafeMutablePointer<AVPacket>]
@@ -46,5 +50,20 @@ protocol AudioTranscodingBridge: AnyObject, Sendable {
 extension AudioBridge: AudioTranscodingBridge {
     var soundSampleEntryOverride: Data? { nil }
     var servedChannelCount: Int? { nil }
+    var peakOutputBitRate: Int64 {
+        guard let cp = encoderCodecpar else { return 0 }
+        return Self.peakBitRate(bitRate: cp.pointee.bit_rate,
+                                channels: cp.pointee.ch_layout.nb_channels,
+                                sampleRate: cp.pointee.sample_rate,
+                                bitsPerRawSample: cp.pointee.bits_per_raw_sample)
+    }
+
+    /// A constant-rate encoder (E-AC-3) states its rate. FLAC is variable and never exceeds the PCM
+    /// it encodes by more than its frame headers, so its ceiling is the PCM rate.
+    static func peakBitRate(bitRate: Int64, channels: Int32, sampleRate: Int32, bitsPerRawSample: Int32) -> Int64 {
+        if bitRate > 0 { return bitRate }
+        let bits = bitsPerRawSample > 0 ? Int64(bitsPerRawSample) : 32
+        return Int64(max(0, channels)) * Int64(max(0, sampleRate)) * bits
+    }
     func settle() -> [UnsafeMutablePointer<AVPacket>] { [] }
 }
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
index 1abccbf8a..5801aedab 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
@@ -41,6 +41,7 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
     /// HLS `CODECS` value for the track.
     let hlsCodecs: String
     var servedChannelCount: Int? { layout.channelCount }
+    let peakOutputBitRate: Int64
 
     private let srcTimeBase: AVRational
     private let decoder: ObjectAudioDecoding
@@ -114,6 +115,7 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         levelMeter = BedLevelMeter(layout: layout, sampleRate: Self.sampleRate)
         limiter = PeakLimiter(sampleRate: Self.sampleRate)
         let rate = bitRate ?? layout.channelCount * Self.bitRatePerChannel
+        peakOutputBitRate = Int64(rate)
         let encoder = try APACEncoder(layout: layout, sampleRate: Double(Self.sampleRate), bitRate: rate)
         let pipeline = APACEncodePipeline(
             encoder: encoder, channels: layout.channelCount, bufferFrames: Self.encodeChunkFrames * 4)
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index c7a20fc65..17c5321a6 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1831,6 +1831,12 @@ public final class Demuxer: @unchecked Sendable {
     /// during avformat_find_stream_info. Empty = no usable index, fall back to
     /// uniform-stride plan. AVINDEX_KEYFRAME checked defensively.
     func indexedKeyframes(streamIndex: Int32) -> [Int64] {
+        indexedKeyframeEntries(streamIndex: streamIndex).map(\.pts)
+    }
+
+    /// `indexedKeyframes` with each entry's byte position in the source (AE#783), -1 where the index
+    /// has none. Matroska stores the position of the Cluster that holds the keyframe.
+    func indexedKeyframeEntries(streamIndex: Int32) -> [(pts: Int64, pos: Int64)] {
         accessLock.lock()
         defer { accessLock.unlock() }
         let compositionOffset = compositionRepair?.decodeTimestampOffset
@@ -1843,7 +1849,7 @@ public final class Demuxer: @unchecked Sendable {
         let count = avformat_index_get_entries_count(stream)
         guard count > 0 else { return [] }
         let tb = stream.pointee.time_base
-        var result: [Int64] = []
+        var result: [(pts: Int64, pos: Int64)] = []
         for i in 0..<count {
             // 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
@@ -1854,7 +1860,7 @@ public final class Demuxer: @unchecked Sendable {
                   let folded = normalizedTimestamp(entry.pointee.timestamp, pos: entry.pointee.pos, timeBase: tb),
                   let placed = Self.offsetIndexTimestamp(folded, by: compositionOffset)
             else { continue }
-            result.append(placed)
+            result.append((pts: placed, pos: entry.pointee.pos))
         }
         return result
     }
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
index 34d0d0327..8ea28e406 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
@@ -384,6 +384,27 @@ extension HLSVideoEngine {
         return plan
     }
 
+    /// AE#783: the highest source bitrate of any planned segment, from the byte positions the container
+    /// index records at the segment boundaries. Those bytes hold every interleaved track, including the
+    /// ones the session drops, so the figure errs high. Nil unless the positions rise across every
+    /// measurable boundary: two IRAPs in one Matroska Cluster share a position, a disc folds several
+    /// files onto one axis, and either one makes a byte span mean nothing. The final segment has no
+    /// indexed end and is not measured.
+    ///
+    /// Pure for offline testing.
+    static func peakSegmentBitrate(plan: [Segment], keyframeBytePositions: [Int64: Int64]) -> Int64? {
+        guard plan.count > 1 else { return nil }
+        var peak: Double = 0
+        for segment in plan.dropLast() {
+            guard let start = keyframeBytePositions[segment.startPts], start >= 0,
+                  let end = keyframeBytePositions[segment.endPts], end > start,
+                  segment.durationSeconds > 0
+            else { return nil }
+            peak = max(peak, Double(end - start) * 8 / segment.durationSeconds)
+        }
+        return peak > 0 && peak < Double(Int64.max) ? Int64(peak) : nil
+    }
+
     /// Segments shorter than this are folded into a neighbour by `collapseShortSegments`. A keyframe
     /// cluster (several IRAPs within a few frames) otherwise makes `buildKeyframeSegmentPlan` emit
     /// sub-frame segments whose narrow [start,end) window can miss every demuxed keyframe, so the producer
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 36076a76b..9476511d7 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -634,6 +634,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// Source bitrate in bps for HLS BANDWIDTH/AVERAGE-BANDWIDTH. 0 when libavformat can't
     /// compute it; callers fall back to an over-declared estimate to avoid CoreMediaErrorDomain -12318.
     private var sourceBitrate: Int64 = 0
+    /// AE#783: the highest per-segment source bitrate the keyframe index measures, nil when it cannot.
+    private var sourcePeakBitrate: Int64?
 
     /// Fires on each gate open (initial + restart) so AetherEngine keeps its shift in step
     /// for subtitle cue lookup.
@@ -1296,6 +1298,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         sourceStartSeconds = formatStart == Int64.min ? 0 : max(0, Double(formatStart) / Double(AV_TIME_BASE))
         let durationSeconds = dem.duration
         var plan: [Segment]
+        var keyframeBytePositions: [Int64: Int64] = [:]
         if isLiveSession {
             sourceBitrate = dem.bitRate
             self.firstKeyframePts = 0
@@ -1353,7 +1356,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             // 3. Build the segment plan. Uses the same cut algorithm as libavformat's hls muxer
             //    (first IDR at-or-after `(segIdx+1) * hls_time`); falls back to uniform stride
             //    if the index has < 2 entries (restart machinery handles any plan/muxer drift).
-            let keyframes = dem.indexedKeyframes(streamIndex: videoIndex)
+            let keyframeEntries = dem.indexedKeyframeEntries(streamIndex: videoIndex)
+            let keyframes = keyframeEntries.map(\.pts)
             let indexTrustworthy = Self.keyframeIndexIsTrustworthy(
                 keyframes: keyframes,
                 videoTimeBase: videoTimeBase,
@@ -1392,6 +1396,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
                     sourceDurationSeconds: durationSeconds
                 )
                 planBoundariesClaimRandomAccess = true
+                keyframeBytePositions = Dictionary(keyframeEntries.map { ($0.pts, $0.pos) },
+                                                   uniquingKeysWith: { first, _ in first })
                 // AE#561: these boundaries ARE this container's index entries, so they carry its
                 // stamping. Read from the demuxer that produced them, never from the URL or the
                 // host's metadata: on a remux session the delivered container is the one indexed.
@@ -1688,6 +1694,15 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // share these boundaries, so the merge fixes both at once).
         plan = Self.collapseShortSegments(plan, minDurationSeconds: Self.minSegmentDurationSeconds)
         self.segmentPlan = plan
+        if !keyframeBytePositions.isEmpty {
+            sourcePeakBitrate = Self.peakSegmentBitrate(plan: plan, keyframeBytePositions: keyframeBytePositions)
+            EngineLog.emit(
+                "[HLSVideoEngine] peak segment bitrate: "
+                + (sourcePeakBitrate.map { "\($0) bps (source average \(sourceBitrate) bps)" }
+                   ?? "not measurable from the index byte positions"),
+                category: .session
+            )
+        }
 
         // #93 residual: anchor the FIRST producer at the session's start position instead of seg0.
         // A resume start otherwise produces seg0 (torn down and discarded seconds later when
@@ -2073,6 +2088,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             frameRate: frameRate,
             hdcpLevel: hdcpLevel,
             sourceBitrate: sourceBitrate,
+            sourcePeakBitrate: sourcePeakBitrate,
+            bridgedAudioPeakBitrate: savedAudioConfig?.bridge?.peakOutputBitRate ?? 0,
             audioLanguage: servedAudioLanguage,
             audioChannelCount: servedAudioChannels,
             audioIsAtmosStreamCopy: servedAudioIsAtmosStreamCopy,
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index a51eabead..6fd3cd888 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -782,6 +782,8 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     private let frameRate: Double?
     private let hdcpLevel: String?
     private let sourceBitrate: Int64
+    private let sourcePeakBitrate: Int64?
+    private let bridgedAudioPeakBitrate: Int64
 
     /// AE#458: ISO 639-2/T of the ONE audio track muxed into the variant, for the master's
     /// EXT-X-MEDIA:TYPE=AUDIO tag. Nil for a source whose audio carries no resolvable language.
@@ -1015,6 +1017,8 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         frameRate: Double?,
         hdcpLevel: String?,
         sourceBitrate: Int64,
+        sourcePeakBitrate: Int64? = nil,
+        bridgedAudioPeakBitrate: Int64 = 0,
         audioLanguage: String? = nil,
         audioChannelCount: Int? = nil,
         audioIsAtmosStreamCopy: Bool = false,
@@ -1076,6 +1080,8 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         self.frameRate = frameRate
         self.hdcpLevel = hdcpLevel
         self.sourceBitrate = sourceBitrate
+        self.sourcePeakBitrate = sourcePeakBitrate
+        self.bridgedAudioPeakBitrate = bridgedAudioPeakBitrate
         self.audioLanguage = audioLanguage
         self.audioChannelCount = audioChannelCount
         self.audioIsAtmosStreamCopy = audioIsAtmosStreamCopy
@@ -2990,10 +2996,35 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         sourceBitrate > 0 ? Int(sourceBitrate) : 25_000_000
     }
 
-    /// 2x average as peak estimate (4K HDR action bursts to ~2x); 5 Mbps floor for corrupt-bitrate sources.
     var masterBandwidth: Int? {
-        let avg = masterAverageBandwidth ?? 25_000_000
-        return max(avg * 2, 5_000_000)
+        Self.declaredPeakBandwidth(averageBandwidth: masterAverageBandwidth ?? 25_000_000,
+                                   sourcePeakBitrate: sourcePeakBitrate,
+                                   bridgedAudioPeakBitrate: bridgedAudioPeakBitrate)
+    }
+
+    /// Headroom over the measured peak for the fMP4 boxes and for Cue positions that sit on a Cluster
+    /// rather than on the keyframe itself.
+    static let measuredPeakHeadroom = 1.2
+
+    /// The most a measurement may raise the declaration to: four times the average, 40 Mbps at least,
+    /// and never past 160 Mbps. A declaration AVPlayer cannot meet is worse than an exceeded one: at
+    /// 2.25 Gbps it never picked the variant at all (the disc title in 7.35.x).
+    static func measuredPeakCeiling(averageBandwidth: Int) -> Int {
+        min(max(averageBandwidth * 4, 40_000_000), 160_000_000)
+    }
+
+    /// The variant's `BANDWIDTH`, a peak AVPlayer checks every segment against (-12318). Twice the
+    /// average, 5 Mbps at least, stays the floor (4K HDR action bursts to ~2x). AE#783: where the
+    /// index measures each segment, the highest of them plus the bridged track's ceiling raises it,
+    /// up to `measuredPeakCeiling`; a VBR ending ran past twice the average, and a FLAC track can
+    /// weigh several times the Opus it replaced.
+    static func declaredPeakBandwidth(averageBandwidth: Int, sourcePeakBitrate: Int64?,
+                                      bridgedAudioPeakBitrate: Int64) -> Int {
+        let estimate = max(averageBandwidth * 2, 5_000_000)
+        guard let peak = sourcePeakBitrate, peak > 0 else { return estimate }
+        let measured = Double(peak) * measuredPeakHeadroom + Double(max(0, bridgedAudioPeakBitrate))
+        let ceiling = measuredPeakCeiling(averageBandwidth: averageBandwidth)
+        return max(estimate, Int(min(measured, Double(ceiling))))
     }
     var masterFrameRate: Double? { frameRate }
     var masterHDCPLevel: String? { hdcpLevel }
diff --git a/Tests/AetherEngineTests/Issue783PeakBandwidthTests.swift b/Tests/AetherEngineTests/Issue783PeakBandwidthTests.swift
new file mode 100644
index 000000000..423abb4f5
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue783PeakBandwidthTests.swift
@@ -0,0 +1,138 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavformat
+import AetherLibavutil
+@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)
+}
+
+/// AE#783: a Matroska remux (Opus bridged to FLAC) declared `BANDWIDTH` as twice the container's
+/// average, and AVPlayer refused a segment of the VBR ending with -12318 "Segment exceeds specified
+/// bandwidth for variant". The keyframe index knows where every planned segment starts in the file,
+/// so the peak it measures, plus the bridged track's ceiling, now raises the declaration.
+@Suite("AE#783 peak-safe master BANDWIDTH")
+struct Issue783PeakBandwidthTests {
+
+    private static func plan(_ bounds: [(pts: Int64, seconds: Double)]) -> [HLSVideoEngine.Segment] {
+        zip(bounds, bounds.dropFirst()).map { a, b in
+            HLSVideoEngine.Segment(startPts: a.pts, endPts: b.pts, startSeconds: a.seconds,
+                                   durationSeconds: b.seconds - a.seconds)
+        }
+    }
+
+    @Test("the peak is the densest measured segment, the final one unmeasured")
+    func peakIsDensestSegment() {
+        let plan = Self.plan([(0, 0), (4000, 4), (8000, 8), (12000, 12)])
+        // 4 MB over 4 s, then 12 MB over 4 s; the last segment has no indexed end.
+        let positions: [Int64: Int64] = [0: 1_000, 4000: 4_001_000, 8000: 16_001_000]
+        #expect(HLSVideoEngine.peakSegmentBitrate(plan: plan, keyframeBytePositions: positions) == 24_000_000)
+    }
+
+    @Test("a boundary without a position, or one that does not rise, measures nothing")
+    func unusablePositionsMeasureNothing() {
+        let plan = Self.plan([(0, 0), (4000, 4), (8000, 8), (12000, 12)])
+        #expect(HLSVideoEngine.peakSegmentBitrate(
+            plan: plan, keyframeBytePositions: [0: 0, 8000: 9_000_000]) == nil)
+        // Two IRAPs in one Matroska Cluster share its position.
+        #expect(HLSVideoEngine.peakSegmentBitrate(
+            plan: plan, keyframeBytePositions: [0: 0, 4000: 0, 8000: 9_000_000]) == nil)
+        #expect(HLSVideoEngine.peakSegmentBitrate(
+            plan: plan, keyframeBytePositions: [0: -1, 4000: 10, 8000: 20]) == nil)
+        #expect(HLSVideoEngine.peakSegmentBitrate(plan: Self.plan([(0, 0), (4000, 4)]),
+                                                  keyframeBytePositions: [0: 0, 4000: 100]) == nil)
+    }
+
+    @Test("the reporter's session: a 3.46 s ending segment above twice the 9.15 Mb/s average")
+    func reporterSessionDeclaresTheMeasuredPeak() {
+        let average = 9_148_953
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: average, sourcePeakBitrate: nil, bridgedAudioPeakBitrate: 0) == 18_297_906)
+        // A 21 Mb/s segment, and a stereo FLAC bridge from Opus (S16, 48 kHz).
+        let flac = AudioBridge.peakBitRate(bitRate: 0, channels: 2, sampleRate: 48_000, bitsPerRawSample: 16)
+        #expect(flac == 1_536_000)
+        let declared = VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: average, sourcePeakBitrate: 21_000_000, bridgedAudioPeakBitrate: flac)
+        #expect(declared == 21_000_000 * 12 / 10 + 1_536_000)
+    }
+
+    @Test("a measured peak never lowers the declaration below twice the average")
+    func measuredPeakNeverLowers() {
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: 10_000_000, sourcePeakBitrate: 12_000_000, bridgedAudioPeakBitrate: 0) == 20_000_000)
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: 1_000_000, sourcePeakBitrate: nil, bridgedAudioPeakBitrate: 9_000_000) == 5_000_000)
+    }
+
+    @Test("a measured peak past the ceiling is held at it, so AVPlayer can still pick the variant")
+    func implausiblePeakIsClamped() {
+        // An index position far down the file reads as a 2 Gb/s segment.
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: 9_000_000, sourcePeakBitrate: 2_000_000_000, bridgedAudioPeakBitrate: 0) == 40_000_000)
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: 30_000_000, sourcePeakBitrate: 500_000_000, bridgedAudioPeakBitrate: 0) == 120_000_000)
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: 60_000_000, sourcePeakBitrate: 500_000_000, bridgedAudioPeakBitrate: 0) == 160_000_000)
+        // Twice an average above the ceiling's cap is still the floor.
+        #expect(VideoSegmentProvider.declaredPeakBandwidth(
+            averageBandwidth: 90_000_000, sourcePeakBitrate: 500_000_000, bridgedAudioPeakBitrate: 0) == 180_000_000)
+    }
+
+    @Test("an E-AC-3 bridge states its rate, a lossless FLAC one its PCM ceiling")
+    func bridgeCeilings() {
+        #expect(AudioBridge.peakBitRate(bitRate: 768_000, channels: 6, sampleRate: 48_000, bitsPerRawSample: 0)
+                == 768_000)
+        #expect(AudioBridge.peakBitRate(bitRate: 0, channels: 8, sampleRate: 48_000, bitsPerRawSample: 24)
+                == 9_216_000)
+        #expect(AudioBridge.peakBitRate(bitRate: 0, channels: 2, sampleRate: 48_000, bitsPerRawSample: 0)
+                == 3_072_000)
+    }
+
+    /// The index-measured peak has to cover what each planned segment really carries. Read every
+    /// packet of the file, sum the bytes per segment, and compare.
+    @Test("on a real Matroska file the index peak covers every segment's packets",
+          .enabled(if: fixtureExists("restart-witness-subs.mkv")))
+    func indexPeakCoversPacketBytes() throws {
+        let dem = Demuxer()
+        try dem.open(url: fixtureURL("restart-witness-subs.mkv"))
+        defer { dem.close() }
+        let video = dem.videoStreamIndex
+        _ = dem.seekBounded(to: dem.duration * 0.5, timeout: 2)
+        let entries = dem.indexedKeyframeEntries(streamIndex: video)
+        try #require(entries.count >= 3)
+        guard let stream = dem.stream(at: video) else {
+            Issue.record("no video stream"); return
+        }
+        let tb = stream.pointee.time_base
+        let plan = HLSVideoEngine.buildKeyframeSegmentPlan(
+            keyframes: entries.map(\.pts), videoTimeBase: tb, sourceDurationSeconds: dem.duration)
+        let positions = Dictionary(entries.map { ($0.pts, $0.pos) }, uniquingKeysWith: { a, _ in a })
+        let peak = try #require(HLSVideoEngine.peakSegmentBitrate(plan: plan, keyframeBytePositions: positions))
+
+        _ = dem.seekBounded(to: 0, timeout: 2)
+        var bytesPerSegment = [Int64](repeating: 0, count: plan.count)
+        let videoTb = Double(tb.num) / Double(tb.den)
+        while let pkt = try dem.readPacket() {
+            var owned: UnsafeMutablePointer<AVPacket>? = pkt
+            defer { av_packet_free(&owned) }
+            guard let s = dem.stream(at: pkt.pointee.stream_index) else { continue }
+            let ts = pkt.pointee.dts != Int64.min ? pkt.pointee.dts : pkt.pointee.pts
+            guard ts != Int64.min else { continue }
+            let seconds = Double(ts) * Double(s.pointee.time_base.num) / Double(s.pointee.time_base.den)
+            let firstStart = Double(plan[0].startPts) * videoTb
+            guard let idx = plan.lastIndex(where: { $0.startSeconds <= seconds - firstStart }) else { continue }
+            bytesPerSegment[idx] += Int64(pkt.pointee.size)
+        }
+        for (idx, segment) in plan.enumerated().dropLast() {
+            let rate = Double(bytesPerSegment[idx]) * 8 / segment.durationSeconds
+            #expect(Double(peak) >= rate, "segment \(idx): \(Int(rate)) bps above the index peak \(peak)")
+        }
+    }
+}

From c7ac32a77970b7644b8b3521601f65ad29c5ae01 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 20:06:22 +0200
Subject: [PATCH 076/132] fix(software): residency drops history the memory
 store's kernel reclaimed (#759)

tvOS keeps software VOD packets in purgeable memory, and the store only
learned of a reclaimed history chunk when a restore walked into it. The
ranges #759 publishes therefore kept claiming that history until a seek
proved it gone. The sampler now evicts emptied chunks (a purgeable-state
query per history chunk, under a try-lock so it never waits on the store)
before it copies the floors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 +++-
 .../Native/SoftwarePacketMemoryFIFO.swift     | 22 +++++++++++++++++++
 .../Native/SoftwarePacketReadAhead.swift      | 14 +++++++++++-
 .../Native/SoftwarePacketStore.swift          |  6 +++++
 .../SoftwarePacketMemoryFIFOTests.swift       | 14 ++++++++++++
 .../SoftwareResidentRangesTests.swift         | 21 ++++++++++++++++--
 6 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c48029821..1c9416f7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -62,7 +62,9 @@ the public-API contract.
   committed packets remain seekable after a source read error, which is still reported after drain;
   storage failures remain unusable. Failed resume/seek positioning can no longer publish a false
   successful landing. Bounded cold probes avoid speculative detour fetches, and foreground software
-  positioning has a finite 30 s budget for slow multi-probe remote keyframe searches.
+  positioning has a finite 30 s budget for slow multi-probe remote keyframe searches. On tvOS's
+  in-memory packet store, history the system reclaims under memory pressure leaves the published
+  ranges at the next sample instead of only when a seek walks into it.
 
 - **A remuxed title declares a `BANDWIDTH` its densest segment fits under** (#783, thanks @hp561). The
   master declared twice the container's average, and a VBR ending in an HEVC Matroska file with three
diff --git a/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
index 0a6304fe8..18343aa47 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketMemoryFIFO.swift
@@ -62,6 +62,17 @@ final class SoftwarePacketMemoryFIFO: @unchecked Sendable {
             return kr == KERN_SUCCESS && state != VM_PURGABLE_EMPTY
         }
 
+        private static let getState: vm_purgable_t = 1
+
+        /// A query only: the chunk stays volatile either way.
+        var isEmptied: Bool {
+            guard isVolatile else { return false }
+            var state: Int32 = 0
+            let kr = vm_purgable_control(mach_task_self_, vm_address_t(UInt(bitPattern: base)),
+                                         Self.getState, &state)
+            return kr == KERN_SUCCESS && state == VM_PURGABLE_EMPTY
+        }
+
         /// Empties the chunk now, as the kernel may once it is volatile. Tests only.
         func purgeForTesting() {
             var state: Int32 = VM_PURGABLE_EMPTY
@@ -264,6 +275,17 @@ final class SoftwarePacketMemoryFIFO: @unchecked Sendable {
         }
     }
 
+    /// Evicts history the kernel has emptied, up to the newest emptied chunk. Without it the store
+    /// learns of a purge only when a restore walks into it, and published residency (#759) would
+    /// keep claiming history that is already gone. Returns whether anything was evicted.
+    func evictPurgedHistory() -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let newest = chunks.last(where: { $0.id < headID && $0.isEmptied })?.id else { return false }
+        evictPurgedLocked(through: newest)
+        return true
+    }
+
     /// Empties every volatile history chunk now, as the kernel may under memory pressure. Tests only.
     func purgeHistoryForTesting() {
         lock.lock()
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 986590dad..4c17996bb 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -149,8 +149,20 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     }
 
     /// Called only by a background sampler. Copy bounded metadata under the short state lock;
-    /// timestamp conversion/intersection and keyframe selection happen after releasing it. No I/O.
+    /// timestamp conversion/intersection and keyframe selection happen after releasing it. No I/O
+    /// beyond a purgeable-state query per history chunk on the memory store.
     var residentRanges: [ClosedRange<Double>] {
+        // A purged history chunk is gone before any restore notices. Never wait for the store:
+        // a busy one is checked on the next sample.
+        if operations.try() {
+            if fifo.evictPurgedHistory() {
+                let state = fifo.snapshot
+                condition.lock()
+                if !closed { copyDiskStateLocked(state) }
+                condition.unlock()
+            }
+            operations.unlock()
+        }
         condition.lock()
         // Fixed numeric state only, emitted on edges by this background sampler. No URLs,
         // error descriptions or packet content. Bits: closed/reposition/reset/failure,
diff --git a/Sources/AetherEngine/Native/SoftwarePacketStore.swift b/Sources/AetherEngine/Native/SoftwarePacketStore.swift
index d12224e68..4e6e683b9 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketStore.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketStore.swift
@@ -14,6 +14,12 @@ protocol SoftwarePacketStore: AnyObject, Sendable {
     func trimConsumed(toByteBudget budget: Int) throws
     func reset() throws
     func close() throws
+    /// Drops history the system reclaimed behind the store's back. Returns whether anything went.
+    func evictPurgedHistory() -> Bool
+}
+
+extension SoftwarePacketStore {
+    func evictPurgedHistory() -> Bool { false }
 }
 
 extension SoftwarePacketDiskFIFO: SoftwarePacketStore {}
diff --git a/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift b/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift
index d2cf2b47e..ec963a07a 100644
--- a/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePacketMemoryFIFOTests.swift
@@ -92,6 +92,20 @@ struct SoftwarePacketMemoryFIFOTests {
         #expect(try fifo.pop() == record(100))
     }
 
+    @Test("emptied history is evicted on a check, before any restore walks into it (#759)")
+    func evictPurgedHistory() throws {
+        let (fifo, cursors) = try filled(100)
+        for _ in 0..<90 { _ = try fifo.pop() }
+        #expect(!fifo.evictPurgedHistory())
+        let before = try #require(fifo.snapshot.oldestRetainedChunkID)
+        fifo.purgeHistoryForTesting()
+        #expect(fifo.evictPurgedHistory())
+        #expect(try #require(fifo.snapshot.oldestRetainedChunkID) > before)
+        #expect(!fifo.evictPurgedHistory())
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) { try fifo.restore(to: cursors[10]) }
+        for i in 90..<100 { #expect(try fifo.pop() == record(i)) }
+    }
+
     @Test("a still walk into emptied history is refused and releases the store")
     func purgedHistoryWalk() async throws {
         let (fifo, cursors) = try filled(100)
diff --git a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
index 85cafd566..81c5a3a8c 100644
--- a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
+++ b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
@@ -23,9 +23,10 @@ struct SoftwareResidentRangesTests {
     }
     private func source(_ packets: [SoftwareStoredPacket], audio: Bool = false,
                         reorder: Int? = nil, budget: Int = 1_000_000,
-                        chunkBytes: Int = 1024) throws -> SoftwarePacketReadAhead {
+                        chunkBytes: Int = 1024,
+                        store: (any SoftwarePacketStore)? = nil) throws -> SoftwarePacketReadAhead {
         let input = Input(packets)
-        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: chunkBytes, retainConsumed: true)
+        let fifo = try store ?? SoftwarePacketDiskFIFO(chunkTargetBytes: chunkBytes, retainConsumed: true)
         let source = SoftwarePacketReadAhead(video: .init(index: 0, numerator: 1, denominator: 1000),
             audio: audio ? .init(index: 1, numerator: 1, denominator: 1000) : nil,
             byteBudget: budget, forwardSeconds: 3600, initialSourceClock: 0,
@@ -114,6 +115,22 @@ struct SoftwareResidentRangesTests {
         #expect(source.residentRanges.isEmpty)
     }
 
+    @Test("History the kernel emptied in the memory store leaves the published spans (#759)")
+    func purgedMemoryHistory() async throws {
+        let packets = (0..<400).map { packet(Int64($0) * 40) }
+        let store = SoftwarePacketMemoryFIFO(chunkTargetBytes: 1, historyCapBytes: .max)
+        let source = try source(packets, store: store)
+        defer { source.close() }
+        try await consume(source, expecting: packets, fails: false)
+        #expect(source.residentRanges == [0...16])
+        store.purgeHistoryForTesting()
+        let spans = source.residentRanges
+        #expect((spans.first?.lowerBound ?? 0) > 0)
+        #expect(spans.last?.upperBound == 16)
+        let miss = source.beginSeek(to: 0.1)
+        #expect(try !source.prepareSeek(miss, to: 0.1))
+    }
+
     @Test("Evicted reordered timestamps and metadata pressure only shorten coverage")
     func residencyWatermarks() {
         var value = SoftwarePacketResidency(maximumChunks: 2)

From 72c2ec78910e2d194afad8e64d6c528673ee02ab Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 20:53:08 +0200
Subject: [PATCH 077/132] fix(video): judge an H.264 VOD set change by its
 decoder signature (#785)

The tracker compared every referenced SPS and PPS byte for byte against the
avcC, so a set that changed only where VideoToolbox takes the in-band value
moved a working native session onto the software path at load. Measured on
macOS with x264 halves joined by a stream copy, 1280x720 throughout:

  VUI only (MP4 and MKV), level only, PPS only: main played 739-743 frames
  natively across the seam, #785 took the software path at 0.00 s.
  Baseline -> High profile, 1280x720 -> 856x480: main froze at the seam
  (453 frames), the takeover is right.

H264SPS.decoderSignature packs profile_idc and every field from
chroma_format_idc through the cropping window; constraint flags, level,
the set ID and the VUI are left out. An IDR whose active SPS signature is
not among the baseline's takes the takeover, a PPS no longer counts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  5 ++-
 .../Video/H264ConfigurationTracker.swift      | 14 ++++----
 Sources/AetherEngine/Video/H264SPS.swift      | 22 ++++++++++--
 .../H264ConfigurationTrackerTests.swift       | 34 +++++++++++++++++++
 docs/architecture.md                          |  3 +-
 docs/formats.md                               |  6 +++-
 6 files changed, 73 insertions(+), 11 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dbd083afe..fc6acb116 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -92,7 +92,10 @@ the public-API contract.
   references SPS/PPS that differ from the AVC initialization, the producer stops before writing that
   sample into the stale native segment. Automatic routing uses the existing software-path takeover,
   preserving a pending seek or cold-resume position and the session transport. Repeated or unused
-  parameter sets keep the native route; an explicitly selected route or disabled escalation is honored.
+  parameter sets keep the native route, and so does a change confined to the PPS, the VUI or the
+  level, which the native decoder takes in band (a TS recording remuxed to MKV or MP4 carries those);
+  only the fields a decoder session is built from, profile through cropping, take the software path.
+  An explicitly selected route or disabled escalation is honored.
 
 - **A live HLS source refused for a while keeps its session.** An IPTV panel that limits an account's
   connections answers a live playlist refresh with 509 while another device holds the last slot, and
diff --git a/Sources/AetherEngine/Video/H264ConfigurationTracker.swift b/Sources/AetherEngine/Video/H264ConfigurationTracker.swift
index f8eb4069f..2ca2f4e98 100644
--- a/Sources/AetherEngine/Video/H264ConfigurationTracker.swift
+++ b/Sources/AetherEngine/Video/H264ConfigurationTracker.swift
@@ -1,7 +1,9 @@
 import Foundation
 
 /// Pump-local evidence that an AVC access unit no longer matches the sample description.
-/// Merely repeating SPS/PPS, or announcing an unused set, is not a decoder failure.
+/// Merely repeating SPS/PPS, or announcing an unused set, is not a decoder failure, and neither is a
+/// set that differs only where the native decoder takes the in-band value: a new PPS, VUI or level
+/// (#785 follow-up, see `H264SPS.decoderSignature`).
 /// No frames are decoded and only parameter sets / short slice headers are copied.
 struct H264ConfigurationTracker {
     struct Mismatch: Sendable, Equatable {
@@ -12,8 +14,7 @@ struct H264ConfigurationTracker {
         var summary: String { "H264 active SPS/PPS differs from native init: \(width)x\(height), SPS=\(spsID), PPS=\(ppsID)" }
     }
 
-    private let baselineSPS: [Int: [UInt8]]
-    private let baselinePPS: [Int: [UInt8]]
+    private let baselineSignatures: Set<[UInt8]>
     private var sps: [Int: [UInt8]]
     private var pps: [Int: [UInt8]]
 
@@ -41,7 +42,7 @@ struct H264ConfigurationTracker {
             pictures[ids.pps] = nal
         }
         guard !sequences.isEmpty, !pictures.isEmpty else { return nil }
-        baselineSPS = sequences; baselinePPS = pictures
+        baselineSignatures = Set(sequences.values.compactMap(H264SPS.decoderSignature(fromNAL:)))
         sps = sequences; pps = pictures
     }
 
@@ -77,8 +78,9 @@ struct H264ConfigurationTracker {
                 let prefix = Array(bytes[range.lowerBound..<min(range.upperBound, range.lowerBound + 33)])
                 guard let id = Self.slicePPS(prefix), let picture = pictures[id],
                       let ids = Self.pictureIDs(picture), let sequence = sequences[ids.sps],
-                      let size = Self.dimensions(sequence) else { continue }
-                if baselinePPS[id] != picture || baselineSPS[ids.sps] != sequence {
+                      let size = Self.dimensions(sequence),
+                      let signature = H264SPS.decoderSignature(fromNAL: sequence) else { continue }
+                if !baselineSignatures.contains(signature) {
                     mismatch = Mismatch(width: size.width, height: size.height, spsID: ids.sps, ppsID: id)
                 }
             default: break
diff --git a/Sources/AetherEngine/Video/H264SPS.swift b/Sources/AetherEngine/Video/H264SPS.swift
index 8020b12f9..f2ad2d481 100644
--- a/Sources/AetherEngine/Video/H264SPS.swift
+++ b/Sources/AetherEngine/Video/H264SPS.swift
@@ -14,6 +14,14 @@ enum H264SPS {
         parse(fromNAL: nal)?.frameMbsOnly
     }
 
+    /// The part of an SPS a decoder session is built from: profile_idc and every field from
+    /// chroma_format_idc through the cropping window, packed bit for bit. Constraint flags, level_idc,
+    /// the set's ID and the VUI are left out, since a change confined to them plays on the native
+    /// route with the original sample description (#785 follow-up, measured on macOS).
+    static func decoderSignature(fromNAL nal: [UInt8]) -> [UInt8]? {
+        parse(fromNAL: nal)?.signature
+    }
+
     /// First SPS NAL (incl. 1-byte header) from codecpar extradata, accepting both layouts: Annex-B
     /// (MPEG-TS, start-code delimited) and avcC (MP4/MKV, configurationVersion byte 0x01 then
     /// length-prefixed parameter sets). Returns nil when neither layout yields an SPS.
@@ -31,7 +39,7 @@ enum H264SPS {
         return extradata.withUnsafeBufferPointer { extractSPSandPPS(fromAnnexB: $0)?.sps }
     }
 
-    private static func parse(fromNAL nal: [UInt8]) -> (width: Int, height: Int, frameMbsOnly: Bool)? {
+    private static func parse(fromNAL nal: [UInt8]) -> (width: Int, height: Int, frameMbsOnly: Bool, signature: [UInt8])? {
         guard nal.count > 1, (nal[0] & 0x1f) == 7 else { return nil }
         let rbsp = unescape(Array(nal[1...]))  // strip NAL header + emulation-prevention (00 00 03 -> 00 00)
         var r = BitReader(rbsp)
@@ -40,6 +48,7 @@ enum H264SPS {
         _ = r.u(8)                  // constraint flags + reserved
         _ = r.u(8)                  // level_idc
         guard r.ue() != nil else { return nil } // seq_parameter_set_id
+        let coreStart = r.position
 
         var chromaFormatIdc = 1
         let highProfiles: Set<Int> = [100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134, 135]
@@ -102,7 +111,15 @@ enum H264SPS {
         }
 
         guard width > 0, height > 0 else { return nil }
-        return (width, height, frameMbsOnly)
+        var core = BitReader(rbsp), signature = [UInt8(profileIdc)], packed = 0, count = 0
+        _ = core.u(coreStart)
+        for _ in coreStart..<r.position {
+            guard let b = core.u(1) else { return nil }
+            packed = (packed << 1) | b; count += 1
+            if count == 8 { signature.append(UInt8(packed)); packed = 0; count = 0 }
+        }
+        if count > 0 { signature.append(UInt8(packed << (8 - count))) }
+        return (width, height, frameMbsOnly, signature)
     }
 
     /// Scan Annex-B for the first SPS (NAL type 7) and PPS (NAL type 8), returned with their 1-byte NAL header.
@@ -237,6 +254,7 @@ enum H264SPS {
         private let bytes: [UInt8]
         private var bit = 0
         init(_ b: [UInt8]) { bytes = b }
+        var position: Int { bit }
 
         mutating func u(_ n: Int) -> Int? {
             var v = 0
diff --git a/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift b/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
index 63bbd04ed..fb3bf611f 100644
--- a/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
+++ b/Tests/AetherEngineTests/H264ConfigurationTrackerTests.swift
@@ -78,6 +78,40 @@ struct H264ConfigurationTrackerTests {
         #expect(H264ConfigurationTracker(avcC: Array(avcc().dropLast())) == nil)
         #expect(H264ConfigurationTracker(avcC: [1,2,3]) == nil)
     }
+    // #785 follow-up: in-band set pairs taken from x264 encodes joined with a stream copy. On macOS the
+    // native route played the VUI, level and PPS changes through (739 to 743 frames over 30 s) and
+    // froze at the profile change, as at a resolution change.
+    private static let baselineSPS = hex("6742c01fda014016ec05a810100a000003000200000300601e306540")
+    private static let baselinePPS = hex("68ce0fc8")
+    private func avcc(sps: [UInt8], pps: [UInt8]) -> [UInt8] {
+        [1, sps[1], sps[2], sps[3], 255, 225, 0, UInt8(sps.count)] + sps + [1, 0, UInt8(pps.count)] + pps
+    }
+    @Test("A set that differs only in VUI, level or PPS keeps the native route", arguments: [
+        ("6742c01fda014016ec05a810102a000003000200000300601e306540", "68ce0fc8"),
+        ("6742c029da014016ec0440000003004000000c03c60ca8", "68ce0fc8"),
+        ("6742c01fda014016ec05a810100a000003000200000300601e306540", "68ce0fcb"),
+    ])
+    func decoderCompatibleChange(sps: String, pps: String) throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc(sps: Self.baselineSPS, pps: Self.baselinePPS)))
+        #expect(observe(&tracker, [Self.hex(sps), Self.hex(pps), idr]) == nil)
+        #expect(observe(&tracker, [idr]) == nil)
+    }
+    @Test("A profile change at the same size still takes the compatible decoder")
+    func profileChange() throws {
+        var tracker = try #require(H264ConfigurationTracker(avcC: avcc(sps: Self.baselineSPS, pps: Self.baselinePPS)))
+        let high = Self.hex("6764001facb402802dd80b50202014000003000400000300c03c60ca80")
+        let result = observe(&tracker, [high, Self.hex("68ee0fcb"), idr])
+        #expect(result?.width == 1280)
+        #expect(result?.height == 720)
+    }
+    @Test("The decoder signature ignores VUI and level but not size or profile")
+    func decoderSignature() throws {
+        let base = try #require(H264SPS.decoderSignature(fromNAL: Self.baselineSPS))
+        #expect(H264SPS.decoderSignature(fromNAL: Self.hex("6742c01fda014016ec05a810102a000003000200000300601e306540")) == base)
+        #expect(H264SPS.decoderSignature(fromNAL: Self.hex("6742c029da014016ec0440000003004000000c03c60ca8")) == base)
+        #expect(H264SPS.decoderSignature(fromNAL: Self.hex("6764001facb402802dd80b50202014000003000400000300c03c60ca80")) != base)
+        #expect(H264SPS.decoderSignature(fromNAL: sps) != H264SPS.decoderSignature(fromNAL: changed))
+    }
     @Test("The new media verdict respects explicit route, host and once-only constraints")
     func escalationPolicy() {
         let domain = SoftwarePathEscalation.videoConfigurationErrorDomain
diff --git a/docs/architecture.md b/docs/architecture.md
index b2505cd0e..8c901eca4 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -24,7 +24,8 @@ Why HLS-fMP4 for the native path instead of feeding `AVPlayer` the source URL di
 
 **AVC VOD configuration changes are judged before native muxing.** `H264ConfigurationTracker`
 starts from the producer’s effective `avcC`, follows length-prefixed SPS/PPS in NAL order, and checks
-the pair referenced by an IDR against that baseline. A mismatch exits the pump with a typed reason
+the SPS referenced by an IDR against that baseline by its decoder signature (profile through
+cropping; PPS, VUI and level are taken in band by the native decoder and do not count). A mismatch exits the pump with a typed reason
 before the changed sample is written; the session retains the verdict for a pump that finishes before
 its owning load is installed. Producer epoch and load generation checks reject superseded events.
 The existing `SoftwarePathEscalation` takeover owns recovery under its normal route and host opt-in
diff --git a/docs/formats.md b/docs/formats.md
index adf183477..f238f0106 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -30,7 +30,11 @@ A length-prefixed H.264 file can retain its original `avcC` while later samples
 SPS/PPS, including a resolution change under the same parameter-set IDs. Native HLS can then play
 audio without displaying video, including after seeking or reopening at that position. The producer
 checks the parameter sets actually referenced by an IDR before writing it into the native segment;
-repeated sets and announcements that no IDR uses do not change the route.
+repeated sets and announcements that no IDR uses do not change the route. Only the part of the SPS a
+decoder session is built from counts (`H264SPS.decoderSignature`: profile, chroma format and bit
+depth, frame numbering and picture order, reference frames, size and cropping). A new PPS, VUI or
+level keeps the native route, since the native decoder takes those in band: on macOS such a change
+played through natively in every arm, while a profile or resolution change froze the picture.
 
 In automatic mode, with `escalatesToSoftwarePath` enabled, a confirmed mismatch uses the existing
 native-to-software takeover. The software decoder accepts the changing frame dimensions, while the

From 7fb6142d5a6219fa31d5388ce95f276f884ffca4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 21:08:15 +0200
Subject: [PATCH 078/132] fix(audio): give TrueHD a second of access units
 before calling its decoder dead (#786)

TrueHD and MLP decode only from a major sync. After a start, seek or track
switch mid-stream the decoder skips up to ~100 40-frame access units
("Stream parameters not seen") before its first frame, while the channel
bridge's decoder arm fired after 64 silent packets (~53 ms of TrueHD). The
bridge then raised AE#396 / AE#641 and the session went to .error with
.audioBridgeProducedNoOutput while it played, ignoring later seeks.

The decoder arm's packet bound now follows the source codec: 1200 for TrueHD
and MLP, the bound SpatialAudioBridge already used for the same wait (now
shared from AudioBridge), 64 for everything else.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  9 +++
 Sources/AetherEngine/Audio/AudioBridge.swift  | 32 +++++++-
 .../Audio/Spatial/SpatialAudioBridge.swift    |  7 +-
 .../Issue396SilentAudioBridgeTests.swift      | 74 +++++++++++++++++++
 4 files changed, 116 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fc6acb116..5c7091595 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -53,6 +53,15 @@ the public-API contract.
 
 ### Fixed
 
+- **A TrueHD track started or switched to mid-stream is no longer reported as a dead decoder** (#786,
+  thanks @ijuniorfu). TrueHD and MLP decode only from a major sync, so after a start, seek or track
+  switch past the opening the decoder skips up to about a hundred 40-frame access units before its
+  first frame. The channel bridge judged its decoder dead after 64 silent packets, about 53 ms of
+  TrueHD, so `AudioBridge` raised AE#396 / AE#641 and the session went to `.error`
+  (`.audioBridgeProducedNoOutput`) while it played, ignoring seeks after it. For these two codecs the
+  bound is now 1200 packets (one second of source), the bound `SpatialAudioBridge` already used for
+  the same wait; every other source keeps 64.
+
 - **Software VOD exposes retained cache ranges to host timelines.** `residentRanges` now covers
   compressed video packets together with the selected audio stream, including retained history,
   gaps and disk eviction. Cached seeks keep the same spans; cold seeks and teardown clear them.
diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index af615e152..dda591d2a 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -264,6 +264,7 @@ final class AudioBridge: @unchecked Sendable {
 
         // 1. Source decoder
         let srcCodecID = srcCodecpar.pointee.codec_id
+        decoderPacketThreshold = Self.decoderSilencePacketThreshold(for: srcCodecID)
 
         // PCM intermediate format follows the ENCODER (resolved below, after the channel count): EAC3 needs
         // FLTP; FLAC takes S16 (lossy src) or S32@24 (lossless src).
@@ -593,6 +594,26 @@ final class AudioBridge: @unchecked Sendable {
     /// back, so there is no sample count to bound anything with and packets are all there is.
     private static let silentFeedPacketThreshold = 64
 
+    /// AE#786: a packet is not the same length of source on every codec, and the decoder arm has to
+    /// outlast the longest a healthy decoder stays quiet. TrueHD and MLP decode only from a major
+    /// sync, and a TrueHD packet is one 40-frame access unit (1/1200 s), so after a start or seek
+    /// mid-stream the decoder skips up to ~100 of them ("Stream parameters not seen") before its
+    /// first frame. At 64 that wait was reported as a dead decoder and the session went to `.error`
+    /// while it played. `SpatialAudioBridge` met the same wait first and shares this bound: a second
+    /// of source.
+    static let trueHDSilentFeedPacketThreshold = 1200
+
+    static func decoderSilencePacketThreshold(for codecID: AVCodecID) -> Int {
+        switch codecID {
+        case AV_CODEC_ID_TRUEHD, AV_CODEC_ID_MLP:
+            return trueHDSilentFeedPacketThreshold
+        default:
+            return silentFeedPacketThreshold
+        }
+    }
+
+    private let decoderPacketThreshold: Int
+
     /// AE#474: the ENCODER arm's unit. `drainFIFOIntoEncoder(requireFull: true)` cannot encode below
     /// `frame_size`, so nothing can be emitted until that many samples have been enqueued, and the
     /// figure is not a constant of the bridge: 1536 on E-AC-3, 4608 on FLAC. A source packet is not
@@ -947,13 +968,17 @@ final class AudioBridge: @unchecked Sendable {
     ///
     /// Pure and static so the boundary can be pinned against the frame sizes this bridge really
     /// opens instead of against whichever one the fixtures happen to reach.
-    static func silenceIsStructural(stats: FeedStats, encoderFrameSize: Int32) -> Bool {
+    static func silenceIsStructural(
+        stats: FeedStats,
+        encoderFrameSize: Int32,
+        decoderPacketThreshold: Int = silentFeedPacketThreshold
+    ) -> Bool {
         guard stats.isSilent else { return false }
         let frame = Int64(encoderFrameSize > 0 ? encoderFrameSize : assumedEncoderFrameSize)
         // The encoder arm: enough PCM to build several frames went in and none came back.
         if stats.samplesEnqueued >= frame * silentFeedEncoderFrameMultiple { return true }
         // The decoder arm: the FIFO has stood still for longer than any source explains.
-        return stats.packetsFedSinceLastEnqueue >= silentFeedPacketThreshold
+        return stats.packetsFedSinceLastEnqueue >= decoderPacketThreshold
     }
 
     /// AE#396: say it once, the moment the silence is structural. Without this the only downstream
@@ -962,7 +987,8 @@ final class AudioBridge: @unchecked Sendable {
     /// the #165 cascade line.
     private func noteSilentFeedIfNeeded(encoderFrameSize: Int32) {
         guard !silentFeedReported,
-              Self.silenceIsStructural(stats: stats, encoderFrameSize: encoderFrameSize)
+              Self.silenceIsStructural(stats: stats, encoderFrameSize: encoderFrameSize,
+                                       decoderPacketThreshold: decoderPacketThreshold)
         else { return }
         silentFeedReported = true
         let encoder = avcodec_get_name(outputCodecID).map { String(cString: $0) } ?? "the encoder"
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
index 5801aedab..42d05f2ba 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
@@ -93,15 +93,16 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
     private static let avNoPTS: Int64 = -0x7FFFFFFFFFFFFFFF - 1
 
     /// Packets the object decoder may take without a block before it counts as producing nothing.
-    /// Not the channel bridge's 64: a TrueHD packet is one 40-frame access unit, and after a start or
-    /// resume mid-stream the decoder waits for the next major sync before its first block. Measured
+    /// Not the channel bridge's default 64 (it takes this bound for TrueHD too, AE#786): a TrueHD
+    /// packet is one 40-frame access unit, and after a start or resume mid-stream the decoder waits
+    /// for the next major sync before its first block. Measured
     /// on Dolby's Unfold demo, that wait was up to 102 access units; at 64 every resume past the
     /// opening seconds was reported as a dead decoder and the session went to `.error` while it
     /// played, ignoring every seek after it. 1200 is a second of TrueHD, still a fraction of a second
     /// of the producer's time. A DTS-HD packet is a 512-frame frame, so for DTS:X it is 12.8 s; the
     /// track was confirmed as DTS:X before the bridge was built, and its decoder outputs from the
     /// third packet after every reset.
-    static let silentFeedPacketThreshold = 1200
+    static let silentFeedPacketThreshold = AudioBridge.trueHDSilentFeedPacketThreshold
 
     init(
         srcTimeBase: AVRational,
diff --git a/Tests/AetherEngineTests/Issue396SilentAudioBridgeTests.swift b/Tests/AetherEngineTests/Issue396SilentAudioBridgeTests.swift
index 246098904..059096c13 100644
--- a/Tests/AetherEngineTests/Issue396SilentAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/Issue396SilentAudioBridgeTests.swift
@@ -378,4 +378,78 @@ struct Issue396SilentAudioBridgeTests {
         #expect(!AudioBridge.silenceIsStructural(stats: stillFilling, encoderFrameSize: 4608),
                 "a FIFO that is still accepting samples is a bridge that has not been asked yet")
     }
+
+    // MARK: - AE#786: a decoder waiting for its sync is not a dead one
+
+    private func makeTrueHDCodecpar() -> UnsafeMutablePointer<AVCodecParameters> {
+        let par = avcodec_parameters_alloc()!
+        par.pointee.codec_type = AVMEDIA_TYPE_AUDIO
+        par.pointee.codec_id = AV_CODEC_ID_TRUEHD
+        par.pointee.sample_rate = 48_000
+        av_channel_layout_default(&par.pointee.ch_layout, 8)
+        return par
+    }
+
+    private final class DecoderVerdict: @unchecked Sendable {
+        private let lock = NSLock()
+        private var stats: AudioBridge.FeedStats?
+        var reported: AudioBridge.FeedStats? {
+            lock.lock(); defer { lock.unlock() }
+            return stats
+        }
+        func set(_ s: AudioBridge.FeedStats) { lock.lock(); stats = s; lock.unlock() }
+    }
+
+    @Test("TrueHD and MLP are judged on a second of access units, every other source on 64 packets")
+    func decoderPacketThresholdFollowsTheSource() {
+        #expect(AudioBridge.trueHDSilentFeedPacketThreshold == 1200)
+        #expect(AudioBridge.decoderSilencePacketThreshold(for: AV_CODEC_ID_TRUEHD)
+                == AudioBridge.trueHDSilentFeedPacketThreshold)
+        #expect(AudioBridge.decoderSilencePacketThreshold(for: AV_CODEC_ID_MLP)
+                == AudioBridge.trueHDSilentFeedPacketThreshold)
+        #expect(AudioBridge.decoderSilencePacketThreshold(for: AV_CODEC_ID_MP3) == 64)
+        #expect(AudioBridge.decoderSilencePacketThreshold(for: AV_CODEC_ID_DTS) == 64)
+        #expect(AudioBridge.decoderSilencePacketThreshold(for: AV_CODEC_ID_EAC3) == 64)
+
+        var waiting = AudioBridge.FeedStats()
+        waiting.packetsFed = 102
+        waiting.packetsFedSinceLastEnqueue = 102
+        #expect(!AudioBridge.silenceIsStructural(stats: waiting, encoderFrameSize: 1536,
+                                                 decoderPacketThreshold: 1200),
+                "102 access units is the longest major-sync wait measured, 85 ms of TrueHD")
+        #expect(AudioBridge.silenceIsStructural(stats: waiting, encoderFrameSize: 1536),
+                "the same count is past the default bound, which is why TrueHD needs its own")
+    }
+
+    @Test("a TrueHD bridge started between major syncs is not reported dead before a second of source")
+    func trueHDWaitingForMajorSyncIsNotADeadDecoder() throws {
+        let codecpar = makeTrueHDCodecpar()
+        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 verdict = DecoderVerdict()
+        bridge.onDecoderProducedNothing = { verdict.set($0) }
+
+        var outputs: [UnsafeMutablePointer<AVPacket>] = []
+        defer { freeAll(&outputs) }
+        var early = makeUndecodablePackets(count: 200)
+        defer { freeAll(&early) }
+        for p in early { outputs.append(contentsOf: (try? bridge.feed(packet: p)) ?? []) }
+
+        #expect(bridge.feedStats.decodedNothing)
+        #expect(verdict.reported == nil,
+                "AE#786: 200 access units is 167 ms, longer than any wait for a major sync and far short of a dead decoder")
+
+        var late = makeUndecodablePackets(count: AudioBridge.trueHDSilentFeedPacketThreshold)
+        defer { freeAll(&late) }
+        for p in late { outputs.append(contentsOf: (try? bridge.feed(packet: p)) ?? []) }
+
+        #expect(verdict.reported?.decodedNothing == true,
+                "a TrueHD decoder that never answers is still caught, a second of source later")
+    }
 }

From 43af24e5b03ca5e7b8e5fbbb0f65982a04a1cde8 Mon Sep 17 00:00:00 2001
From: dlev <49005290+dlev02@users.noreply.github.com>
Date: Thu, 15 Oct 2026 14:26:28 -0500
Subject: [PATCH 079/132] feat(engine): replace a live session's request
 headers without a rebuild (#792)

updateRequestHeaders(_:) hands the session a new header set and the next
request each of its source readers makes carries it. One RequestHeaderStore
per load feeds the playback demuxer, the producer's reopens and revives, and
the I-frame and embedded-subtitle side readers, which used to freeze a copy of
LoadOptions.httpHeaders at their open. A reconnect already backing off over a
refused credential sends the new set on its next attempt.

The set is also installed into loadedOptions so rebuilds replay it. Routes
whose requests are fixed at load (remoteBypass, AVPlayer audio, custom
IOReader, remote disc image) report .installedForNextRebuild.
---
 CHANGELOG.md                                  |  11 ++
 .../AetherEngine/AetherEngine+Loading.swift   |  11 +-
 .../AetherEngine+RequestHeaders.swift         |  90 ++++++++++++
 .../AetherEngine/AetherEngine+Subtitles.swift |  10 +-
 Sources/AetherEngine/AetherEngine.swift       |  22 ++-
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  13 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  13 +-
 .../Demuxer/RequestHeaderStore.swift          |  31 +++++
 .../Video/HLSVideoEngine+LiveReopen.swift     |   3 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   |  18 ++-
 .../LiveRequestHeaderTests.swift              | 130 ++++++++++++++++++
 docs/api.md                                   |  33 +++++
 12 files changed, 368 insertions(+), 17 deletions(-)
 create mode 100644 Sources/AetherEngine/AetherEngine+RequestHeaders.swift
 create mode 100644 Sources/AetherEngine/Demuxer/RequestHeaderStore.swift
 create mode 100644 Tests/AetherEngineTests/LiveRequestHeaderTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dbd083afe..30b9113aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,17 @@ the public-API contract.
 
 ### Added
 
+- **A live session's request headers can be replaced without a rebuild (#792).**
+  `updateRequestHeaders(_:)` hands the session a new header set, and the next request each of its
+  source readers makes carries it: one store per load now feeds the playback demuxer, the producer's
+  reopens and revives, and the I-frame and embedded-subtitle side readers, which used to freeze a copy
+  at their open. A media server whose bearer tokens expire under a long title no longer costs a
+  `reloadAtCurrentPosition(applying:)` teardown per rotation, and a reconnect already backing off over
+  a lapsed token heals on its next attempt once the host renews. The returned
+  `RequestHeaderUpdateOutcome` says `.installedForNextRebuild` where the requests are not the
+  engine's to change (`.remoteBypass`, an AVPlayer-hosted audio item, a custom `IOReader`, a remote
+  disc image). See [Rotating a credential without a rebuild](docs/api.md#rotating-a-credential-without-a-rebuild).
+
 - **A DVD-Video ripped as a `VIDEO_TS` folder plays over HTTP, as a `BDMV` folder does.** A
   `DiscDirectoryReader` (or `HTTPDiscDirectoryReader`) whose listing holds `VIDEO_TS/` files is now read
   as DVD-Video: the title sets, VMGI filtering, durations, chapters and languages come from the same code
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index dde59e682..c462960fa 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -885,6 +885,9 @@ extension AetherEngine {
             declaredDurationSeconds: loadedOptions.declaredDurationSeconds,
             forwardBufferSegments: loadedOptions.forwardBufferSegments
         )
+        // AE#792: the session's live header store, shared with the playback demuxer it was handed, so
+        // `updateRequestHeaders(_:)` reaches that reader and every reopen the producer makes. Set before start().
+        session.requestHeaders = sessionRequestHeaders
         // AE#464: every producer this session builds reads it off the session. Set before start().
         session.audioDelaySeconds = loadedOptions.audioDelaySeconds
         session.servesSegmentsProgressively = loadedOptions.progressiveSegmentDelivery
@@ -2117,13 +2120,13 @@ extension AetherEngine {
         let forwardBufferSegments = loadedOptions.forwardBufferSegments
         let dvrRetention = loadedOptions.softwareDVRRetention
         try await BlockingWork.detached(priority: .userInitiated) {
-            [host, preopenedDemuxer, url, sourceHTTPHeaders, isLive, dvrWindowSeconds, probesize, maxAnalyzeDuration, sequentialOrigin, heldSourceConnection, declaredDuration, networkPhaseSink] in
+            [host, preopenedDemuxer, url, sourceHTTPHeaders, requestHeaders = sessionRequestHeaders, isLive, dvrWindowSeconds, probesize, maxAnalyzeDuration, sequentialOrigin, heldSourceConnection, declaredDuration, networkPhaseSink] in
             let dem: Demuxer
             if let pre = preopenedDemuxer {
                 dem = pre
             } else {
                 dem = Demuxer()
-                try dem.open(url: url, extraHeaders: sourceHTTPHeaders, profile: .playback.withProbeBudget(probesize: probesize, maxAnalyzeDuration: maxAnalyzeDuration).withSequentialOrigin(sequentialOrigin, declaredDuration: declaredDuration).withHeldSourceConnection(heldSourceConnection).withSourceOpenPolicy(sourceOpenPolicy), isLive: isLive)
+                try dem.open(url: url, extraHeaders: sourceHTTPHeaders, profile: .playback.withProbeBudget(probesize: probesize, maxAnalyzeDuration: maxAnalyzeDuration).withSequentialOrigin(sequentialOrigin, declaredDuration: declaredDuration).withHeldSourceConnection(heldSourceConnection).withSourceOpenPolicy(sourceOpenPolicy).withRequestHeaders(requestHeaders), isLive: isLive)
             }
             dem.onNetworkPhaseChanged = networkPhaseSink
             try await host.load(
@@ -2196,13 +2199,13 @@ extension AetherEngine {
         }
         if loadGeneration == generation { recordStartupCheckpoint(.sessionConstructed) }   // #361
         try await BlockingWork.detached(priority: .userInitiated) {
-            [host, preopenedDemuxer, url, sourceHTTPHeaders, probesize, maxAnalyzeDuration, sequentialOrigin, heldSourceConnection, declaredDuration, networkPhaseSink] in
+            [host, preopenedDemuxer, url, sourceHTTPHeaders, requestHeaders = sessionRequestHeaders, probesize, maxAnalyzeDuration, sequentialOrigin, heldSourceConnection, declaredDuration, networkPhaseSink] in
             let dem: Demuxer
             if let pre = preopenedDemuxer {
                 dem = pre
             } else {
                 dem = Demuxer()
-                try dem.open(url: url, extraHeaders: sourceHTTPHeaders, profile: .playback.withProbeBudget(probesize: probesize, maxAnalyzeDuration: maxAnalyzeDuration).withSequentialOrigin(sequentialOrigin, declaredDuration: declaredDuration).withHeldSourceConnection(heldSourceConnection).withSourceOpenPolicy(sourceOpenPolicy))
+                try dem.open(url: url, extraHeaders: sourceHTTPHeaders, profile: .playback.withProbeBudget(probesize: probesize, maxAnalyzeDuration: maxAnalyzeDuration).withSequentialOrigin(sequentialOrigin, declaredDuration: declaredDuration).withHeldSourceConnection(heldSourceConnection).withSourceOpenPolicy(sourceOpenPolicy).withRequestHeaders(requestHeaders))
             }
             dem.onNetworkPhaseChanged = networkPhaseSink
             try await host.load(
diff --git a/Sources/AetherEngine/AetherEngine+RequestHeaders.swift b/Sources/AetherEngine/AetherEngine+RequestHeaders.swift
new file mode 100644
index 000000000..75548e420
--- /dev/null
+++ b/Sources/AetherEngine/AetherEngine+RequestHeaders.swift
@@ -0,0 +1,90 @@
+import Foundation
+
+/// AE#792: replacing a live session's request headers without a rebuild.
+///
+/// A media server that requires a bearer token on every request, with tokens that live an hour,
+/// rotates the credential under any long title. Nothing about the session changes when it does:
+/// the source, the routing and the byte stream are the same, and only the value of one header is
+/// new. `reloadAtCurrentPosition(applying:)` (#460) can install it, but it is a teardown at the
+/// playhead, a visible restart bought for a value only the NEXT request reads.
+///
+/// Every request an `AVIOReader` builds goes through `headers(for:)`, so the only thing that kept a
+/// session on its load-time headers was that each reader froze a copy at its open. The session now
+/// creates one `RequestHeaderStore` per load and hands it to every reader it opens on its source
+/// (the playback demuxer, the producer's reopens and revives, the I-frame and subtitle side
+/// readers); this call replaces the value in it.
+extension AetherEngine {
+
+    /// Replace the HTTP headers the session's source requests carry, from the next request on,
+    /// without a rebuild (AE#792).
+    ///
+    /// ```swift
+    /// player.updateRequestHeaders(["Authorization": "Bearer \(fresh)"])
+    /// ```
+    ///
+    /// The set REPLACES the current one, the way `LoadOptions.httpHeaders` does at `load`; it is not
+    /// merged. It is also installed into the session's options, so every rebuild that replays them
+    /// (an audio switch, a background return, `reloadAtCurrentPosition()`) opens with it too.
+    ///
+    /// A request already in flight finishes with the headers it was sent with. A reconnect that is
+    /// backing off after a refusal sends the new set on its next attempt, so a session stalled over
+    /// a lapsed credential heals without a teardown once the host supplies a current one.
+    /// `RedirectHeaderPolicy` scoping is unchanged: a credential still does not follow a
+    /// cross-origin redirect.
+    ///
+    /// - Returns: whether the session's live requests will carry the new set. See
+    ///   `RequestHeaderUpdateOutcome`; on `.installedForNextRebuild` call
+    ///   `reloadAtCurrentPosition()` if the headers are needed now.
+    @discardableResult
+    public func updateRequestHeaders(_ headers: [String: String]) -> RequestHeaderUpdateOutcome {
+        guard let url = loadedURL else {
+            EngineLog.emit("[AetherEngine] AE#792: request headers not updated, no active session",
+                           category: .engine)
+            return .noActiveSession
+        }
+        setLoadedHTTPHeaders(headers)
+        sessionRequestHeaders.replace(headers)
+        let outcome = RequestHeaderUpdateOutcome.forSession(
+            isCustomSource: isCustomSource,
+            isDiscImage: !isCustomSource && Demuxer.isDiscImageURL(url),
+            route: videoRoute,
+            audioRequestsOwnedByAVFoundation: audioSessionRequestsOwnedByAVFoundation)
+        // Names only: the values are credentials.
+        EngineLog.emit(
+            "[AetherEngine] AE#792: request headers replaced (\(headers.keys.sorted().joined(separator: ", "))): "
+            + (outcome == .appliedToLiveRequests
+                ? "live, the next source request carries them"
+                : "installed for the next rebuild, this session's requests are fixed at load"),
+            category: .engine)
+        return outcome
+    }
+}
+
+/// What `updateRequestHeaders(_:)` did (AE#792).
+public enum RequestHeaderUpdateOutcome: Sendable, Equatable {
+    /// The session's source readers send the new set on their next request, a reconnect already
+    /// backing off included. Nothing was torn down.
+    case appliedToLiveRequests
+    /// The session's requests are made by something that fixed its headers when the session was
+    /// built: AVFoundation on a `.remoteBypass` route or an AVPlayer-hosted audio item, a custom
+    /// `IOReader` the host built, or a remote disc image. The set is installed for the next rebuild;
+    /// call `reloadAtCurrentPosition()` if it is needed now.
+    case installedForNextRebuild
+    /// Nothing is loaded. Nothing was installed.
+    case noActiveSession
+
+    /// Which session shapes have every source request built by an `AVIOReader` that reads the
+    /// session's store. `.none` is a load still opening, whose probe reader already reads it.
+    static func forSession(isCustomSource: Bool, isDiscImage: Bool, route: VideoRoute,
+                           audioRequestsOwnedByAVFoundation: Bool) -> RequestHeaderUpdateOutcome {
+        if isCustomSource || isDiscImage { return .installedForNextRebuild }
+        switch route {
+        case .remoteBypass:
+            return .installedForNextRebuild
+        case .audio:
+            return audioRequestsOwnedByAVFoundation ? .installedForNextRebuild : .appliedToLiveRequests
+        case .none, .loopback, .software:
+            return .appliedToLiveRequests
+        }
+    }
+}
diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index 812b1e686..02ab63cbf 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -734,6 +734,7 @@ extension AetherEngine {
         let isCustom = isCustomSource
         if isCustom, customReader == nil { return }
         let headers = loadedOptions.httpHeaders
+        let headerStore = sessionRequestHeaders
         let formatHint = customFormatHint
         let probesize = loadedOptions.probesize
         let maxAnalyzeDuration = loadedOptions.maxAnalyzeDuration
@@ -785,7 +786,7 @@ extension AetherEngine {
                 guard let self else { return }
                 let outcome = await self.runSubtitleForwardPrefetchSession(
                     url: url, reader: attemptReader, formatHint: formatHint, headers: headers,
-                    startAt: resumeAt, callerProbesize: probesize,
+                    headerStore: headerStore, startAt: resumeAt, callerProbesize: probesize,
                     callerMaxAnalyzeDuration: maxAnalyzeDuration,
                     selectTitleID: titleID, store: store, leadSeconds: lead, link: link)
                 guard outcome.exit.isRestartable, !Task.isCancelled else { return }
@@ -837,6 +838,7 @@ extension AetherEngine {
     /// packets to the SubtitlePacketStore instead of decoded cues to native stores.
     nonisolated private func runSubtitleForwardPrefetchSession(
         url: URL, reader: IOReader?, formatHint: String?, headers: [String: String],
+        headerStore: RequestHeaderStore?,
         startAt: Double, callerProbesize: Int64?, callerMaxAnalyzeDuration: Int64?,
         selectTitleID: Int?, store: SubtitlePacketStore, leadSeconds: Double,
         link: SideReaderLinkArbiter?
@@ -844,6 +846,7 @@ extension AetherEngine {
         let demuxer = Demuxer()
         let openProfile = DemuxerOpenProfile.subtitleSideDemuxer(
             callerProbesize: callerProbesize, callerMaxAnalyzeDuration: callerMaxAnalyzeDuration).withReaderLabel("prefetch")
+            .withRequestHeaders(headerStore)
         let registered = await MainActor.run { [weak self] () -> Bool in
             guard !Task.isCancelled, let self else { return false }
             self.subtitleForwardPrefetchDemuxer = demuxer
@@ -1742,6 +1745,7 @@ extension AetherEngine {
             customClone = clone
         }
         let headers = loadedOptions.httpHeaders
+        let headerStore = sessionRequestHeaders
         let formatHint = customFormatHint
         let w = sourceVideoWidth > 0 ? sourceVideoWidth : 1920
         let h = sourceVideoHeight > 0 ? sourceVideoHeight : 1080
@@ -1767,7 +1771,7 @@ extension AetherEngine {
         nativeSubtitleReadersTask = BlockingWork.detached(priority: .utility) { [weak self] in
             await self?.runNativeSubtitleReaders(
                 url: url, reader: reader, formatHint: formatHint, headers: headers,
-                pairs: pairs, startAt: startAt, videoWidth: w, videoHeight: h,
+                headerStore: headerStore, pairs: pairs, startAt: startAt, videoWidth: w, videoHeight: h,
                 callerProbesize: probesize, callerMaxAnalyzeDuration: maxAnalyzeDuration,
                 selectTitleID: titleID, readToEOF: readToEOF, link: link
             )
@@ -1825,6 +1829,7 @@ extension AetherEngine {
     nonisolated private func runNativeSubtitleReaders(
         url: URL, reader: IOReader?, formatHint: String?,
         headers: [String: String],
+        headerStore: RequestHeaderStore?,
         pairs: [(streamIndex: Int32, store: NativeSubtitleCueStore)],
         startAt: Double, videoWidth: Int32, videoHeight: Int32,
         callerProbesize: Int64? = nil, callerMaxAnalyzeDuration: Int64? = nil,
@@ -1834,6 +1839,7 @@ extension AetherEngine {
         let demuxer = Demuxer()
         let openProfile = DemuxerOpenProfile.subtitleSideDemuxer(
             callerProbesize: callerProbesize, callerMaxAnalyzeDuration: callerMaxAnalyzeDuration).withReaderLabel("nativesubs")
+            .withRequestHeaders(headerStore)
         let registered = await MainActor.run { [weak self] () -> Bool in
             guard !Task.isCancelled, let self else { return false }
             self.nativeSubtitleReadersDemuxer = demuxer
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 519136866..4d8fb5c18 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2294,6 +2294,20 @@ public final class AetherEngine: ObservableObject {
     /// `load`, the custom-source branch reads these fields one by one). See `rebuildResumesPlaying`.
     func setLoadedAutoplay(_ autoplay: Bool) { loadedOptions.autoplay = autoplay }
 
+    /// AE#792: the fifth narrow write, for the same reason as the teletext page. A rotated credential
+    /// has to live where the session's own rebuilds replay it from, or the next audio switch, background
+    /// return or revive would reopen with the header the origin already refused.
+    func setLoadedHTTPHeaders(_ headers: [String: String]) { loadedOptions.httpHeaders = headers }
+
+    /// AE#792: the session's live request headers. One store per load, created from
+    /// `LoadOptions.httpHeaders`, handed to every reader the session opens on its source, and
+    /// replaced in place by `updateRequestHeaders(_:)`.
+    var sessionRequestHeaders = RequestHeaderStore([:])
+
+    /// AE#792: the audio-only session is an `AVPlayer` item, whose request headers AVFoundation fixed
+    /// at asset creation. Reset by every load.
+    var audioSessionRequestsOwnedByAVFoundation = false
+
     /// AE#460: the second narrow write into `loadedOptions` outside a load, for a host correction
     /// that a session-preserving reload is about to rebuild on. Installed before the rebuild rather
     /// than carried through it, because only the URL branch passes a struct into `load`: the
@@ -4183,6 +4197,10 @@ public final class AetherEngine: ObservableObject {
         }
         loadedURL = url
         loadedOptions = options
+        // AE#792: a fresh store per load, so a header rotated on the previous session can never reach
+        // this one through a reader that outlived it.
+        sessionRequestHeaders = RequestHeaderStore(options.httpHeaders)
+        audioSessionRequestsOwnedByAVFoundation = false
         // #377: register the host's concurrency ceiling for this origin before anything fetches
         // from it. Keyed on the origin rather than the load, so the subtitle side reader and any
         // later reopen of the same source are bound by it too.
@@ -4432,7 +4450,7 @@ public final class AetherEngine: ObservableObject {
             // AetherEngine#10: a @MainActor async body without a suspension point blocks the main thread
             // despite the async signature; a detached task's value introduces a real background hop,
             // and BlockingWork keeps that hop off the cooperative pool while the open blocks.
-            try await BlockingWork.detached(priority: .userInitiated) { [probe, source, options] in
+            try await BlockingWork.detached(priority: .userInitiated) { [probe, source, options, requestHeaders = sessionRequestHeaders] in
                 // Caller-bounded find_stream_info budget (#68); nil keeps the .playback default. This probe
                 // demuxer is reused as the session demuxer, so the cap lands on the open that actually pays it.
                 let probeProfile = DemuxerOpenProfile.playback.withProbeBudget(
@@ -4441,6 +4459,7 @@ public final class AetherEngine: ObservableObject {
                                           declaredDuration: options.declaredDurationSeconds)
                     .withHeldSourceConnection(options.heldSourceConnection)
                     .withSourceOpenPolicy(options.sourceOpenPolicy)
+                    .withRequestHeaders(requestHeaders)
                 switch source {
                 case .url(let u):
                     // isLive configures the AVIOReader for endless-feed mode; must be set at open time because
@@ -4792,6 +4811,7 @@ public final class AetherEngine: ObservableObject {
                     if probeOpened { probe.close() }
                     try await loadAudioNative(url: url, startPosition: startPosition, httpHeaders: options.httpHeaders, generation: gen)
                     try checkLoadCurrent(gen)
+                    audioSessionRequestsOwnedByAVFoundation = true
                     playbackBackend = .audio
                     activeVideoDecoder = nil
                     activeAudioDecoder = "AVPlayer"
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 1e3821ab8..831ddfa3a 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -41,7 +41,13 @@ struct NetworkPhaseGate {
 final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
     private let url: URL
-    private let extraHeaders: [String: String]
+    private let openedHeaders: [String: String]
+    /// AE#792: the session's live header set, when the reader was opened for one. Read per request,
+    /// so a host that rotates a credential mid-session reaches the next request (a reconnect already
+    /// backing off included) without a rebuild. Nil for every reader opened outside a session (a probe,
+    /// a sidecar, a still), which keep the headers they were opened with.
+    private let requestHeaderStore: RequestHeaderStore?
+    private var extraHeaders: [String: String] { requestHeaderStore?.current ?? openedHeaders }
     /// #450: connections the BOUNDED pool may hold to one host. A throttle, and it is allowed to be
     /// one: every request on that pool ends (a 4 MB detour block, a size probe, the tail prefetch),
     /// so a request that waits here waits for one that is finishing.
@@ -1123,13 +1129,14 @@ 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, detourIdleSeconds: TimeInterval? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil, sourceOpenPolicy: SourceOpenPolicy = .init()) {
+    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, sourceOpenPolicy: SourceOpenPolicy = .init(), requestHeaderStore: RequestHeaderStore? = nil) {
         self.sourceOpenPolicy = sourceOpenPolicy
         self.probeControl = probeControl
         self.probeRequestSession = probeControl == nil ? nil : probeRequestSession
         self.url = url
         self.label = label
-        self.extraHeaders = extraHeaders
+        self.openedHeaders = extraHeaders
+        self.requestHeaderStore = requestHeaderStore
         self.chunkSize = chunkSize
         self.prefetchEnabled = prefetchEnabled
         self.isLive = isLive
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 8ef28a3c9..387695c53 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -82,6 +82,10 @@ struct DemuxerOpenProfile: Sendable {
     /// distinguished them. Defaults to the pump, since every other path builds its profile explicitly.
     var readerLabel: String = "pump"
     var sourceOpenPolicy: SourceOpenPolicy = .init()
+    /// AE#792: the session's live header set. A reader opened with one reads its headers from it per
+    /// request instead of keeping the `extraHeaders` it was opened with, so a session-scoped open (the
+    /// playback demuxer, the producer's reopens) follows `updateRequestHeaders(_:)`. Nil everywhere else.
+    var requestHeaders: RequestHeaderStore? = nil
 
     func withSourceOpenPolicy(_ policy: SourceOpenPolicy) -> DemuxerOpenProfile {
         var copy = self
@@ -89,6 +93,12 @@ struct DemuxerOpenProfile: Sendable {
         return copy
     }
 
+    func withRequestHeaders(_ store: RequestHeaderStore?) -> DemuxerOpenProfile {
+        var copy = self
+        copy.requestHeaders = store
+        return copy
+    }
+
     /// Whether a probe of an untagged 10-bit HEVC source may read its first RPU to find a Dolby Vision
     /// Profile 5 the container never recorded (`DolbyVisionRecordAudit.addRecordIfProfile5`). On for every
     /// playback open, so the probe, the HLS producer's own open and every rebuild agree; off for the
@@ -782,7 +792,8 @@ public final class Demuxer: @unchecked Sendable {
             boundedInitialFetch: openProfile.boundedInitialFetch,
             sequentialOnly: openProfile.avioSequentialOnly,
             heldConnection: openProfile.avioHeldConnection,
-            sourceOpenPolicy: openProfile.sourceOpenPolicy
+            sourceOpenPolicy: openProfile.sourceOpenPolicy,
+            requestHeaderStore: openProfile.requestHeaders
         )
         reader.onNetworkPhaseChanged = onNetworkPhaseChanged
         reader.playIntentProvider = playIntentProvider
diff --git a/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift b/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift
new file mode 100644
index 000000000..3fb9d8e28
--- /dev/null
+++ b/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift
@@ -0,0 +1,31 @@
+import Foundation
+
+/// AE#792: the HTTP headers a session's source requests carry, as one value every reader of that
+/// session reads at request time instead of a copy each one froze at its open.
+///
+/// A credential that rotates under a playing session (a bearer token that lives an hour) changes
+/// nothing about the session except this value, and every request an `AVIOReader` builds already
+/// goes through one place (`headers(for:)`), so the value is the only thing that was frozen. The
+/// session creates one store per load, hands it to the readers it opens (through
+/// `DemuxerOpenProfile.requestHeaders`) and to the producer's reopens, and
+/// `AetherEngine.updateRequestHeaders(_:)` replaces the value in it. A request already in flight
+/// finishes with the headers it was sent with; the next one carries the new set.
+///
+/// Redirect scoping is not this type's business: `RedirectHeaderPolicy` still decides which of
+/// these headers a given target may see, on the value read here.
+final class RequestHeaderStore: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value: [String: String]
+
+    init(_ headers: [String: String]) {
+        value = headers
+    }
+
+    var current: [String: String] {
+        lock.withLock { value }
+    }
+
+    func replace(_ headers: [String: String]) {
+        lock.withLock { value = headers }
+    }
+}
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index 2aaa5f526..cb1ca822c 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -1069,7 +1069,8 @@ extension HLSVideoEngine {
             do {
                 switch transport {
                 case .url:
-                    try dem.open(url: sourceURL, extraHeaders: sourceHTTPHeaders, profile: openProfile, isLive: true)
+                    try dem.open(url: sourceURL, extraHeaders: sourceHTTPHeaders,
+                                 profile: openProfile.withRequestHeaders(requestHeaders), isLive: true)
                 case .customFactory:
                     // #199: fresh engine-created ingest reader over the same channel; the dead
                     // reader's construction inputs are immutable, so this rejoins at the live edge.
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 964f367e3..386c44c0f 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -41,7 +41,11 @@ public final class HLSVideoEngine: @unchecked Sendable {
     // MARK: - State
 
     let sourceURL: URL
-    let sourceHTTPHeaders: [String: String]
+    /// AE#792: the session's live header set. Seeded from `sourceHTTPHeaders` at init; `AetherEngine`
+    /// installs its session store here before `start()`, so the opens below and the playback demuxer it
+    /// hands over read the same value, and `updateRequestHeaders(_:)` reaches both.
+    var requestHeaders: RequestHeaderStore
+    var sourceHTTPHeaders: [String: String] { requestHeaders.current }
     private let dvModeAvailable: Bool
 
     /// From `LoadOptions.keepDvh1TagWithoutDV`; default OFF, set only for misreporting DV panels.
@@ -1037,7 +1041,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         forwardBufferSegments: Int? = nil
     ) {
         self.sourceURL = url
-        self.sourceHTTPHeaders = sourceHTTPHeaders
+        self.requestHeaders = RequestHeaderStore(sourceHTTPHeaders)
         self.sequentialOrigin = sequentialOrigin
         self.heldSourceConnection = heldSourceConnection
         self.declaredDurationSeconds = declaredDurationSeconds
@@ -1197,6 +1201,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             .withSourceOpenPolicy(openProfile.sourceOpenPolicy)
             .withSequentialOrigin(sequentialOrigin, declaredDuration: declaredDurationSeconds)
             .withHeldSourceConnection(heldSourceConnection)
+            .withRequestHeaders(requestHeaders)
     }
 
     /// `LoadOptions.sequentialOrigin` for this session. Gates the VOD readError revive
@@ -1258,7 +1263,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
         } else {
             dem = Demuxer()
             do {
-                try dem.open(url: sourceURL, extraHeaders: sourceHTTPHeaders, profile: openProfile, isLive: isLiveSession)
+                try dem.open(url: sourceURL, extraHeaders: sourceHTTPHeaders,
+                             profile: openProfile.withRequestHeaders(requestHeaders), isLive: isLiveSession)
             } catch {
                 throw Self.openFailure(from: error)
             }
@@ -2843,7 +2849,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             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 url = sourceURL, headers = sourceHTTPHeaders, headerStore = requestHeaders, custom = customIFrameReader
         // The side reader owns the clone from here; `stop()` must not close it a second time.
         customIFrameReader = nil
         let reader = IFrameSideReader(
@@ -2852,7 +2858,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
                     try dem.open(reader: custom.reader, formatHint: custom.formatHint,
                                  profile: .iFrameSideDemuxer)
                 } else {
-                    try dem.open(url: url, extraHeaders: headers, profile: .iFrameSideDemuxer, isLive: false)
+                    try dem.open(url: url, extraHeaders: headers,
+                                 profile: DemuxerOpenProfile.iFrameSideDemuxer.withRequestHeaders(headerStore),
+                                 isLive: false)
                 }
             },
             cleanup: { custom?.reader.close() },
diff --git a/Tests/AetherEngineTests/LiveRequestHeaderTests.swift b/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
new file mode 100644
index 000000000..24128aa22
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
@@ -0,0 +1,130 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// AE#792: a session's request headers can be replaced while it plays, and the reader that is
+/// already open sends the new set on its next request.
+///
+/// The shape this exists for is a media server whose bearer tokens live an hour. Mid-title the
+/// origin starts refusing the token the reader was opened with; the host mints a new one and hands
+/// it over; the reader's reconnect, already backing off, must carry it rather than the header it
+/// froze at its open. Before the store, the only way to get it there was a rebuild of the session.
+@Suite("Live request headers", .serialized, .offCooperativePool)
+struct LiveRequestHeaderTests {
+
+    /// An origin whose first token lapses after the opening range: "first" is served below
+    /// `lapsesAt` and refused from there on, "second" is served everywhere. Tying the lapse to the
+    /// offset rather than to a moment keeps the read from racing the rotation.
+    final class TokenGate: @unchecked Sendable {
+        private let lock = NSLock()
+        private var refused = 0
+        let lapsesAt: Int64
+        weak var origin: ThrottledOriginServer?
+
+        init(lapsesAt: Int64) { self.lapsesAt = lapsesAt }
+        var refusals: Int { lock.withLock { refused } }
+
+        func answer(_ index: Int, offset: Int64) -> ThrottledOriginServer.Directive {
+            let sent = origin?.requestHeaders[index]["authorization"]
+            if sent == "Bearer second" || (sent == "Bearer first" && offset < lapsesAt) { return .serve206 }
+            lock.withLock { refused += 1 }
+            return .status(401)
+        }
+    }
+
+    @Test("a reader stalled on a refused token heals on the next attempt once the store holds a new one",
+          .timeLimit(.minutes(2)))
+    func refusedTokenHealsWithoutReopen() async throws {
+        let firstRange: Int64 = 256 * 1024
+        let gate = TokenGate(lapsesAt: firstRange)
+        let originMaybe = ThrottledOriginServer(totalSize: 64 * 1024 * 1024,
+                                                respond: { index, offset, _ in gate.answer(index, offset: offset) })
+        let origin = try #require(originMaybe)
+        gate.origin = origin
+        defer { origin.stop() }
+
+        let store = RequestHeaderStore(["Authorization": "Bearer first"])
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(origin.port)/movie.bin")!,
+                                extraHeaders: store.current,
+                                boundedInitialFetch: firstRange,
+                                requestHeaderStore: store)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let target = Int(firstRange) + 1024 * 1024
+        let delivered = Delivered()
+        Thread.detachNewThread {
+            let sliceCap = 128 * 1024
+            let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: sliceCap)
+            defer { buf.deallocate() }
+            var got = 0
+            while got < target {
+                let n = reader.read(into: buf, size: Int32(min(sliceCap, target - got)))
+                if n <= 0 { break }
+                got += Int(n)
+            }
+            delivered.finish(got)
+        }
+
+        // The reader has met the refusal and is in its reconnect ladder before the host renews.
+        try await waitFor { gate.refusals >= 1 }
+        store.replace(["Authorization": "Bearer second"])
+
+        try await waitFor { delivered.total != nil }
+        #expect(delivered.total == target, "the read healed past the refusal instead of failing")
+        let sent = origin.requestHeaders.map { $0["authorization"] }
+        #expect(sent.last == "Bearer second", "the healing request carried the renewed token")
+        // One reader all the way through: the same AVIOReader was never reopened, it only reconnected.
+        #expect(sent.first == "Bearer first")
+    }
+
+    @Test("a reader opened without a store keeps the headers it was opened with")
+    func readerWithoutStoreKeepsItsHeaders() async throws {
+        let originMaybe = ThrottledOriginServer(totalSize: 4 * 1024 * 1024)
+        let origin = try #require(originMaybe)
+        defer { origin.stop() }
+        let unrelated = RequestHeaderStore(["Authorization": "Bearer session"])
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(origin.port)/side.bin")!,
+                                extraHeaders: ["Authorization": "Bearer opened"],
+                                boundedInitialFetch: 64 * 1024)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        unrelated.replace(["Authorization": "Bearer rotated"])
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: 64 * 1024)
+        defer { buf.deallocate() }
+        _ = reader.read(into: buf, size: 64 * 1024)
+        #expect(origin.requestHeaders.allSatisfy { $0["authorization"] == "Bearer opened" })
+    }
+
+    @Test("the outcome says live only where every source request is built by the session's readers")
+    func outcomeFollowsWhoOwnsTheRequests() {
+        func outcome(custom: Bool = false, disc: Bool = false, route: VideoRoute,
+                     avAudio: Bool = false) -> RequestHeaderUpdateOutcome {
+            .forSession(isCustomSource: custom, isDiscImage: disc, route: route,
+                        audioRequestsOwnedByAVFoundation: avAudio)
+        }
+        #expect(outcome(route: .loopback) == .appliedToLiveRequests)
+        #expect(outcome(route: .software) == .appliedToLiveRequests)
+        #expect(outcome(route: .audio) == .appliedToLiveRequests)
+        #expect(outcome(route: .none) == .appliedToLiveRequests)
+        #expect(outcome(route: .remoteBypass) == .installedForNextRebuild)
+        #expect(outcome(route: .audio, avAudio: true) == .installedForNextRebuild)
+        #expect(outcome(custom: true, route: .loopback) == .installedForNextRebuild)
+        #expect(outcome(disc: true, route: .loopback) == .installedForNextRebuild)
+    }
+
+    @Test("without a session the call installs nothing")
+    @MainActor
+    func noSessionInstallsNothing() throws {
+        let engine = try AetherEngine()
+        #expect(engine.updateRequestHeaders(["Authorization": "Bearer x"]) == .noActiveSession)
+        #expect(engine.loadedOptions.httpHeaders.isEmpty)
+    }
+
+    final class Delivered: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value: Int?
+        func finish(_ n: Int) { lock.withLock { value = n } }
+        var total: Int? { lock.withLock { value } }
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 6d57bd759..5ce504f40 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -281,6 +281,39 @@ session sat in `.error`; it now throws what the rebuild threw, the way the URL b
 rebuild superseded by a newer `load` or `stop` is not a failure and still returns normally, because
 the newer load owns the session.
 
+### Rotating a credential without a rebuild
+
+A media server that requires a bearer token on every request, with tokens that expire while a title
+plays, needs the next request to carry a new header and nothing else to change.
+`updateRequestHeaders(_:)` does that without the teardown `reloadAtCurrentPosition(applying:)` pays
+(AE#792):
+
+```swift
+let outcome = player.updateRequestHeaders(["Authorization": "Bearer \(fresh)"])
+```
+
+The set replaces the session's headers, the way `LoadOptions.httpHeaders` sets them at `load`; it is
+not merged. The session's source readers (the playback demuxer, the producer's reopens and revives,
+the I-frame and embedded-subtitle side readers) read their headers per request from one store the
+session creates at `load`, so the next request any of them makes carries the new set. A request
+already in flight finishes with the headers it was sent with. A reconnect already backing off after
+a refusal sends the new set on its next attempt, so a session stalled over a lapsed credential
+(`.stalled(reconnecting: true)`) recovers without a rebuild once the host supplies a current one;
+renewing ahead of the expiry avoids the stall entirely. The set is also installed into the session's
+options, so every rebuild that replays them (an audio switch, a background return,
+`reloadAtCurrentPosition()`) opens with it. Redirect scoping is unchanged: a credential still does
+not follow a cross-origin redirect.
+
+The call returns a `RequestHeaderUpdateOutcome`:
+
+| Outcome | When |
+| --- | --- |
+| `.appliedToLiveRequests` | every source request is made by the session's own readers: the `.loopback`, `.software` and FFmpeg `.audio` routes, and a load still opening. |
+| `.installedForNextRebuild` | the requests are made by something that fixed its headers when the session was built: AVFoundation on `.remoteBypass` or an AVPlayer-hosted audio item, a custom `IOReader` the host built, a remote disc image. Call `reloadAtCurrentPosition()` if the set is needed now. |
+| `.noActiveSession` | nothing is loaded; nothing was installed. |
+
+The log names the header names it replaced, never their values.
+
 ### Overriding the decode path
 
 `LoadOptions.preferredDecodePath` is the per-session escape onto `SoftwarePlaybackHost` (#461).

From f310def6f3802ba8c32e160ee7b067692d9b58c5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 22:21:37 +0200
Subject: [PATCH 080/132] feat(audio): TrackInfo.isDTSX, from the profile and
 from LibDTSX's verdict

FFmpeg labels DTS:X by two of its markers only, so a DTS-HD MA track it
calls plain can be DTS:X, and the object-audio route already learns that
from LibDTSX before it builds the bridge (#744). The verdict now reaches
the host: `TrackInfo.isDTSX` is set from libavcodec's DTS:X profiles at
probe time, and a track LibDTSX confirms while it plays is recorded in a
ledger keyed to its source, like the confirmed-JOC one, and republished
in `audioTracks`. Every republish goes through `applyConfirmedTrackFlags()`
so a track switch or title switch does not drop either flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |  7 +++-
 Sources/AetherEngine/AetherEngine.swift       |  7 +++-
 .../Audio/AtmosConfirmationWorker.swift       |  4 +-
 .../AetherEngine/Audio/DTSXConfirmation.swift | 42 +++++++++++++++++++
 Sources/AetherEngine/PlayerState.swift        | 15 ++++++-
 .../Video/HLSVideoEngine+SpatialAudio.swift   |  1 +
 .../AetherEngine/Video/HLSVideoEngine.swift   |  4 ++
 .../DTSXConfirmationTests.swift               | 37 ++++++++++++++++
 docs/api.md                                   |  4 +-
 9 files changed, 113 insertions(+), 8 deletions(-)
 create mode 100644 Sources/AetherEngine/Audio/DTSXConfirmation.swift
 create mode 100644 Tests/AetherEngineTests/DTSXConfirmationTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index dde59e682..5b37c6a32 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2293,7 +2293,7 @@ extension AetherEngine {
         let sideTracks = session.companionAudioTracks
         if !sideTracks.isEmpty {
             audioTracks = sideTracks
-            applyConfirmedAtmos()   // #214 follow-up: a whole-list swap must not drop confirmed JOC
+            applyConfirmedTrackFlags()   // #214 follow-up: a whole-list swap must not drop confirmed JOC
         }
         let active = session.activeAudioSourceStreamIndex
         let resolved: Int? = active >= 0 ? Int(active) : nil
@@ -2306,6 +2306,9 @@ extension AetherEngine {
             )
             activeAudioTrackIndex = resolved
         }
+        if session.audioIsConfirmedDTSX, active >= 0 {
+            recordConfirmedDTSX(streamIndex: active)
+        }
     }
 
     /// Rebuild the pipeline at the current playhead with an optional audio stream override (nil = keep auto-picked). Re-arms the active subtitle source. Called by `selectAudioTrack` and `reloadAtCurrentPosition`. Snapshots subtitle + playhead INSIDE the task body: a chained `selectSubtitleTrack` lands on MainActor before the body runs; snapshotting at call-site would miss it.
@@ -2736,7 +2739,7 @@ extension AetherEngine {
             // not reconcile tracks post-load, needs the probe-derived lists re-applied here.
             if targetSoftwarePath {
                 audioTracks = reopenedAudioTracks
-                applyConfirmedAtmos()   // #214 follow-up: a title switch re-applies probe lists
+                applyConfirmedTrackFlags()   // #214 follow-up: a title switch re-applies probe lists
                 subtitleTracks = reopenedSubtitleTracks
             }
         } else {
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 519136866..e2dfaddb1 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2435,6 +2435,11 @@ public final class AetherEngine: ObservableObject {
     var confirmedAtmosStreamIndices: Set<Int32> = []
     var confirmedAtmosSource: URL?
 
+    /// #744 follow-up: the stream indices LibDTSX confirmed as DTS:X while they played, keyed to their
+    /// source like the Atmos ledger above and republished through `applyConfirmedTrackFlags()`.
+    var confirmedDTSXStreamIndices: Set<Int32> = []
+    var confirmedDTSXSource: URL?
+
     /// AE#154: publishes the remote-HLS bypass item's legible options as `subtitleTracks`.
     /// Session-scoped; cancelled on load()/stop() alongside the other subtitle tasks.
     var remoteHLSSubtitleDiscoveryTask: Task<Void, Never>? = nil
@@ -4698,7 +4703,7 @@ public final class AetherEngine: ObservableObject {
             : avcodec_get_name(detectedCodecID).map { String(cString: $0) }
         sourceContainerFormat = probeOpened ? probe.containerFormatName : nil
         audioTracks = probedAudioTracks
-        applyConfirmedAtmos()
+        applyConfirmedTrackFlags()
         subtitleTracks = probedSubtitleTracks
         // #88: load-declared external tracks join the list now, BEFORE preferred-language selection
         // and the native rendition table are built from it.
diff --git a/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift b/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift
index c2016f9ad..5b805971b 100644
--- a/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift
+++ b/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift
@@ -57,7 +57,7 @@ extension AetherEngine {
             confirmedAtmosSource = url
             confirmedAtmosStreamIndices = []
         }
-        applyConfirmedAtmos()
+        applyConfirmedTrackFlags()
         let candidates = Self.atmosConfirmationCandidates(in: audioTracks)
         guard !candidates.isEmpty else { return }
         if isCustomSource, !Self.canForkCustomReader(customReader) { return }
@@ -112,7 +112,7 @@ extension AetherEngine {
                 await MainActor.run { [weak self] in
                     guard let self, self.loadedURL == self.confirmedAtmosSource else { return }
                     self.confirmedAtmosStreamIndices.insert(index)
-                    self.applyConfirmedAtmos()
+                    self.applyConfirmedTrackFlags()
                 }
             }
         }
diff --git a/Sources/AetherEngine/Audio/DTSXConfirmation.swift b/Sources/AetherEngine/Audio/DTSXConfirmation.swift
new file mode 100644
index 000000000..f817b5616
--- /dev/null
+++ b/Sources/AetherEngine/Audio/DTSXConfirmation.swift
@@ -0,0 +1,42 @@
+import Foundation
+
+// #744 follow-up: `TrackInfo.isDTSX` from LibDTSX's verdict. FFmpeg labels DTS:X by two of its
+// markers only, so a DTS-HD MA track it calls plain can turn out to be DTS:X once the object-audio
+// route decodes it. The verdict is about the track, so it outlives the session that produced it the
+// same way a confirmed JOC flag does.
+extension AetherEngine {
+
+    /// Every republish of `audioTracks` runs through here (see `applyConfirmedAtmos`).
+    func applyConfirmedTrackFlags() {
+        applyConfirmedAtmos()
+        guard !confirmedDTSXStreamIndices.isEmpty, loadedURL == confirmedDTSXSource else { return }
+        let flagged = Self.applyingConfirmedDTSX(to: audioTracks, confirmed: confirmedDTSXStreamIndices)
+        if flagged != audioTracks { audioTracks = flagged }
+    }
+
+    /// Called once the native session has published its pick, so `streamIndex` is in the numbering
+    /// `audioTracks` uses. A new item starts a new ledger; a reload of the same one keeps it.
+    func recordConfirmedDTSX(streamIndex: Int32) {
+        guard let url = loadedURL else { return }
+        if confirmedDTSXSource != url {
+            confirmedDTSXSource = url
+            confirmedDTSXStreamIndices = []
+        }
+        guard confirmedDTSXStreamIndices.insert(streamIndex).inserted else { return }
+        EngineLog.emit("[AetherEngine] #744: stream \(streamIndex) confirmed DTS:X by LibDTSX", category: .engine)
+        applyConfirmedTrackFlags()
+    }
+
+    /// Pure half of `applyConfirmedTrackFlags`. Additive, like the Atmos ledger: nothing is cleared.
+    nonisolated static func applyingConfirmedDTSX(to tracks: [TrackInfo], confirmed: Set<Int32>) -> [TrackInfo] {
+        guard !confirmed.isEmpty else { return tracks }
+        return tracks.map { track in
+            guard let index = Int32(exactly: track.id), confirmed.contains(index), !track.isDTSX else {
+                return track
+            }
+            var flipped = track
+            flipped.isDTSX = true
+            return flipped
+        }
+    }
+}
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index cd01aa3bc..2b9d8c31b 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -1277,6 +1277,12 @@ public struct TrackInfo: Identifiable, Sendable, Equatable {
     /// Settable inside the module so `probeDetectingAtmos` can confirm it post-decode without rebuilding the struct field by field.
     public internal(set) var isAtmos: Bool
 
+    /// DTS:X. True from the probe when libavcodec labels the profile DTS:X, and set during playback when
+    /// LibDTSX confirms a track FFmpeg labelled plain DTS-HD MA (FFmpeg reads only two of DTS:X's
+    /// markers). Never cleared once set for a session's source, so a confirmed track keeps its name in a
+    /// track menu after a switch away from it.
+    public internal(set) var isDTSX: Bool
+
     /// ASS / SSA tracks only: `[Script Info]` + `[V4+ Styles]` + `[Events]` format line from codec extradata. Hosts rendering ASS styling themselves (see `LoadOptions.preserveASSMarkup`) need it to resolve style references. nil for all other track kinds.
     public let assHeader: String?
 
@@ -1301,7 +1307,7 @@ public struct TrackInfo: Identifiable, Sendable, Equatable {
     /// 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) {
+    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, isDTSX: Bool = false) {
         self.sampleRate = sampleRate
         self.bitsPerSample = bitsPerSample
         self.sampleFormat = sampleFormat
@@ -1318,10 +1324,17 @@ public struct TrackInfo: Identifiable, Sendable, Equatable {
         self.isHearingImpaired = isHearingImpaired
         self.isCommentary = isCommentary
         self.isAtmos = isAtmos
+        self.isDTSX = isDTSX || Self.profileNamesDTSX(codec: codec, profile: profile)
         self.assHeader = assHeader
         self.isExternal = isExternal
         self.isNativelyRenderedSubtitle = isNativelyRenderedSubtitle
     }
+
+    /// libavcodec's DTS:X profiles, "DTS-HD MA + DTS:X" and "DTS-HD MA + DTS:X IMAX". `dca` is the
+    /// decoder's name, `dts` the codec's, which a build without the decoder reports.
+    static func profileNamesDTSX(codec: String, profile: String?) -> Bool {
+        ["dca", "dts"].contains(codec.lowercased()) && (profile?.contains("DTS:X") ?? false)
+    }
 }
 
 /// MKV attachment filtered to font payloads. Anime releases embed TTF/OTF fonts for their ASS styles; pass to the renderer's font directory (AetherEngine#30).
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index 4a20c485d..a35f0c0a1 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -188,6 +188,7 @@ extension HLSVideoEngine {
                     // The verdict decoded the first packets; the bridge starts from the same ones again.
                     dtsx.reset()
                     decoder = dtsx
+                    audioIsConfirmedDTSX = true
                 case .refused(let reason):
                     EngineLog.emit(
                         "[HLSVideoEngine] DTS-HD MA track is not DTS:X LibDTSX renders (\(reason)); "
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 964f367e3..ca6c51999 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -559,6 +559,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// `AtmosOutputActivator` beside the player to reach the receiver as Atmos.
     var audioIsAPAC = false
 
+    /// LibDTSX confirmed the playing track as DTS:X (#744), whatever FFmpeg's profile label said. The
+    /// engine folds it into the published track's `isDTSX`.
+    var audioIsConfirmedDTSX = false
+
     /// Producer's `videoShiftPts` in seconds, updated on every gate open. AVPlayer clock =
     /// `source_pts - playlistShiftSeconds`. Lock-guarded: written on pump thread, read on others.
     public var playlistShiftSeconds: Double {
diff --git a/Tests/AetherEngineTests/DTSXConfirmationTests.swift b/Tests/AetherEngineTests/DTSXConfirmationTests.swift
new file mode 100644
index 000000000..de38c930e
--- /dev/null
+++ b/Tests/AetherEngineTests/DTSXConfirmationTests.swift
@@ -0,0 +1,37 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+@Suite("DTS:X track flag: profile label and LibDTSX ledger")
+struct DTSXConfirmationTests {
+
+    private func dts(id: Int, profile: String?, codec: String = "dca") -> TrackInfo {
+        TrackInfo(id: id, name: "Track \(id) (\(codec))", codec: codec, language: nil, channels: 8,
+                  isDefault: id == 1, profile: profile)
+    }
+
+    @Test("libavcodec's DTS:X profiles mark the track from the probe on")
+    func profileLabel() {
+        #expect(dts(id: 1, profile: "DTS-HD MA + DTS:X").isDTSX)
+        #expect(dts(id: 1, profile: "DTS-HD MA + DTS:X IMAX").isDTSX)
+        #expect(dts(id: 1, profile: "DTS-HD MA + DTS:X", codec: "dts").isDTSX)
+        #expect(!dts(id: 1, profile: "DTS-HD MA").isDTSX)
+        #expect(!dts(id: 1, profile: nil).isDTSX)
+        #expect(!dts(id: 1, profile: "DTS:X", codec: "truehd").isDTSX)
+    }
+
+    @Test("a confirmed stream index flips its track, the others stay as they were")
+    func ledgerFlipsConfirmedOnly() {
+        let tracks = [dts(id: 1, profile: "DTS-HD MA"), dts(id: 2, profile: "DTS-HD MA"),
+                      dts(id: 3, profile: "DTS-HD MA + DTS:X")]
+        let out = AetherEngine.applyingConfirmedDTSX(to: tracks, confirmed: [1])
+        #expect(out.map(\.isDTSX) == [true, false, true])
+        #expect(out[0].profile == "DTS-HD MA")
+    }
+
+    @Test("an empty ledger hands the list back untouched")
+    func emptyLedger() {
+        let tracks = [dts(id: 1, profile: "DTS-HD MA")]
+        #expect(AetherEngine.applyingConfirmedDTSX(to: tracks, confirmed: []) == tracks)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 6d57bd759..f20262d61 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -743,7 +743,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 
 | Symbol | Notes |
 | --- | --- |
-| `$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`. |
+| `$audioTracks` | `[TrackInfo]`. Republished when `LoadOptions.confirmAtmos` confirms a track, and when LibDTSX confirms the playing track as DTS:X (`isDTSX`). 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. On the native path the old item stays mounted while the source reopens, and its last picture is held on the bound `AetherStillView` (or `AetherPlayerView`) across the item swap until the new item's first frame, so the switch shows a still rather than black (not gapless audio; nothing is held in PiP or on external playback, and a media-services reset still discards the item; see `AetherStillView` for the software path and Dolby Vision); 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. |
@@ -1264,7 +1264,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`, `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. |
+| `TrackInfo` | `id`, `name`, `codec`, `language`, `channels`, `bitrate`, `isDefault`, `isForced`, `isHearingImpaired`, `isCommentary`, `isAtmos`, `isDTSX`, `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. `isDTSX` is set from that DTS:X profile at probe time and, because FFmpeg reads only two of DTS:X's markers, also once LibDTSX confirms a track FFmpeg labelled plain DTS-HD MA while `objectAudioRendering` plays it; `audioTracks` is then republished and the flag stays for that source. `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 748cbd692ffd6481740617c523dfed51a3639b4e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 23:00:54 +0200
Subject: [PATCH 081/132] docs(audio): say which sinks take the lossless
 bridge, from measurement

The FLAC route warning and the bridge-mode docs said soundbars like the
Sonos Arc take multichannel only as a bitstream. Measured on an Apple TV
with a Sonos Arc on eARC (#794): the route reports 6 LPCM channels and
the FLAC bridge reaches it as lossless 5.1, where `.surroundCompat` gives
lossy 5.1. What needs EAC3 is a sink behind legacy ARC. The docs now say
so, and say why the engine does not pick the mode from the route: with
Continuous Audio Connection on, tvOS reports 32 unlabelled channels for
every HDMI sink.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/AudioBridge.swift       | 14 ++++++++------
 .../AetherEngine/Native/NativeAVPlayerHost.swift   | 12 ++++++------
 Sources/AetherEngine/PlayerState.swift             |  4 ++--
 docs/formats.md                                    |  6 ++++--
 4 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index dda591d2a..278726a3e 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -16,13 +16,15 @@ import AetherLibswresample
 /// produces no JOC, FLAC has no object channel concept). EAC3+JOC sources stay lossless via the stream-copy path
 /// that bypasses this bridge; only non-stream-copyable sources enter here.
 ///
-/// Encoder choice. Public so LoadOptions / the host pass it through; default `.surroundCompat` (soundbar /
-/// LPCM-stereo-only install base is the consumer majority).
+/// Encoder choice. Public so LoadOptions / the host pass it through; default `.surroundCompat`, the one mode
+/// that keeps surround on every sink.
 ///   - `.surroundCompat`: EAC3 128 kbps/channel (256 stereo, 768 5.1), AVPlayer -> HDMI bitstream tunnel. Lossy,
-///     caps at 5.1 (7.1 loses SL/SR), but surround works on essentially every AVR + soundbar including LPCM-stereo-
-///     only routes (Sonos Arc, Samsung HW-Q, Bose) where FLAC falls down.
-///   - `.lossless`: FLAC up to 7.1, AVPlayer -> LPCM HDMI route. Needs a multichannel-LPCM sink (Denon/Marantz/NAD);
-///     a stereo-LPCM route downmixes to stereo.
+///     caps at 5.1 (a 7.1 source is downmixed, its back surrounds folded into the sides), but surround works on
+///     every AVR and soundbar, including one behind legacy ARC (stereo LPCM or a Dolby bitstream only).
+///   - `.lossless`: FLAC up to 7.1, AVPlayer -> LPCM HDMI route. Needs a multichannel-LPCM sink: an AVR over
+///     HDMI, or an AVR or soundbar on eARC (a Sonos Arc there takes 6 channels, so lossless 5.1). A legacy-ARC
+///     route downmixes to stereo. Not picked from the route: with Continuous Audio Connection on, tvOS reports
+///     32 channels for every HDMI sink (AE#794).
 public enum AudioBridgeMode: String, Sendable, CaseIterable {
     case surroundCompat
     case lossless
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index d2e351df1..3a145add0 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2891,7 +2891,7 @@ final class NativeAVPlayerHost {
         return parts.joined(separator: " ")
     }
 
-    /// Warn when the FLAC bridge produced N-channel LPCM but the route carries fewer channels. FLAC bridge decodes to LPCM (unlike stream-copy EAC3/AC3 which tunnels encoded); Sonos Arc reports ch=2 LPCM even with eARC. Not a bridge bug -- a route capability mismatch.
+    /// Warn when the FLAC bridge produced N-channel LPCM but the route carries fewer channels. FLAC bridge decodes to LPCM (unlike stream-copy EAC3/AC3 which tunnels encoded). Not a bridge bug, a route capability mismatch. Silent with tvOS's Continuous Audio Connection on: every HDMI route then reports 32 channels whatever the sink takes (AE#794), so the route cannot show a mismatch.
     private static func warnIfFLACSurroundExceedsRoute(_ item: AVPlayerItem, sid: Int) async {
         #if os(iOS) || os(tvOS)
         var trackChannels: Int = 0
@@ -2919,11 +2919,11 @@ final class NativeAVPlayerHost {
         EngineLog.emit(
             "[NativeAVPlayerHost] #\(sid) WARNING: FLAC bridge produced \(trackChannels)-channel "
             + "LPCM but active audio route carries only \(routeChannels) LPCM channels, tvOS "
-            + "will downmix. Common cause: soundbars (Sonos Arc, etc.) accept multichannel only "
-            + "via bitstream codecs (EAC3, Atmos, DD+), not LPCM. Stream-copy paths bypass this; "
-            + "TrueHD / DTS-HD MA sources route through the FLAC bridge and hit the LPCM limit. "
-            + "AVRs with 7.1 LPCM-over-HDMI support play these sources at full source channel "
-            + "count without downmix.",
+            + "will downmix. A 6-channel route is a 5.1 sink (an eARC soundbar such as a Sonos "
+            + "Arc takes 6-channel LPCM), which still gets lossless 5.1; a 2-channel route is a "
+            + "sink behind legacy ARC or one that renegotiated to stereo after idling, where "
+            + "audioBridgeMode .surroundCompat (EAC3 5.1) keeps the surround. An AVR with 7.1 "
+            + "LPCM over HDMI plays the full source channel count.",
             category: .session
         )
         #endif
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 2b9d8c31b..00803a040 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -567,8 +567,8 @@ public struct LoadOptions: Sendable, Equatable {
 
     /// Bridge encoder for codecs that cannot stream-copy into fMP4 (TrueHD, DTS, DTS-HD MA, MP3, Opus, EAC3-from-MKV-without-dec3-extradata).
     ///
-    /// - `.surroundCompat` (default): EAC3 128 kbps/ch. Works on soundbars (Sonos Arc, Samsung HW-Q, Bose). Lossy; caps 7.1 to 5.1.
-    /// - `.lossless`: FLAC up to 7.1. Needs a sink that accepts multichannel LPCM (Denon / Marantz / NAD AVRs); stereo-only routes silently downmix.
+    /// - `.surroundCompat` (default): EAC3 128 kbps/ch. Surround on every sink, including a soundbar behind legacy ARC. Lossy; downmixes 7.1 to 5.1.
+    /// - `.lossless`: FLAC up to 7.1. Needs a sink that takes multichannel LPCM (an AVR over HDMI, or an AVR or soundbar on eARC); legacy-ARC routes silently downmix to stereo. The engine cannot tell the two apart from the route (AE#794).
     public var audioBridgeMode: AudioBridgeMode
 
     /// TrueHD Atmos and DTS:X delivery (#731). `.off` (default) keeps `audioBridgeMode`'s 7.1 channel
diff --git a/docs/formats.md b/docs/formats.md
index f238f0106..142e9dcc3 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -274,8 +274,10 @@ The label can also be taken back from the item itself, where the platform has no
 
 Non-streamable codecs route through `AudioBridge` in one of two modes (`LoadOptions.audioBridgeMode`):
 
-- **`.surroundCompat`** (default): the encoder is chosen per source, not per mode. A source with more than two channels is re-encoded to lossy EAC3 at 128 kbps per channel (768 kbps 5.1). AVPlayer hands the encoded bitstream to HDMI and the sink decodes its own 5.1 mix, so surround works on essentially every modern AVR and soundbar (Sonos Arc, Samsung HW-Q, Bose). Two channels or fewer have no surround to carry and take the FLAC encoder instead, which is lossless where EAC3 would have been 256 kbps lossy, and LPCM the route decodes on the routes that can only pass a Dolby bitstream through (AE#395: an AirPlay 2 optical adapter played one MPEG-TS program's stream-copied AC3 5.1 and was silent on the bridged EAC3 stereo of the same program, so which track `av_find_best_stream` happened to pick decided whether the viewer heard anything).
-- **`.lossless`** (opt-in): FLAC up to 7.1 lossless, which AVPlayer decodes to LPCM. Needs an AVR that accepts multichannel LPCM via HDMI (Denon, Marantz, NAD); on soundbars and basic AVRs that handle multichannel only via bitstream codecs the LPCM gets downmixed to stereo at the route.
+- **`.surroundCompat`** (default): the encoder is chosen per source, not per mode. A source with more than two channels is re-encoded to lossy EAC3 at 128 kbps per channel (768 kbps 5.1). AVPlayer hands the encoded bitstream to HDMI and the sink decodes its own 5.1 mix, so surround works on essentially every AVR and soundbar, including one behind legacy ARC. Two channels or fewer have no surround to carry and take the FLAC encoder instead, which is lossless where EAC3 would have been 256 kbps lossy, and LPCM the route decodes on the routes that can only pass a Dolby bitstream through (AE#395: an AirPlay 2 optical adapter played one MPEG-TS program's stream-copied AC3 5.1 and was silent on the bridged EAC3 stereo of the same program, so which track `av_find_best_stream` happened to pick decided whether the viewer heard anything).
+- **`.lossless`** (opt-in): FLAC up to 7.1 lossless, which AVPlayer decodes to LPCM. Needs a sink that takes multichannel LPCM: an AVR over HDMI, or an AVR or soundbar on eARC (a Sonos Arc on eARC takes 6-channel LPCM, so a 7.1 source arrives as lossless 5.1 there, folded by tvOS). Behind legacy ARC, which carries stereo LPCM or a Dolby bitstream only, the LPCM is downmixed to stereo, and `.surroundCompat` is the right mode.
+
+The engine does not pick between the two from the route (AE#794): with tvOS's Continuous Audio Connection on, every HDMI route reports 32 unlabelled channels whatever the sink takes, so an eARC soundbar and a legacy-ARC one look the same, and a wrong FLAC pick on the second plays stereo. The mode stays the host's choice.
 
 Either encoder opens at a sample rate it actually has, which is not always the source's (AE#548). E-AC-3 exists at 32 / 44.1 / 48 kHz only, so a 96 kHz TrueHD or DTS-HD master is resampled to 48 kHz on the `.surroundCompat` arm; opening the encoder at the source rate instead made `avcodec_open2` refuse the context and took the whole session to silent video-only. The rates come from `avcodec_get_supported_config`, so an FFmpeg bump that widens them needs no change here, and an encoder that advertises no list (FLAC) keeps the source rate untouched, which is what keeps `.lossless` bit-perfect at 96 and 192 kHz. The resampler is in the path on every bridged packet either way, so the conversion costs nothing that was not already being paid.
 

From eb14d795511e7ec7d3bf72e3690c9f00c201ecd9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 23:20:22 +0200
Subject: [PATCH 082/132] fix(engine): the session's still extractor follows
 rotated request headers (#792)

`makeFrameExtractor()` built its extractor from `loadedOptions.httpHeaders`
at the moment the host asked for it, and the extractor opens its
demuxer lazily, on the first scrub and again after an idle close. After
`updateRequestHeaders(_:)` rotated a token, scrub stills on the
software path kept asking with the refused one. The extractor over the
session's own source now reads the session's `RequestHeaderStore` when
it opens, and its demuxer's reader follows the store per request. An
extractor the host builds over its own URL keeps the headers it was
given.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 ++--
 .../AetherEngine+FrameExtractor.swift         |  2 +-
 .../FrameExtractor/FrameDecodeContext.swift   | 18 ++++++++++++-----
 .../FrameExtractor/FrameExtractor.swift       | 10 ++++++++++
 .../LiveRequestHeaderTests.swift              | 20 +++++++++++++++++++
 docs/api.md                                   |  3 ++-
 6 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 23f10cfde..c0faa8ddf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,8 @@ the public-API contract.
 - **A live session's request headers can be replaced without a rebuild (#792).**
   `updateRequestHeaders(_:)` hands the session a new header set, and the next request each of its
   source readers makes carries it: one store per load now feeds the playback demuxer, the producer's
-  reopens and revives, and the I-frame and embedded-subtitle side readers, which used to freeze a copy
-  at their open. A media server whose bearer tokens expire under a long title no longer costs a
+  reopens and revives, the I-frame and embedded-subtitle side readers, and the still extractor
+  `makeFrameExtractor()` returns for the session's source, which used to freeze a copy at their open. A media server whose bearer tokens expire under a long title no longer costs a
   `reloadAtCurrentPosition(applying:)` teardown per rotation, and a reconnect already backing off over
   a lapsed token heals on its next attempt once the host renews. The returned
   `RequestHeaderUpdateOutcome` says `.installedForNextRebuild` where the requests are not the
diff --git a/Sources/AetherEngine/FrameExtractor/AetherEngine+FrameExtractor.swift b/Sources/AetherEngine/FrameExtractor/AetherEngine+FrameExtractor.swift
index b0ed14a0f..bb96ef44e 100644
--- a/Sources/AetherEngine/FrameExtractor/AetherEngine+FrameExtractor.swift
+++ b/Sources/AetherEngine/FrameExtractor/AetherEngine+FrameExtractor.swift
@@ -65,7 +65,7 @@ extension AetherEngine {
         // For a disc image, pin the extractor to the currently-selected title so stills follow the
         // title switch instead of always decoding the default one (AE#105). The host rebuilds the
         // extractor when the disc title changes.
-        return FrameExtractor(url: url, httpHeaders: loadedOptions.httpHeaders,
+        return FrameExtractor(url: url, requestHeaderStore: sessionRequestHeaders,
                               selectTitleID: activeDiscTitleID,
                               yieldWhile: sessionYieldSignal())
     }
diff --git a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
index 4392b6ed5..4f56a8e4b 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
@@ -13,7 +13,11 @@ import AetherLibswscale
 /// NOT thread-safe; FrameExtractor serializes all access on its decode queue.
 final class FrameDecodeContext: @unchecked Sendable {
     private let url: URL
-    private let httpHeaders: [String: String]
+    private let openedHTTPHeaders: [String: String]
+    /// AE#792: the session's live header set for an extractor over the session's own source, so a
+    /// still fetched after a credential rotation carries the current token. Nil otherwise.
+    private let requestHeaderStore: RequestHeaderStore?
+    private var httpHeaders: [String: String] { requestHeaderStore?.current ?? openedHTTPHeaders }
     /// When non-nil, opens from this independent reader (custom source clone) not the URL.
     /// Closed at deinit, NOT in close() (which tears down only demuxer/decoder so the
     /// idle-reopen path can rebuild over the still-alive reader).
@@ -124,9 +128,10 @@ final class FrameDecodeContext: @unchecked Sendable {
     }
 
     init(url: URL, httpHeaders: [String: String], selectTitleID: Int? = nil,
-         allowsHardwareDecode: Bool = false) {
+         allowsHardwareDecode: Bool = false, requestHeaderStore: RequestHeaderStore? = nil) {
         self.url = url
-        self.httpHeaders = httpHeaders
+        self.openedHTTPHeaders = httpHeaders
+        self.requestHeaderStore = requestHeaderStore
         self.reader = nil
         self.formatHint = nil
         self.selectTitleID = selectTitleID
@@ -136,7 +141,8 @@ final class FrameDecodeContext: @unchecked Sendable {
     init(reader: IOReader, formatHint: String?, allowsHardwareDecode: Bool = false) {
         // Placeholder; unused when reader != nil (openInternal opens the reader).
         self.url = URL(string: "aether-custom://frame-extractor")!
-        self.httpHeaders = [:]
+        self.openedHTTPHeaders = [:]
+        self.requestHeaderStore = nil
         self.reader = reader
         self.formatHint = formatHint
         self.selectTitleID = nil
@@ -223,7 +229,9 @@ final class FrameDecodeContext: @unchecked Sendable {
         } else if let reader = reader {
             try demuxer.open(reader: reader, formatHint: formatHint, profile: .stillExtraction)
         } else {
-            try demuxer.open(url: url, extraHeaders: httpHeaders, profile: .stillExtraction, selectTitleID: selectTitleID)
+            try demuxer.open(url: url, extraHeaders: httpHeaders,
+                             profile: DemuxerOpenProfile.stillExtraction.withRequestHeaders(requestHeaderStore),
+                             selectTitleID: selectTitleID)
         }
         self.demuxer = demuxer
 
diff --git a/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift b/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift
index 9e60ee8d8..dd830bb00 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift
@@ -114,6 +114,16 @@ public actor FrameExtractor {
                   yieldWhile: yieldWhile)
     }
 
+    /// AE#792: an extractor over the session's own source, whose requests follow
+    /// `updateRequestHeaders(_:)` like the session's other readers.
+    init(url: URL, requestHeaderStore: RequestHeaderStore, selectTitleID: Int?,
+         yieldWhile: (@Sendable () -> Bool)?) {
+        self.init(context: FrameDecodeContext(url: url, httpHeaders: requestHeaderStore.current,
+                                              selectTitleID: selectTitleID,
+                                              requestHeaderStore: requestHeaderStore),
+                  yieldWhile: yieldWhile)
+    }
+
     /// Construct over a custom `IOReader` source (a clone with its own cursor).
     /// The extractor owns the reader and closes it on teardown.
     public init(reader: IOReader, formatHint: String? = nil,
diff --git a/Tests/AetherEngineTests/LiveRequestHeaderTests.swift b/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
index 24128aa22..02620c6ca 100644
--- a/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
+++ b/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
@@ -96,6 +96,26 @@ struct LiveRequestHeaderTests {
         #expect(origin.requestHeaders.allSatisfy { $0["authorization"] == "Bearer opened" })
     }
 
+    /// The session's still extractor (`makeFrameExtractor()`) opens its demuxer lazily, on the first
+    /// scrub after the extractor was built, and again after an idle close, so it must read the store
+    /// at that moment, not the token current when the host asked for the extractor.
+    @Test("a still extractor over the session's source opens with the rotated headers")
+    func stillExtractorFollowsTheStore() throws {
+        let originMaybe = ThrottledOriginServer(totalSize: 4 * 1024 * 1024)
+        let origin = try #require(originMaybe)
+        defer { origin.stop() }
+        let store = RequestHeaderStore(["Authorization": "Bearer first"])
+        let context = FrameDecodeContext(url: URL(string: "http://127.0.0.1:\(origin.port)/movie.bin")!,
+                                         httpHeaders: store.current, requestHeaderStore: store)
+        defer { context.close() }
+        store.replace(["Authorization": "Bearer second"])
+        // The bytes are not a container, so the open fails after its requests; only their headers matter.
+        try? context.ensureOpen()
+        let sent = origin.requestHeaders.map { $0["authorization"] }
+        #expect(!sent.isEmpty, "the open reached the origin")
+        #expect(sent.allSatisfy { $0 == "Bearer second" })
+    }
+
     @Test("the outcome says live only where every source request is built by the session's readers")
     func outcomeFollowsWhoOwnsTheRequests() {
         func outcome(custom: Bool = false, disc: Bool = false, route: VideoRoute,
diff --git a/docs/api.md b/docs/api.md
index 6fbe94d7d..c7e894c8a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -294,7 +294,8 @@ let outcome = player.updateRequestHeaders(["Authorization": "Bearer \(fresh)"])
 
 The set replaces the session's headers, the way `LoadOptions.httpHeaders` sets them at `load`; it is
 not merged. The session's source readers (the playback demuxer, the producer's reopens and revives,
-the I-frame and embedded-subtitle side readers) read their headers per request from one store the
+the I-frame and embedded-subtitle side readers, and the still extractor `makeFrameExtractor()` returns
+for the session's own source) read their headers per request from one store the
 session creates at `load`, so the next request any of them makes carries the new set. A request
 already in flight finishes with the headers it was sent with. A reconnect already backing off after
 a refusal sends the new set on its next attempt, so a session stalled over a lapsed credential

From 5e78a84fe7cbc3a6beb1d1351371a87d1b044a81 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 23:34:15 +0200
Subject: [PATCH 083/132] feat(engine): a credential refused mid-session is
 typed, short, and heals on renewal (#792)

Part 2 of #792. A 401/403 after the session started was handled as a
dropped connection: twelve unproductive reconnects with the same refused
header (about 80 s), two revives that reopened with it, then
`vodSourceFailed`.

- AVIOReader gives 401/403 a ladder of their own
  (`credentialRefusalMaxStreak` = 2 retries, about 3 s) and stamps the
  refusal on the session's `RequestHeaderStore` with the header revision
  the request was built with. A renewal mid-ladder starts a fresh streak.
- `RequestHeaderStore` carries a revision, the newest refusal, and
  announces the first refusal of each header set.
- `AetherEngine.sourceAuthorizationRefused` publishes that status, so a
  host can renew and call `updateRequestHeaders(_:)` at once.
- HLSVideoEngine's read-error arm never revives with the refused
  header: it waits up to 10 s for a new revision, rebuilds the producer
  when one arrives (`credentialReviveGate`, 3 per session), and otherwise
  surfaces `sourceRefused` with the status. The software path's
  pipeline failure is reclassified the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  14 ++
 .../AetherEngine/AetherEngine+Loading.swift   |   7 +-
 .../AetherEngine+RequestHeaders.swift         |  14 ++
 Sources/AetherEngine/AetherEngine.swift       |  19 +++
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  65 ++++++++-
 .../Demuxer/RequestHeaderStore.swift          |  60 +++++++-
 Sources/AetherEngine/PlaybackErrorInfo.swift  |   4 +-
 .../Video/HLSVideoEngine+LiveReopen.swift     | 103 +++++++++++++-
 .../AetherEngine/Video/HLSVideoEngine.swift   |   3 +
 .../CredentialRefusalTests.swift              | 128 ++++++++++++++++++
 docs/api.md                                   |  24 ++++
 11 files changed, 429 insertions(+), 12 deletions(-)
 create mode 100644 Tests/AetherEngineTests/CredentialRefusalTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c0faa8ddf..53f2f13c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -64,6 +64,20 @@ the public-API contract.
 
 ### Fixed
 
+- **A credential refused mid-session is reported as one, in seconds, and heals when the host renews it
+  (#792).** A 401 or 403 after the session started was handled as a dropped connection: twelve
+  unproductive reconnects with the same refused header (about 80 s of `.stalled(reconnecting: true)`),
+  two revives that reopened with it again, and then `vodSourceFailed` / "Source read failed". The reader
+  now gives a credential refusal a short ladder of its own (about 3 s, the first retry re-resolving an
+  expired signed redirect through the source) and stamps it on the session's header store with the
+  header revision it was sent with. The first refusal of a header set is published on the new
+  `sourceAuthorizationRefused` (the status), so a host can renew and call `updateRequestHeaders(_:)`
+  while the reader is still retrying, which gives it a fresh ladder. Once the reader has given up, the
+  loopback session waits up to 10 s for new headers and rebuilds the producer at the playhead when they
+  arrive (up to three times); otherwise, and on the software path, the session ends with
+  `sourceRefused` and the status as `underlyingCode`. A revive is never spent on the header that was
+  just refused.
+
 - **A TrueHD track started or switched to mid-stream is no longer reported as a dead decoder** (#786,
   thanks @ijuniorfu). TrueHD and MLP decode only from a major sync, so after a start, seek or track
   switch past the opening the decoder skips up to about a hundred 40-frame access units before its
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index ebfd4d224..660e7620b 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -299,7 +299,12 @@ extension AetherEngine {
             .store(in: &cancellables)
         failure
             .compactMap { $0 }
-            .sink { [weak self] info in self?.publishError(info) }
+            .sink { [weak self] info in
+                guard let self else { return }
+                self.publishError(Self.reclassifiedForCredentialRefusal(
+                    info, refusal: self.sessionRequestHeaders.recentCredentialRefusal(
+                        within: HLSVideoEngine.rateLimitVerdictWindowSeconds)))
+            }
             .store(in: &cancellables)
         didReachEnd
             .filter { $0 }
diff --git a/Sources/AetherEngine/AetherEngine+RequestHeaders.swift b/Sources/AetherEngine/AetherEngine+RequestHeaders.swift
index 75548e420..ad218a6ee 100644
--- a/Sources/AetherEngine/AetherEngine+RequestHeaders.swift
+++ b/Sources/AetherEngine/AetherEngine+RequestHeaders.swift
@@ -60,6 +60,20 @@ extension AetherEngine {
     }
 }
 
+extension AetherEngine {
+    /// AE#792 part 2: the software path reports a source that stopped answering as a pipeline
+    /// failure. When the reader's last answer was a credential refusal, that is what the host is
+    /// told, with the status, the way an open-time 401 already arrives.
+    nonisolated static func reclassifiedForCredentialRefusal(
+        _ info: PlaybackErrorInfo, refusal: RequestHeaderStore.CredentialRefusal?
+    ) -> PlaybackErrorInfo {
+        guard info.kind == .softwarePipelineFailed, let refusal else { return info }
+        return PlaybackErrorInfo(kind: .sourceRefused,
+                                 message: "Source refused the session's credentials (HTTP \(refusal.status))",
+                                 underlyingCode: refusal.status)
+    }
+}
+
 /// What `updateRequestHeaders(_:)` did (AE#792).
 public enum RequestHeaderUpdateOutcome: Sendable, Equatable {
     /// The session's source readers send the new set on their next request, a reconnect already
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index f22cd274a..3f855ee65 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -149,6 +149,16 @@ public final class AetherEngine: ObservableObject {
 
     private let seekEventSubject = PassthroughSubject<SeekEvent, Never>()
 
+    /// AE#792: the origin refused the session's credentials mid-session. One value per header set,
+    /// the HTTP status (401 or 403), sent on the first refusal of that set, so a host can renew a
+    /// lapsed or revoked token and hand it over with `updateRequestHeaders(_:)` while the reader is
+    /// still retrying. See `updateRequestHeaders(_:)` for what happens if it does not.
+    public var sourceAuthorizationRefused: AnyPublisher<Int, Never> {
+        sourceAuthorizationRefusedSubject.eraseToAnyPublisher()
+    }
+
+    let sourceAuthorizationRefusedSubject = PassthroughSubject<Int, Never>()
+
     /// Monotonic id source for `SeekEvent`. Deliberately NOT `seekGeneration`: that counter is the
     /// supersede fence every in-flight finalize checks itself against, so a rejected or stashed seek must
     /// not be able to move it (it would make a live seek believe it lost and return without finalizing).
@@ -4205,6 +4215,15 @@ public final class AetherEngine: ObservableObject {
         // AE#792: a fresh store per load, so a header rotated on the previous session can never reach
         // this one through a reader that outlived it.
         sessionRequestHeaders = RequestHeaderStore(options.httpHeaders)
+        let refusalStore = sessionRequestHeaders
+        refusalStore.onCredentialRefusal = { [weak self] status in
+            Task { @MainActor [weak self] in
+                guard let self, self.sessionRequestHeaders === refusalStore else { return }
+                EngineLog.emit("[AetherEngine] AE#792: source refused the request headers (HTTP \(status))",
+                               category: .engine)
+                self.sourceAuthorizationRefusedSubject.send(status)
+            }
+        }
         audioSessionRequestsOwnedByAVFoundation = false
         // #377: register the host's concurrency ceiling for this origin before anything fetches
         // from it. Keyed on the origin rather than the load, so the subtitle side reader and any
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 831ddfa3a..d2635a77c 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -400,6 +400,15 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return status == 429 || status == 503 || status == 509
     }
 
+    /// AE#792 part 2: the origin refused the request's credentials. An identical request carrying
+    /// the identical credential cannot succeed, so these get a short ladder of their own instead of
+    /// the twelve unproductive reconnects a dropped connection is given, and the refusal is stamped
+    /// on the session's header store so the engine can tell "the token lapsed" from "the source is
+    /// gone".
+    static func isCredentialRefusalStatus(_ status: Int) -> Bool {
+        return status == 401 || status == 403
+    }
+
     /// Hard server errors answered by a pinned post-redirect URL: the redirect target
     /// may be dead or expired while the source URL would mint a fresh one. Rate-limit
     /// statuses are excluded — the origin is metering us, and the pin is not the
@@ -767,6 +776,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     // Connection state.
     private var connEnded = false
     private var connStatus = 0
+    // AE#792: the header store's revision when the current generation's request was built.
+    private var connHeaderRevision: UInt64 = 0
     // Retry-After seconds from a rate-limit status, honoured before reconnect.
     private var connRetryAfter: TimeInterval = 0
     // Bumped on every (re)connect; stale delegate callbacks are ignored.
@@ -958,6 +969,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private var bytesAtLastReconnect: Int64 = 0
     // Consecutive rate-limited attempts; survives seekReconnect, resets on real read progress (#71).
     private var rateLimitStreak = 0
+    // AE#792: consecutive 401/403 ends on one credential. Survives seekReconnect like the rate-limit
+    // streak, resets on real read progress and whenever the header store's revision moves.
+    private var credentialRefusalStreak = 0
+    private var credentialStreakRevision: UInt64?
 
     /// Detour LRU block cache (its own leaf lock, never held across `fetchChunk`/network or
     /// `winCond`). Stores only full-size blocks; short bodies are served once but never cached
@@ -2427,6 +2442,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 if connFirstDataSeen {
                     unproductiveReconnects = 0      // real progress
                     rateLimitStreak = 0             // real progress clears the 429 give-up streak (#71)
+                    credentialRefusalStreak = 0     // and the credential one (#792)
                     emitNetworkPhase(.flowing)      // recovered: source delivering again (#85/#410)
                 }
                 // No flow installed and the consumer has drawn down to low water: request at the
@@ -2566,10 +2582,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             // rate-limit streak, which (unlike unproductiveReconnects) survives the seekReconnect
             // that parse seeks fire, so a throttled origin fails cleanly instead of looping (#71).
             let isRateLimited = Self.isRateLimitStatus(status)
+            let isCredentialRefusal = Self.isCredentialRefusalStatus(status)
             let giveUp = isRateLimited ? recordRateLimitAndShouldGiveUp()
-                                       : recordReconnectAndShouldGiveUp(status: status)
+                : isCredentialRefusal ? recordCredentialRefusalAndShouldGiveUp()
+                : recordReconnectAndShouldGiveUp(status: status)
             if giveUp {
-                let streakDesc = isRateLimited ? "\(rateLimitStreak) consecutive rate-limited" : "\(unproductiveReconnects) unproductive"
+                let streakDesc = isRateLimited ? "\(rateLimitStreak) consecutive rate-limited"
+                    : isCredentialRefusal ? "\(credentialRefusalStreak) consecutive credential refusals"
+                    : "\(unproductiveReconnects) unproductive"
                 EngineLog.emit("[AVIOReader] \(label) reconnect exhausted at offset \(frontier) status=\(status) (\(streakDesc))\(isLive ? " [live source lost]" : "")", category: .demux)
                 emitNetworkPhase(.exhausted)   // ladder spent; the reopen owns recovery, the source is still down (#410)
                 if isLive {
@@ -2577,11 +2597,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 }
                 return totalRead > 0 ? Int32(totalRead) : -1
             }
-            let backoffStreak = isRateLimited ? rateLimitStreak : unproductiveReconnects
+            let backoffStreak = isRateLimited ? rateLimitStreak
+                : isCredentialRefusal ? credentialRefusalStreak : unproductiveReconnects
             EngineLog.emit("[AVIOReader] \(label) conn ended at offset \(frontier) status=\(status), reconnecting (streak=\(backoffStreak) retryAfter=\(retryAfter)s)", category: .demux)
             lastUnplannedReconnectAt = Date()
             emitNetworkPhase(.reconnecting)   // unplanned reconnect now in flight (#85)
-            let repinned = dropPinIfTheRefusalCallsForIt(isRateLimited: isRateLimited)
+            // A credential refusal already dropped the pin where the status was read (an expired
+            // signed redirect target answers 401/403 too), and its streak is not the unproductive one.
+            let repinned = isCredentialRefusal ? false : dropPinIfTheRefusalCallsForIt(isRateLimited: isRateLimited)
             let backoffStart = DispatchTime.now()
             // #392: a pin dropped for idleness sends this attempt to the SOURCE, which has refused
             // nothing, so the exponential pacing charged against the target that did refuse is not
@@ -2730,8 +2753,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private func chargeFaultedRunwayRefill(at frontier: Int64, ahead: Int,
                                            status: Int, retryAfter: TimeInterval) -> Bool {
         let isRateLimited = Self.isRateLimitStatus(status)
+        let isCredentialRefusal = Self.isCredentialRefusalStatus(status)
         let giveUp = isRateLimited ? recordRateLimitAndShouldGiveUp()
-                                   : recordReconnectAndShouldGiveUp(status: status)
+            : isCredentialRefusal ? recordCredentialRefusalAndShouldGiveUp()
+            : recordReconnectAndShouldGiveUp(status: status)
         if giveUp {
             winCond.lock()
             nextFaultedRefillAt = .distantFuture
@@ -2742,8 +2767,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 category: .demux)
             return false
         }
-        let streak = isRateLimited ? rateLimitStreak : unproductiveReconnects
-        let repinned = dropPinIfTheRefusalCallsForIt(isRateLimited: isRateLimited)
+        let streak = isRateLimited ? rateLimitStreak
+            : isCredentialRefusal ? credentialRefusalStreak : unproductiveReconnects
+        let repinned = isCredentialRefusal ? false : dropPinIfTheRefusalCallsForIt(isRateLimited: isRateLimited)
         lastUnplannedReconnectAt = Date()
         let delay = backoffDelay(streak: repinned ? 0 : streak, retryAfter: retryAfter)
         winCond.lock()
@@ -2779,6 +2805,25 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return rateLimitStreak > Self.rateLimitMaxStreak
     }
 
+    /// AE#792: charges one 401/403 end; true once `credentialRefusalMaxStreak` attempts on one
+    /// credential were refused. A host that replaced the headers since the last refusal starts a
+    /// fresh streak, so a renewal arriving mid-ladder is always tried. Demux-thread-only.
+    func recordCredentialRefusalAndShouldGiveUp() -> Bool {
+        let revision = requestHeaderStore?.revision
+        if revision != credentialStreakRevision {
+            credentialRefusalStreak = 0
+            credentialStreakRevision = revision
+        }
+        credentialRefusalStreak += 1
+        return credentialRefusalStreak > Self.credentialRefusalMaxStreak
+    }
+
+    /// Two retries after the first refusal: the first goes out right after the pin was dropped, so
+    /// an expired signed redirect is re-resolved through the source, and the second gives a host
+    /// that renews on `sourceAuthorizationRefused` a moment to do so. About 3 s with the backoff,
+    /// against roughly 80 s on the unproductive ladder.
+    static let credentialRefusalMaxStreak = 2
+
     // MARK: - Detour Block Cache (AetherEngine#69)
 
     /// `fetched` says whether the served bytes crossed the network. The callers charge the
@@ -3223,6 +3268,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         winCond.lock()
         connGeneration &+= 1
         let generation = connGeneration
+        connHeaderRevision = requestHeaderStore?.revision ?? 0
         // #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
@@ -3683,10 +3729,12 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                               respondedBy: respondedBy)
         }
         var headerMs: Double? = nil
+        var sentRevision: UInt64? = nil
         winCond.lock()
         if generation == connGeneration {
             connStatus = status
             connRetryAfter = retryAfter
+            sentRevision = connHeaderRevision
             // #93/#96 residual: time-to-first-response-header for this generation. A large value here
             // with a small subsequent first-data gap points at server-side connection queuing (the
             // origin accepted the socket but withheld the response while it served another connection
@@ -3755,6 +3803,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 category: .demux
             )
         }
+        if let sentRevision, Self.isCredentialRefusalStatus(status), let requestHeaderStore {
+            requestHeaderStore.noteCredentialRefusal(status: status, revision: sentRevision)
+        }
         // #331: name the latch once. A field capture that shows the reconnect shape change is the
         // difference between "the origin has no byte addresses" and "the reconnect is broken".
         if latchedJoinShape {
diff --git a/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift b/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift
index 3fb9d8e28..b4be93826 100644
--- a/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift
+++ b/Sources/AetherEngine/Demuxer/RequestHeaderStore.swift
@@ -16,6 +16,26 @@ import Foundation
 final class RequestHeaderStore: @unchecked Sendable {
     private let lock = NSLock()
     private var value: [String: String]
+    private var revisionValue: UInt64 = 0
+    private var refusal: CredentialRefusal?
+    private var announcedRevision: UInt64?
+
+    /// AE#792 part 2: the origin answered 401 or 403 to a request this store's headers went out on.
+    /// `revision` is the store's revision when that request was built, so a later look can tell a
+    /// refusal of the current credential from one the host has already replaced.
+    struct CredentialRefusal: Equatable, Sendable {
+        let status: Int
+        let revision: UInt64
+        let at: Date
+    }
+
+    /// Called once per revision, on the first credential refusal of that revision, from the reader's
+    /// thread. The engine forwards it to `sourceAuthorizationRefused`.
+    var onCredentialRefusal: (@Sendable (Int) -> Void)? {
+        get { lock.withLock { onRefusal } }
+        set { lock.withLock { onRefusal = newValue } }
+    }
+    private var onRefusal: (@Sendable (Int) -> Void)?
 
     init(_ headers: [String: String]) {
         value = headers
@@ -25,7 +45,45 @@ final class RequestHeaderStore: @unchecked Sendable {
         lock.withLock { value }
     }
 
+    /// Bumped by every `replace`, so a reader can stamp what it sent and the revive arm can ask
+    /// whether the credential moved since.
+    var revision: UInt64 {
+        lock.withLock { revisionValue }
+    }
+
     func replace(_ headers: [String: String]) {
-        lock.withLock { value = headers }
+        lock.withLock {
+            value = headers
+            revisionValue &+= 1
+        }
+    }
+
+    /// Records a 401/403 the origin answered to headers of `revision`. Only the newest revision's
+    /// refusal is kept: a late answer to a credential already replaced says nothing about the
+    /// current one.
+    func noteCredentialRefusal(status: Int, revision: UInt64, at instant: Date = Date()) {
+        let callback: (@Sendable (Int) -> Void)?
+        lock.lock()
+        if let kept = refusal, kept.revision > revision {
+            lock.unlock()
+            return
+        }
+        refusal = CredentialRefusal(status: status, revision: revision, at: instant)
+        if announcedRevision != revision {
+            announcedRevision = revision
+            callback = onRefusal
+        } else {
+            callback = nil
+        }
+        lock.unlock()
+        callback?(status)
+    }
+
+    /// The last credential refusal, when it happened within `window` of `now`.
+    func recentCredentialRefusal(within window: TimeInterval, now: Date = Date()) -> CredentialRefusal? {
+        lock.withLock {
+            guard let refusal, now.timeIntervalSince(refusal.at) <= window else { return nil }
+            return refusal
+        }
     }
 }
diff --git a/Sources/AetherEngine/PlaybackErrorInfo.swift b/Sources/AetherEngine/PlaybackErrorInfo.swift
index d36d34491..d29b304ce 100644
--- a/Sources/AetherEngine/PlaybackErrorInfo.swift
+++ b/Sources/AetherEngine/PlaybackErrorInfo.swift
@@ -21,7 +21,9 @@ public struct PlaybackErrorKind: RawRepresentable, Sendable, Equatable, Hashable
     /// a 404, a 5xx. `underlyingCode` is that status; `underlyingDomain` is nil, the sentence is the
     /// engine's. Before this kind existed both this and a corrupt file arrived as `sourceOpenFailed`
     /// carrying FFmpeg's "Invalid data found when processing input". A 429/503/509 arrives as
-    /// `sourceRateLimited` instead: same shape, different recovery.
+    /// `sourceRateLimited` instead: same shape, different recovery. Mid-session, a 401/403 that the
+    /// host did not answer with new headers in time arrives as this kind too (AE#792), where it used to
+    /// arrive as `vodSourceFailed`.
     public static let sourceRefused = PlaybackErrorKind(rawValue: "sourceRefused")
     /// The transport was refused over certificate trust before any media arrived: a self-signed or
     /// private-CA origin, an expired certificate, a client certificate the process cannot present.
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index cb1ca822c..2fb6580bf 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -333,7 +333,7 @@ extension HLSVideoEngine {
                     + "revive cannot resume at an offset, surfacing source failure",
                     category: .session
                 )
-                surfaceVODSourceFailure(code, "Source read failed")
+                surfaceReadFailure(code)
             } else if Self.shouldReviveVODAfterReadError(
                 isLive: isLiveSession,
                 packetsWritten: prod.packetsWrittenCount,
@@ -346,7 +346,7 @@ extension HLSVideoEngine {
                     + "(readError \(code)); surfacing fatal source failure",
                     category: .session
                 )
-                surfaceVODSourceFailure(code, "Source read failed")
+                surfaceReadFailure(code)
             }
             return
         }
@@ -508,6 +508,12 @@ extension HLSVideoEngine {
         // reopening from byte 0 against an origin that is refusing precisely that, and then
         // declares the source "not readable in this session" while the same stream plays instantly
         // if the user backs out and presses play. That verdict is not just unhelpful, it is false.
+        // AE#792 part 2: a refused credential is neither metering nor a lost source. Reviving with the
+        // header that was just refused cannot succeed; reviving after the host renewed it is the heal.
+        if let refusal = requestHeaders.recentCredentialRefusal(within: Self.rateLimitVerdictWindowSeconds) {
+            handleCredentialRefusedReadError(code, refusal: refusal, deadProducer: deadProducer)
+            return
+        }
         let metered = OriginRequestBudget.shared.refusedRecently(
             sourceURL, within: Self.rateLimitVerdictWindowSeconds)
 
@@ -594,6 +600,99 @@ extension HLSVideoEngine {
         }
     }
 
+    /// AE#792 part 2: what a read error over a refused credential calls for. The store's revision says
+    /// whether the host replaced the headers since the refused request was built.
+    enum CredentialRefusalPlan: Equatable { case revive, awaitRenewal }
+
+    static func credentialRefusalPlan(refusedRevision: UInt64, currentRevision: UInt64) -> CredentialRefusalPlan {
+        currentRevision != refusedRevision ? .revive : .awaitRenewal
+    }
+
+    /// How long a session stalled on a refused credential waits for the host to renew it before the
+    /// refusal is published. The host learns of the refusal from `sourceAuthorizationRefused` at the
+    /// first 401/403, so this only has to cover a token refresh, not a user.
+    static let credentialRenewalGraceSeconds: TimeInterval = 10
+
+    func handleCredentialRefusedReadError(_ code: Int32, refusal: RequestHeaderStore.CredentialRefusal,
+                                          deadProducer: HLSSegmentProducer?) {
+        let store = requestHeaders
+        guard Self.credentialRefusalPlan(refusedRevision: refusal.revision,
+                                         currentRevision: store.revision) == .awaitRenewal else {
+            reviveAfterCredentialRenewal(refusal: refusal)
+            return
+        }
+        onNetworkPhaseChanged?(.reconnecting)
+        EngineLog.emit(
+            "[HLSVideoEngine] #792 VOD pump died on a refused credential (HTTP \(refusal.status), readError "
+            + "\(code)); waiting up to \(Int(Self.credentialRenewalGraceSeconds))s for new request headers",
+            category: .session)
+        let sessionEpoch = sessionEpochSnapshot()
+        BlockingWork.detached(priority: .userInitiated) { [weak self, weak deadProducer] in
+            let deadline = Date().addingTimeInterval(Self.credentialRenewalGraceSeconds)
+            while Date() < deadline, store.revision == refusal.revision {
+                try? await Task.sleep(nanoseconds: 250_000_000)
+            }
+            guard let self else { return }
+            guard Self.meteredReviveStillOwed(sessionUnchanged: self.isSessionEpochCurrent(sessionEpoch),
+                                              deadProducerInstalled: self.currentProducerIs(deadProducer)) else {
+                EngineLog.emit(
+                    "[HLSVideoEngine] #792 credential wait ended: the dead producer was already replaced "
+                    + "or the session stopped", category: .session)
+                return
+            }
+            if store.revision != refusal.revision {
+                self.reviveAfterCredentialRenewal(refusal: refusal)
+            } else {
+                EngineLog.emit(
+                    "[HLSVideoEngine] #792 no new request headers within "
+                    + "\(Int(Self.credentialRenewalGraceSeconds))s; publishing the refusal",
+                    category: .session)
+                self.surfaceCredentialRefusal(refusal)
+            }
+        }
+    }
+
+    private func reviveAfterCredentialRenewal(refusal: RequestHeaderStore.CredentialRefusal) {
+        restartLock.lock()
+        let admitted = credentialReviveGate.admit()
+        let attempts = credentialReviveGate.attempts
+        if admitted { mainDemuxerSuspectDead = true }
+        restartLock.unlock()
+        guard admitted else {
+            EngineLog.emit(
+                "[HLSVideoEngine] #792 renewed credentials refused again after \(attempts - 1) revives; "
+                + "publishing the refusal", category: .session)
+            surfaceCredentialRefusal(refusal)
+            return
+        }
+        let frozen = currentPlaybackPositionProvider?() ?? 0
+        let anchor = AetherEngine.recoveryAnchorPosition(
+            frozenPosition: frozen, pendingSeekTarget: recoverySeekTargetProvider?(),
+            currentRendered: frozen)
+        let idx = segmentIndexForPlaylistTime(anchor)
+        EngineLog.emit(
+            "[HLSVideoEngine] #792 request headers renewed after HTTP \(refusal.status); rebuilding the "
+            + "producer at \(String(format: "%.2f", anchor))s -> seg\(idx) "
+            + "(attempt \(attempts)/\(credentialReviveGate.maxAttempts))", category: .session)
+        requestRestart(at: idx, authoritative: true)
+    }
+
+    func surfaceCredentialRefusal(_ refusal: RequestHeaderStore.CredentialRefusal) {
+        surfaceVODSourceFailure(Int32(refusal.status),
+                                "Source refused the session's credentials (HTTP \(refusal.status))",
+                                kind: .sourceRefused)
+    }
+
+    /// The read-error surfaces that have no revive left: typed as a refusal when the reader's last
+    /// answer was one, the generic source failure otherwise.
+    func surfaceReadFailure(_ code: Int32) {
+        if let refusal = requestHeaders.recentCredentialRefusal(within: Self.rateLimitVerdictWindowSeconds) {
+            surfaceCredentialRefusal(refusal)
+            return
+        }
+        surfaceVODSourceFailure(code, "Source read failed")
+    }
+
     /// 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 {
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index d1596fcfd..2f2e3c553 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -877,6 +877,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// See `RefusingSourceReviveBudget` for why: the old figure was the emergent product of two
     /// constants that did not know about each other, and it was never reset.
     var rateLimitReviveGate = RefusingSourceReviveBudget()
+    /// AE#792 part 2: revives spent on a credential refusal the host has since renewed. Each one
+    /// answers a renewal, so the bound only stops a host whose fresh credentials keep being refused.
+    var credentialReviveGate = MuxerFailureReviveGate(maxAttempts: 3)
 
     /// AE#169 round 2 (under `restartLock`): the demuxer's last read threw, so the next
     /// performRestart replaces it via the #79 fresh-demuxer path instead of seeking a connection
diff --git a/Tests/AetherEngineTests/CredentialRefusalTests.swift b/Tests/AetherEngineTests/CredentialRefusalTests.swift
new file mode 100644
index 000000000..fc8a0f03e
--- /dev/null
+++ b/Tests/AetherEngineTests/CredentialRefusalTests.swift
@@ -0,0 +1,128 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// AE#792 part 2: a credential the origin refuses mid-session is told apart from a lost source. The
+/// reader gives it a short ladder and stamps it on the session's header store, the store announces
+/// it once per header set, and the engine revives only after the host replaced the headers.
+@Suite("Credential refusal", .serialized, .offCooperativePool)
+struct CredentialRefusalTests {
+
+    // MARK: - Store
+
+    @Test("replace bumps the revision")
+    func revisionMoves() {
+        let store = RequestHeaderStore(["Authorization": "Bearer a"])
+        #expect(store.revision == 0)
+        store.replace(["Authorization": "Bearer b"])
+        #expect(store.revision == 1)
+    }
+
+    @Test("a refusal is announced once per revision, and a stale one does not replace a newer")
+    func refusalAnnouncedOncePerRevision() {
+        let store = RequestHeaderStore(["Authorization": "Bearer a"])
+        let seen = Seen()
+        store.onCredentialRefusal = { seen.add($0) }
+        store.noteCredentialRefusal(status: 401, revision: 0)
+        store.noteCredentialRefusal(status: 401, revision: 0)
+        #expect(seen.values == [401])
+        store.replace(["Authorization": "Bearer b"])
+        store.noteCredentialRefusal(status: 403, revision: 1)
+        #expect(seen.values == [401, 403])
+        // A late answer to the replaced credential says nothing about the current one.
+        store.noteCredentialRefusal(status: 401, revision: 0)
+        #expect(store.recentCredentialRefusal(within: 60)?.revision == 1)
+        #expect(store.recentCredentialRefusal(within: 60)?.status == 403)
+        #expect(seen.values == [401, 403])
+    }
+
+    @Test("a refusal older than the window is not recent")
+    func refusalWindow() {
+        let store = RequestHeaderStore([:])
+        store.noteCredentialRefusal(status: 401, revision: 0, at: Date().addingTimeInterval(-120))
+        #expect(store.recentCredentialRefusal(within: 60) == nil)
+        #expect(store.recentCredentialRefusal(within: 600)?.status == 401)
+    }
+
+    // MARK: - Engine decisions
+
+    @Test("revive only once the headers moved past the refused revision")
+    func revivePlan() {
+        #expect(HLSVideoEngine.credentialRefusalPlan(refusedRevision: 3, currentRevision: 3) == .awaitRenewal)
+        #expect(HLSVideoEngine.credentialRefusalPlan(refusedRevision: 3, currentRevision: 4) == .revive)
+    }
+
+    @Test("a software pipeline failure over a refused credential reaches the host as sourceRefused")
+    func softwareFailureReclassified() {
+        let failed = PlaybackErrorInfo(kind: .softwarePipelineFailed, message: "read failed")
+        let refusal = RequestHeaderStore.CredentialRefusal(status: 401, revision: 0, at: Date())
+        let typed = AetherEngine.reclassifiedForCredentialRefusal(failed, refusal: refusal)
+        #expect(typed.kind == .sourceRefused)
+        #expect(typed.underlyingCode == 401)
+        #expect(AetherEngine.reclassifiedForCredentialRefusal(failed, refusal: nil).kind == .softwarePipelineFailed)
+        let other = PlaybackErrorInfo(kind: .nativeItemFailed, message: "x")
+        #expect(AetherEngine.reclassifiedForCredentialRefusal(other, refusal: refusal).kind == .nativeItemFailed)
+    }
+
+    // MARK: - Reader
+
+    /// The origin serves the opening range and refuses every request past it with 401, whatever
+    /// the token. The unproductive ladder spent about 80 s on this; the credential ladder gives up
+    /// after its third refusal, a few seconds in, with the refusal on the store.
+    @Test("a reader refused 401 mid-stream gives up in seconds and stamps the store",
+          .timeLimit(.minutes(1)))
+    func refusedReaderGivesUpQuickly() async throws {
+        let firstRange: Int64 = 256 * 1024
+        let originMaybe = ThrottledOriginServer(totalSize: 64 * 1024 * 1024, respond: { _, offset, _ in
+            offset < firstRange ? .serve206 : .status(401)
+        })
+        let origin = try #require(originMaybe)
+        defer { origin.stop() }
+
+        let store = RequestHeaderStore(["Authorization": "Bearer lapsed"])
+        let seen = Seen()
+        store.onCredentialRefusal = { seen.add($0) }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(origin.port)/movie.bin")!,
+                                extraHeaders: store.current, boundedInitialFetch: firstRange,
+                                requestHeaderStore: store)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let started = Date()
+        let result = Result()
+        Thread.detachNewThread {
+            let cap = 128 * 1024
+            let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: cap)
+            defer { buf.deallocate() }
+            var got = 0
+            var last: Int32 = 0
+            while got < Int(firstRange) + 1024 * 1024 {
+                last = reader.read(into: buf, size: Int32(cap))
+                if last <= 0 { break }
+                got += Int(last)
+            }
+            result.finish(last)
+        }
+        try await waitFor { result.code != nil }
+        let elapsed = Date().timeIntervalSince(started)
+        #expect((result.code ?? 0) < 0, "the read failed instead of delivering")
+        #expect(elapsed < 15, "gave up after \(elapsed)s; the unproductive ladder takes about 80 s")
+        #expect(store.recentCredentialRefusal(within: 60)?.status == 401)
+        #expect(store.recentCredentialRefusal(within: 60)?.revision == 0)
+        #expect(seen.values == [401], "announced once for the one header set")
+    }
+
+    final class Seen: @unchecked Sendable {
+        private let lock = NSLock()
+        private var list: [Int] = []
+        func add(_ v: Int) { lock.withLock { list.append(v) } }
+        var values: [Int] { lock.withLock { list } }
+    }
+
+    final class Result: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value: Int32?
+        func finish(_ v: Int32) { lock.withLock { value = v } }
+        var code: Int32? { lock.withLock { value } }
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index c7e894c8a..96d51a557 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -313,6 +313,29 @@ The call returns a `RequestHeaderUpdateOutcome`:
 | `.installedForNextRebuild` | the requests are made by something that fixed its headers when the session was built: AVFoundation on `.remoteBypass` or an AVPlayer-hosted audio item, a custom `IOReader` the host built, a remote disc image. Call `reloadAtCurrentPosition()` if the set is needed now. |
 | `.noActiveSession` | nothing is loaded; nothing was installed. |
 
+**When the credential lapses anyway.** A 401 or 403 mid-session is not treated as a dropped
+connection. The reader gives it a short ladder of its own (the refused request, then two retries, about
+3 s; the first retry re-resolves an expired signed redirect through the source), where the twelve
+unproductive reconnects used to take about 80 s with the same refused header. The first refusal of a
+header set is published on `sourceAuthorizationRefused` (`AnyPublisher<Int, Never>`, the status), so a
+host can renew right away instead of waiting on a timer derived from the token's expiry, which does not
+cover a token an admin revoked early. A renewal that arrives while the reader is still retrying gives it
+a fresh ladder. Once the reader has given up, the native loopback session waits up to 10 s for new
+headers: a renewal within that time rebuilds the producer at the playhead (up to three times per
+session), and otherwise the session ends with `PlaybackErrorKind.sourceRefused` and the status as
+`underlyingCode`, not `vodSourceFailed`. The software path has no producer to rebuild and reports the
+same `sourceRefused` when its reader's last answer was a refusal.
+
+```swift
+player.sourceAuthorizationRefused
+    .sink { _ in
+        Task { @MainActor in
+            if let fresh = try? await auth.renewedHeaders() { player.updateRequestHeaders(fresh) }
+        }
+    }
+    .store(in: &cancellables)
+```
+
 The log names the header names it replaced, never their values.
 
 ### Overriding the decode path
@@ -735,6 +758,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$errorInfo` | `PlaybackErrorInfo?`, the machine-readable half of `.error`: a `PlaybackErrorKind` token, plus the underlying `NSError` domain and code where one is involved. Non-nil exactly while `state` is `.error`, assigned before it. Classify on this, never on the message. |
 | `$playbackPhase` | The derived one-source-of-truth status, and **the only one of these that tracks motion**: `state` is transport INTENT and turns `.playing` the moment the engine has called `play()`, which on a live join can be seconds before the rate rolls (AE#440). Until the transport has moved once in a load, the phase stays `.loading`, and it turns `.playing` on the roll itself. Adds `.rebuffering` and `.stalled(reconnecting:)`. Prefer it over stitching `state` + `isBuffering` + `isSeeking`, and over matching log text. Precedence, highest first: `error > ended > idle > loading > stalled > seeking > rebuffering > playing/paused` - a source that stopped delivering stays visible while a seek is in flight, because no seek can land over it and `isSeeking` / `seekEvents` still carry the seek (#410). `.stalled(reconnecting: true)` is a reader that is retrying, `false` a reader whose ladder is spent and whose recovery has passed to the producer's reopen; both mean the source is down. `.rebuffering` is published on the AVPlayer-backed paths: the native loopback session, direct remote HLS, and the bare-AVPlayer audio host (a starved progressive stream, once the item has played), where `.stalled` cannot occur because there is no reader. The FFmpeg-backed hosts (software video, FFmpeg audio) have no AVPlayer to wait, so a starving source reads as `.stalled` there instead. |
 | `$isBuffering`, `$isSeeking`, `$seekTarget` | The raw axes `playbackPhase` folds. |
+| `sourceAuthorizationRefused` | `AnyPublisher<Int, Never>`: the origin answered 401 or 403 to the session's request headers mid-session; one value per header set, the status. Renew and call `updateRequestHeaders(_:)`; see [Rotating a credential without a rebuild](#rotating-a-credential-without-a-rebuild). |
 | `seekEvents` | `AnyPublisher<SeekEvent, Never>`: `.began`, `.landed(renderedTime:)`, `.stalled`, `.superseded`, `.rejected(SeekEvent.Rejection)`, each with its `target`, an `id` that spans the seek, and a `SeekEvent.Origin` (`.programmatic`, `.nativeScrub`, `.deferred`; a deferred seek is one the session could not take yet, which is where the engine publishes an optimistic `currentTime` for a position nothing has reached). Use it where the falling edge of `$isSeeking` matters: a level cannot say whether a seek landed, gave up, or was superseded, and a `.stalled` seek can still land later under the same id. |
 | `$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). |

From a3db0d7559da85542a974415ab59697e9faa6d08 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 23:37:08 +0200
Subject: [PATCH 084/132] chore(release): prep 7.37.0 - request headers rotate
 without a rebuild, Profile 7 FEL as Dolby Vision, VIDEO_TS folders over HTTP

Also files the CHANGELOG entries for TrackInfo.isDTSX and the #794
lossless-bridge wording.

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 53f2f13c8..8bca37f58 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,8 +10,16 @@ the public-API contract.
 
 ## [Unreleased]
 
+## [7.37.0] - 2026-10-15
+
 ### Added
 
+- **`TrackInfo.isDTSX`.** Set from libavcodec's DTS:X profiles ("DTS-HD MA + DTS:X", "... IMAX") at
+  probe time, and once LibDTSX confirms, while `objectAudioRendering` plays it, a track FFmpeg labelled
+  plain DTS-HD MA (FFmpeg reads only two of DTS:X's markers). The confirmation is kept per source like a
+  confirmed JOC flag, survives a track or title switch, and republishes `audioTracks`. Hosts can name a
+  DTS:X track the way they name TrueHD Atmos without parsing the profile string.
+
 - **A live session's request headers can be replaced without a rebuild (#792).**
   `updateRequestHeaders(_:)` hands the session a new header set, and the next request each of its
   source readers makes carries it: one store per load now feeds the playback demuxer, the producer's
@@ -46,6 +54,13 @@ the public-API contract.
 
 ### Changed
 
+- **The lossless bridge's documentation and route warning name the sinks it is for (#794).** An eARC
+  soundbar takes multichannel LPCM (measured: a Sonos Arc takes 6 channels, so `.lossless` reaches it as
+  lossless 5.1 where `.surroundCompat` gives lossy 5.1); only a sink behind legacy ARC needs E-AC-3. The
+  FLAC route warning no longer says soundbars take multichannel only as a bitstream. The engine still
+  does not pick the mode from the route: with tvOS's Continuous Audio Connection on, every HDMI route
+  reports 32 unlabelled channels whatever the sink takes.
+
 - **Dolby Vision Profile 7: a packet whose only NALs are a refused RPU and its EL now reports the
   conversion as failed** (#767, thanks @pkajaba). The packet is left as it was, as before; the result used
   to say success, which hid the dropped RPU from the one-shot conversion log and from `aetherctl dovitest`.
diff --git a/Examples/README.md b/Examples/README.md
index c3fd89188..5d93f9d34 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.36.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.37.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 4f811f947..f25a49f43 100644
--- a/README.md
+++ b/README.md
@@ -386,7 +386,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.36.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.37.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -633,10 +633,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.36.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.37.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.36.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.37.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 f2a58fea3..76762277d 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.36.0"
+    public nonisolated static let version = "7.37.0"
 }

From e1e9ac3237cf8c2df24e451b911253689a60f853 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 15 Oct 2026 23:59:12 +0200
Subject: [PATCH 085/132] ci(release): build the .dmg on the xcode-27 image CI
 already uses

macos-15 resolved latest-stable to Xcode 26.3, whose Swift 6.2 timed out
type-checking FelResidualMeasure.swift and failed the 7.37.0 DMG while
CI on Xcode 27 passed. The release asset now comes from the same
toolchain the engine is tested and consumed with.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/release-dmg.yml | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/release-dmg.yml b/.github/workflows/release-dmg.yml
index a0d03371c..f7d732866 100644
--- a/.github/workflows/release-dmg.yml
+++ b/.github/workflows/release-dmg.yml
@@ -46,7 +46,9 @@ concurrency:
 jobs:
   build-and-upload:
     name: Build + notarize + upload .dmg
-    runs-on: macos-15
+    # Same image as ci.yml: macos-15's latest-stable is Xcode 26.3, whose Swift 6.2 timed out
+    # type-checking FelResidualMeasure and failed the 7.37.0 DMG while CI on Xcode 27 was green.
+    runs-on: xcode-27
     timeout-minutes: 30
     steps:
       # workflow_dispatch checks out the ref picked in "Use workflow from"
@@ -56,9 +58,8 @@ jobs:
         with:
           ref: refs/tags/${{ github.event.release.tag_name || inputs.tag }}
 
-      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
-        with:
-          xcode-version: latest-stable
+      - name: Show toolchain
+        run: xcodebuild -version
 
       - name: Resolve tag
         id: tag

From f7f7004aeaa3279f5eee65709963095af0851273 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 00:10:49 +0200
Subject: [PATCH 086/132] ci(release): take the DemoPlayerMac binary path from
 SwiftPM

Swift 6.4 writes the multi-arch product to .build/out instead of
.build/apple, so the hardcoded path failed the 7.37.0 DMG once it
built on Xcode 27. --show-bin-path follows SwiftPM wherever it goes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Examples/DemoPlayerMac/Scripts/build-dmg.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Examples/DemoPlayerMac/Scripts/build-dmg.sh b/Examples/DemoPlayerMac/Scripts/build-dmg.sh
index 96dd1fe23..25a7b2877 100755
--- a/Examples/DemoPlayerMac/Scripts/build-dmg.sh
+++ b/Examples/DemoPlayerMac/Scripts/build-dmg.sh
@@ -66,7 +66,8 @@ mkdir -p "$BUILD_DIR"
 echo "==> [1/6] Building universal release..."
 swift build -c release --arch arm64 --arch x86_64
 
-BINARY=".build/apple/Products/Release/DemoPlayerMac"
+# Swift 6.4 moved the multi-arch output from .build/apple to .build/out; ask SwiftPM instead of guessing.
+BINARY="$(swift build -c release --arch arm64 --arch x86_64 --show-bin-path)/DemoPlayerMac"
 [ -f "$BINARY" ] || { echo "FAIL: $BINARY not produced"; exit 1; }
 
 echo "    binary: $(file "$BINARY" | head -1 | sed 's/.*: //')"

From b78c309d478c950166835d99221f971c9f7d54b1 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 00:11:18 +0200
Subject: [PATCH 087/132] ci(release): build-dmg.sh comes from the workflow's
 commit, sources from the tag

A dispatch for an existing tag checked out that tag's packaging script,
so a script fix could never reach a re-run of the release it was for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/release-dmg.yml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/.github/workflows/release-dmg.yml b/.github/workflows/release-dmg.yml
index f7d732866..799f4d73d 100644
--- a/.github/workflows/release-dmg.yml
+++ b/.github/workflows/release-dmg.yml
@@ -58,6 +58,14 @@ jobs:
         with:
           ref: refs/tags/${{ github.event.release.tag_name || inputs.tag }}
 
+      # The packaging script follows the workflow, not the tag: the sources it builds are the tag's,
+      # but a re-run for an older tag needs today's script on today's runner (7.37.0's still looked
+      # for the binary where Swift 6.2 put it).
+      - name: Packaging script from the workflow's commit
+        run: |
+          git fetch --no-tags --depth=1 origin ${{ github.sha }}
+          git checkout FETCH_HEAD -- Examples/DemoPlayerMac/Scripts/build-dmg.sh
+
       - name: Show toolchain
         run: xcodebuild -version
 

From cb3d8bef85a440add34d67bcea3230d7bc1829e1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 15 Oct 2026 22:17:42 +0000
Subject: [PATCH 088/132] fix(dovi): sample FEL enhancement chroma co-sited
 with the base chroma

The chroma kernel fetched the enhancement-layer chroma at texel centres
((gid + 0.5) / uv_size), which for a quarter-resolution EL puts every base
chroma sample a quarter of an EL chroma texel up and to the left of where it
belongs. HDR chroma is co-sited with the top-left luma sample, so base chroma
sample n sits at EL texel n * el / bl: even samples read one texel exactly and
odd ones fall half way between two. That is DoViBaker's phase
(upsampleChromaEven copies, upsampleChromaOdd interpolates at 0.5).
Same-resolution EL is unchanged; luma already matched.

The CPU model samples EL chroma at the same phase, and a new GPU test pins it
with ramps across both axes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DJcqsrqwbUJn2KC3VnaJ64
---
 .../Video/Metal/DoviShaderSource.swift        | 13 +++++--
 .../AetherEngineTests/DoviCpuModelTests.swift | 20 ++++++-----
 .../DoviEnhancementUpsamplerTests.swift       | 36 +++++++++++++++++++
 docs/dolby-vision-fel.md                      |  3 +-
 4 files changed, 59 insertions(+), 13 deletions(-)

diff --git a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
index 7b0aa2afe..10fd9795f 100644
--- a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
@@ -555,9 +555,16 @@ kernel void dovi_compose_chroma(
         bool cr_active = (params.nlq_cr.nlq_method == DOVI_NLQ_METHOD_LINEAR && params.nlq_cr.nlq_scale != 0);
         if (cb_active || cr_active) {
             constexpr sampler s(coord::normalized, filter::linear, address::clamp_to_edge);
-            float2 uv = (float2(gid) + 0.5f) / float2(uv_width, uv_height);
-            float2 el = dovi_sample_el_2d(el_uv_tex, s, uv,
-                                          float2(params.el_width / 2u, params.el_height / 2u)) * dovi_unorm_to_code;
+            // Chroma is co-sited with the top-left luma sample (chroma location type 2, as HDR10 and
+            // Dolby Vision streams carry it), so the enhancement chroma grid and the base chroma grid
+            // share their first sample rather than their outer edge: base chroma sample n sits at EL
+            // chroma texel n * el / bl, and a quarter-resolution EL gives the even samples exactly and
+            // the odd ones half way between two texels. This is DoViBaker's phase (`upsampleChromaEven`
+            // copies, `upsampleChromaOdd` interpolates at 0.5); a centre-aligned fetch puts every
+            // sample a quarter of an EL chroma texel up and to the left. Same-resolution EL is unchanged.
+            float2 el_uv_size = float2(params.el_width / 2u, params.el_height / 2u);
+            float2 uv = float2(gid) / float2(uv_width, uv_height) + 0.5f / el_uv_size;
+            float2 el = dovi_sample_el_2d(el_uv_tex, s, uv, el_uv_size) * dovi_unorm_to_code;
             if (cb_active) {
                 vdr_cb += dovi_eval_inv_nlq(params.nlq_cb, int(rint(el.r)));
             }
diff --git a/Tests/AetherEngineTests/DoviCpuModelTests.swift b/Tests/AetherEngineTests/DoviCpuModelTests.swift
index c407b2c29..17760e07f 100644
--- a/Tests/AetherEngineTests/DoviCpuModelTests.swift
+++ b/Tests/AetherEngineTests/DoviCpuModelTests.swift
@@ -109,11 +109,13 @@ struct DoviCpuModelTests {
             !p.flags.contains(.disableResidual) && n.nlqMethod == .linear && n.nlqScale != 0
         }
 
-        /// Bilinear sample of an enhancement-layer plane at the centre of base-layer pixel (x, y) of a
-        /// plane `baseW` x `baseH`, as a 10-bit code (the word is UNORM x 65535 / 64).
-        func elCode(_ el: Plane, comp: Int, x: Int, y: Int, baseW: Int, baseH: Int) -> Int {
-            let u = (Double(x) + 0.5) / Double(baseW) * Double(el.width) - 0.5
-            let v = (Double(y) + 0.5) / Double(baseH) * Double(el.height) - 0.5
+        /// Bilinear sample of an enhancement-layer plane at base-layer sample (x, y) of a plane `baseW` x
+        /// `baseH`, as a 10-bit code (the word is UNORM x 65535 / 64). Luma samples sit at pixel centres;
+        /// chroma (`cosited`) is co-sited with the top-left luma sample, so the two grids share sample 0.
+        func elCode(_ el: Plane, comp: Int, x: Int, y: Int, baseW: Int, baseH: Int, cosited: Bool = false) -> Int {
+            let centre = cosited ? 0.0 : 0.5
+            let u = (Double(x) + centre) / Double(baseW) * Double(el.width) - centre
+            let v = (Double(y) + centre) / Double(baseH) * Double(el.height) - centre
             let x0 = Int(floor(u)), y0 = Int(floor(v))
             let fx = u - Double(x0), fy = v - Double(y0)
             func w(_ xx: Int, _ yy: Int) -> Double {
@@ -166,12 +168,12 @@ struct DoviCpuModelTests {
             if !p.flags.contains(.disableResidual) {
                 if nlqActive(p.nlqCb) {
                     a.active = true
-                    a.elCode = elCode(elUV, comp: 0, x: x, y: y, baseW: blUV.width, baseH: blUV.height)
+                    a.elCode = elCode(elUV, comp: 0, x: x, y: y, baseW: blUV.width, baseH: blUV.height, cosited: true)
                     a.residual = inverseNlq(p.nlqCb, a.elCode)
                 }
                 if nlqActive(p.nlqCr) {
                     b.active = true
-                    b.elCode = elCode(elUV, comp: 1, x: x, y: y, baseW: blUV.width, baseH: blUV.height)
+                    b.elCode = elCode(elUV, comp: 1, x: x, y: y, baseW: blUV.width, baseH: blUV.height, cosited: true)
                     b.residual = inverseNlq(p.nlqCr, b.elCode)
                 }
             }
@@ -199,10 +201,10 @@ struct DoviCpuModelTests {
             var vcr = denormalize(predict(p.polyCr, p.mmrCr, blValue: cr, y: yn, u: un, v: vn))
             if !p.flags.contains(.disableResidual) {
                 if nlqActive(p.nlqCb) {
-                    vcb += inverseNlq(p.nlqCb, elCode(elUV, comp: 0, x: x, y: y, baseW: blUV.width, baseH: blUV.height))
+                    vcb += inverseNlq(p.nlqCb, elCode(elUV, comp: 0, x: x, y: y, baseW: blUV.width, baseH: blUV.height, cosited: true))
                 }
                 if nlqActive(p.nlqCr) {
-                    vcr += inverseNlq(p.nlqCr, elCode(elUV, comp: 1, x: x, y: y, baseW: blUV.width, baseH: blUV.height))
+                    vcr += inverseNlq(p.nlqCr, elCode(elUV, comp: 1, x: x, y: y, baseW: blUV.width, baseH: blUV.height, cosited: true))
                 }
             }
             let m = Int(p.vdrMax)
diff --git a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
index 25a392444..f57287025 100644
--- a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
+++ b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
@@ -44,6 +44,42 @@ struct DoviEnhancementUpsamplerTests {
         }
     }
 
+    @Test("EL chroma is co-sited with the base chroma: even samples land on EL texels, odd ones half way")
+    func chromaIsCosited() throws {
+        // Quarter-resolution EL: EL chroma 16 x 4 under base chroma 32 x 8. Cb ramps across columns, Cr down
+        // rows, 16 codes per EL texel. Base chroma sample n sits at EL texel n / 2 (DoViBaker's
+        // upsampleChromaEven / Odd), so even samples read one texel exactly; a centre-aligned fetch would
+        // read n / 2 - 0.25 and land 4 codes low on every even sample past the edge.
+        let composer = try #require(DoviFelComposer())
+        var p = DoviGpuEdgeCaseTests.params()
+        p.ditherMode = .debugRawVDR
+        let bl = try #require(H.makeBuffer(width: 64, height: 16))
+        let el = try #require(H.makeBuffer(width: 32, height: 8))
+        H.fillPlane(bl, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(bl, plane: 1, components: 2) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 0, components: 1) { _, _, _ in 512 }
+        H.fillPlane(el, plane: 1, components: 2) { x, y, c in 600 + 16 * (c == 0 ? x : y) }
+        let out = try #require(composer.compose(baseBuffer: bl, enhancementBuffer: el, params: p))
+        let planes = DoviTestSupport.rawVDR(out, chromaOnly: true)
+        let cb = planes[1], cr = planes[2]
+
+        /// EL code at base chroma index n along an axis of `elCount` texels, clamped at the far edge.
+        func elAt(_ n: Int, _ elCount: Int) -> Double { 600.0 + 16.0 * min(Double(n) / 2.0, Double(elCount - 1)) }
+        /// 2048 + ((2r - 1) * 2048) >> 12 = 2048 + r - 1 for the positive r used here.
+        func vdr(_ e: Double) -> Int { 2048 + Int(e.rounded()) - 512 - 1 }
+
+        for y in 0..<8 {
+            for x in 0..<32 {
+                let tol = (x % 2 == 0) ? 0 : 1
+                let gotCb = cb[y * 32 + x], wantCb = vdr(elAt(x, 16))
+                #expect(abs(gotCb - wantCb) <= tol, "Cb (\(x), \(y)): \(gotCb) vs \(wantCb)")
+                let tolR = (y % 2 == 0) ? 0 : 1
+                let gotCr = cr[y * 32 + x], wantCr = vdr(elAt(y, 4))
+                #expect(abs(gotCr - wantCr) <= tolR, "Cr (\(x), \(y)): \(gotCr) vs \(wantCr)")
+            }
+        }
+    }
+
     @Test("a step edge in the EL is blended, never overshot, and the plateaus are exact")
     func stepHasNoRinging() throws {
         let low = 600, high = 700
diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index 664c2d2ea..bbadaa42a 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -103,7 +103,8 @@ composition fails.
 normalized float) or MMR when the luma curve uses MMR → plus the inverse-NLQ residual of the
 enhancement-layer luma, upsampled with one hardware-bilinear fetch →
 12-bit clamp → dither → 10-bit. Chroma: base chroma plus the average of the two vertically adjacent
-luma samples (chroma siting) → MMR → plus the residual from the upsampled enhancement chroma → dither.
+luma samples (chroma siting) → MMR → plus the residual from the enhancement chroma, upsampled with one
+hardware-bilinear fetch co-sited with the top-left luma sample (DoViBaker's phase) → dither.
 
 **Parameter ABI.** `DoviShaderSource.sharedStructs` on the GPU side, `DoviMetalParams.serialize` on
 the Swift side. `DoviLayoutProbeTests` has the GPU read every sub-block back at the offset Swift wrote

From 21c8ef949b72a66c8608eb5a2a07d843288f7240 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 15 Oct 2026 22:25:00 +0000
Subject: [PATCH 089/132] docs(changelog): note the FEL chroma siting fix

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8bca37f58..5ba692b1a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@ the public-API contract.
 
 ## [Unreleased]
 
+### Fixed
+
+- **Profile 7 FEL chroma residual is sampled where the base chroma sits.** With a quarter-resolution
+  enhancement layer (1080p under 4K), the chroma kernel read the enhancement chroma at texel centres,
+  a quarter of an EL chroma texel up and to the left of the co-sited (top-left) chroma location HDR
+  streams use. Base chroma sample n now reads EL texel n / 2, DoViBaker's phase. Same-resolution
+  enhancement layers and luma are unchanged.
+
 ## [7.37.0] - 2026-10-15
 
 ### Added

From ea1642a62ed4f1a135b2e0d383aa552f377163bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Santos?= <slotted.clean-0a@icloud.com>
Date: Fri, 16 Oct 2026 00:51:43 +0200
Subject: [PATCH 090/132] fix(live): a live stream read off its URL rides out
 an IPTV panel's refusals

A connection-limited panel answers a live TS stream's reconnects with 509
while another device on the account holds its last slot, for seconds to
tens of seconds. The reader climbed its 0.5, 1, 2, 4, 8 s ladder, gave up
after six refusals, and each refusal armed the origin's request pacer,
which the reload after it waited out (up to 10 s a request).

A live stream's 429/503/509 is now asked again every second, or after the
origin's Retry-After up to 5 s, for up to 60 s, the way the live HLS
ingest asks for its playlist; its refusals arm no pacer and lower no
budget, and the books still say the origin refused so the revive arm can
tell metered from lost. A live open the origin answers with a status
fails typed with that status at once, where the read loop used to spend
the open budget on the same request and hand back an untyped failure.

LiveStreamRefusalRetryTests.
---
 CHANGELOG.md                                  |  16 ++
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  76 +++++-
 .../LiveStreamRefusalRetryTests.swift         | 235 ++++++++++++++++++
 3 files changed, 322 insertions(+), 5 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8bca37f58..9e6c85569 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,22 @@ the public-API contract.
 
 ## [Unreleased]
 
+### Fixed
+
+- **A live stream read off its URL and refused for a while keeps its session.** The continuous
+  MPEG-TS form of an IPTV channel is one connection for as long as it plays, and a connection-limited
+  panel answers its reconnects with 509 while another device on the account holds the last slot, for
+  seconds to tens of seconds. The reader climbed its 0.5, 1, 2, 4, 8 s ladder, gave up after six
+  refusals, and each refusal armed the origin's request pacer (a quiet of up to 15 s, with each
+  request waiting up to 10 s on it), which the reload after it then waited out. A live stream's
+  429/503/509 is now asked again every second, or after the origin's Retry-After up to 5 s, for up to
+  60 s, the way the live HLS ingest asks for its playlist (#778); its refusals arm no pacer and lower
+  no budget, and the books still say the origin refused, so the revive arm tells metered from lost. A
+  live open the origin answers with a status fails typed with that status at once
+  (`AVIOReaderError.httpStatus`, `sourceRateLimited` or `sourceRefused` at the host), where the read
+  loop used to spend the open budget on the same request and hand back an untyped read failure.
+  `LiveStreamRefusalRetryTests`.
+
 ## [7.37.0] - 2026-10-15
 
 ### Added
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index d2635a77c..6016f98d3 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -438,6 +438,18 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private func noteOriginRefusal(status: Int, retryAfter: TimeInterval? = nil,
                                    respondedBy: URL? = nil) {
         let refusing = respondedBy ?? requestURL()
+        if isLive {
+            // A live stream's refusal is retried on its own short cadence (`liveRefusalRetryInterval`),
+            // which is the pacing: arming the pacer as well would hold the retry, and the reload or
+            // reopen after it, for the quiet period (up to 15 s, and up to 10 s of waiting on each
+            // request) over a refusal that clears in seconds. The books still carry the refusal, so
+            // the engine's revive arm can tell a metered source from a lost one.
+            OriginRequestBudget.shared.noteRefusalWitnessed(for: refusing)
+            if OriginRequestBudget.originKey(for: refusing) != OriginRequestBudget.originKey(for: url) {
+                OriginRequestBudget.shared.noteRefusalWitnessed(for: url)
+            }
+            return
+        }
         OriginRequestBudget.shared.noteRefusal(for: refusing, status: status, retryAfter: retryAfter)
         // The refusal usually comes back from the post-redirect CDN, while the engine's revive arm
         // only knows the URL the host loaded. Where those differ (a proxy that 302s to a signed CDN
@@ -749,6 +761,20 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     // Distinct axis from unproductiveReconnects: NOT reset by seekReconnect, so parse-driven
     // seeks cannot mask a throttled origin into an infinite reconnect loop (AetherEngine#71).
     private static let rateLimitMaxStreak = 6
+    /// A LIVE stream refused mid-session is asked for again on a steady, short cadence rather than
+    /// up the exponential ladder, and for a bounded while rather than a bounded count. The refusal
+    /// this answers is a connection-limited IPTV panel's 509 while another device on the account
+    /// holds its last slot: it lasts seconds to tens of seconds and clears the moment that slot is
+    /// free, and every second of waiting past that is a second the picture stays frozen with the
+    /// origin ready to serve. One small request a second is what the panel's own clients do, and
+    /// what the live HLS ingest does for the same refusal (`HLSLiveIngestReader`). The origin's own
+    /// Retry-After stretches the wait, up to `liveRefusalMaximumRetryWait`.
+    static let liveRefusalRetryInterval: TimeInterval = 1
+    static let liveRefusalMaximumRetryWait: TimeInterval = 5
+    /// How long a live stream keeps asking before the refusal is the session's answer.
+    static let liveRefusalRetryBudget: TimeInterval = 60
+    /// Test seam: a shorter budget, so the give-up is exercised without a minute of wall clock.
+    nonisolated(unsafe) static var liveRefusalRetryBudgetForTesting: TimeInterval?
     // Rate-limited attempts that keep the pinned redirect target before one attempt through the
     // source URL is spent on a fresh redirect. Three paced attempts (~7 s of ladder) ride out the
     // lingering-slot 509 of a connection-capped panel (#307 follow-up: the slot frees in seconds);
@@ -973,6 +999,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     // streak, resets on real read progress and whenever the header store's revision moves.
     private var credentialRefusalStreak = 0
     private var credentialStreakRevision: UInt64?
+    /// When the current rate-limited streak began, for the live budget. Cleared with the streak.
+    private var rateLimitStreakStartedAt: DispatchTime?
 
     /// Detour LRU block cache (its own leaf lock, never held across `fetchChunk`/network or
     /// `winCond`). Stores only full-size blocks; short bodies are served once but never cached
@@ -1283,6 +1311,18 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 winCond.unlock()
                 startPersistentConnection(at: 0, boundedTo: boundedInitialFetch)
                 var opened = awaitFirstPersistentData()
+                // A live open the origin answered with a status is reported as that answer, the
+                // way the live HLS ingest reports a refused join: the host retries a 509 on its own
+                // cadence with the right words for it, where the read loop's ladder would have spent
+                // the open budget on the same request and handed back an untyped read failure.
+                if !opened, isLive, let refusal = refusalOfLiveOpenConnection() {
+                    EngineLog.emit(
+                        "[AVIOReader] \(label) live open refused status=\(refusal); failing the open typed",
+                        category: .demux)
+                    markClosed()
+                    close()
+                    throw AVIOReaderError.httpStatus(refusal)
+                }
                 // 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
@@ -1548,6 +1588,15 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return (connEnded && Self.isResolvedExpiryStatus(connStatus)) ? connStatus : nil
     }
 
+    /// The status a live open's first connection ended with before any data, when it was an answer
+    /// (any 4xx or 5xx, the rate-limit statuses included); nil for a connection still open, one that
+    /// delivered, or one that ended with no status (a transport failure, which the read loop rides).
+    private func refusalOfLiveOpenConnection() -> Int? {
+        winCond.lock()
+        defer { winCond.unlock() }
+        return (connEnded && window.isEmpty && connStatus >= 400) ? 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;
@@ -2379,6 +2428,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                         if fetched {
                             unproductiveReconnects = 0
                             rateLimitStreak = 0
+                            rateLimitStreakStartedAt = nil
                             emitNetworkPhase(.flowing)   // the fetch crossed the network: the origin is serving (#85/#410)
                         }
                         detourTrackSequential(at: curPosition, length: n)
@@ -2443,6 +2493,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                     unproductiveReconnects = 0      // real progress
                     rateLimitStreak = 0             // real progress clears the 429 give-up streak (#71)
                     credentialRefusalStreak = 0     // and the credential one (#792)
+                    rateLimitStreakStartedAt = nil
                     emitNetworkPhase(.flowing)      // recovered: source delivering again (#85/#410)
                 }
                 // No flow installed and the consumer has drawn down to low water: request at the
@@ -2610,7 +2661,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             // nothing, so the exponential pacing charged against the target that did refuse is not
             // its debt. A server-sent Retry-After still applies: that is the origin's own ask, and
             // the source belongs to the same origin.
-            backoffBeforeReconnect(streak: repinned ? 0 : backoffStreak, retryAfter: retryAfter)
+            backoffBeforeReconnect(streak: repinned ? 0 : backoffStreak, retryAfter: retryAfter,
+                                   isRateLimited: isRateLimited)
             diag.recordBackoff(ms: msSince(backoffStart))
             timedReconnect(seek: false, at: frontier)
         }
@@ -2725,7 +2777,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// Exponential backoff (0.5s..8s) growing with streak; immediate on streak=0. How long the
     /// ladder waits before its next attempt. Shared by the blocking backoff below and the
     /// non-blocking one in `chargeFaultedRunwayRefill`, so both pace an origin identically.
-    private func backoffDelay(streak: Int, retryAfter: TimeInterval) -> TimeInterval {
+    private func backoffDelay(streak: Int, retryAfter: TimeInterval, isRateLimited: Bool = false) -> TimeInterval {
+        if isLive, isRateLimited {
+            return min(max(Self.liveRefusalRetryInterval, retryAfter), Self.liveRefusalMaximumRetryWait) * backoffScale
+        }
         let expo = streak <= 0 ? 0.0 : min(Double(1 << min(streak, 4)) * 0.5, 8.0)
         return min(max(expo, retryAfter), 15.0) * backoffScale
     }
@@ -2771,7 +2826,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             : isCredentialRefusal ? credentialRefusalStreak : unproductiveReconnects
         let repinned = isCredentialRefusal ? false : dropPinIfTheRefusalCallsForIt(isRateLimited: isRateLimited)
         lastUnplannedReconnectAt = Date()
-        let delay = backoffDelay(streak: repinned ? 0 : streak, retryAfter: retryAfter)
+        let delay = backoffDelay(streak: repinned ? 0 : streak, retryAfter: retryAfter,
+                                 isRateLimited: isRateLimited)
         winCond.lock()
         nextFaultedRefillAt = Date().addingTimeInterval(delay)
         winCond.unlock()
@@ -2784,8 +2840,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     }
 
     /// Blocking form of the wait above: sleeps in 0.1s slices so a close is honoured promptly.
-    private func backoffBeforeReconnect(streak: Int, retryAfter: TimeInterval) {
-        let total = backoffDelay(streak: streak, retryAfter: retryAfter)
+    private func backoffBeforeReconnect(streak: Int, retryAfter: TimeInterval, isRateLimited: Bool = false) {
+        let total = backoffDelay(streak: streak, retryAfter: retryAfter, isRateLimited: isRateLimited)
         if total <= 0 { return }
         var slept = 0.0
         while slept < total {
@@ -2802,6 +2858,16 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// Internal (not private) so the bounded give-up is unit-tested without a live origin.
     func recordRateLimitAndShouldGiveUp() -> Bool {
         rateLimitStreak += 1
+        if isLive {
+            // A live stream is given a while, not a count: at one attempt a second the count would
+            // be spent in six seconds, inside the refusal this cadence exists to ride out.
+            let now = DispatchTime.now()
+            let started = rateLimitStreakStartedAt ?? now
+            rateLimitStreakStartedAt = started
+            let budget = Self.liveRefusalRetryBudgetForTesting ?? Self.liveRefusalRetryBudget
+            let elapsed = Double(now.uptimeNanoseconds &- started.uptimeNanoseconds) / 1_000_000_000
+            return elapsed > budget
+        }
         return rateLimitStreak > Self.rateLimitMaxStreak
     }
 
diff --git a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
new file mode 100644
index 000000000..bd27a48bd
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
@@ -0,0 +1,235 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// A live stream read straight off its URL (an IPTV panel's continuous MPEG-TS form of a channel)
+/// and refused for a while, as a connection-limited panel refuses an account's requests with 509
+/// while another device holds its last slot, keeps its session: the reader asks again every second
+/// and carries on the moment it is served, the refusals arm no pacer, and a refused open is the
+/// origin's answer, typed, rather than a minute of the same request.
+@Suite("Live stream reader rides out refusals", .offCooperativePool, .timeLimit(.minutes(2)))
+struct LiveStreamRefusalRetryTests {
+
+    // MARK: - Loopback origin
+
+    /// One HTTP/1.1 response per connection (Connection: close), scripted per request.
+    private final class ScriptedOrigin: @unchecked Sendable {
+        struct Response {
+            var status: Int
+            var headers: [String: String] = [:]
+            var body = Data()
+        }
+
+        let port: UInt16
+        private let listener: LoopbackListener
+        private let respond: @Sendable (_ index: Int) -> Response
+        private let lock = NSLock()
+        private var times: [Date] = []
+
+        /// `respond` gets how many requests came before this one.
+        init?(respond: @escaping @Sendable (_ index: Int) -> Response) {
+            self.respond = respond
+            guard let listener = LoopbackListener(backlog: 16) else { return nil }
+            self.listener = listener
+            port = listener.port
+            listener.start { [weak self] conn in
+                guard let self else { close(conn); return false }
+                Thread.detachNewThread { [weak self] in
+                    self?.serve(conn)
+                }
+                return true
+            }
+        }
+
+        func stop() {
+            listener.stop()
+        }
+
+        var requestTimes: [Date] {
+            lock.withLock { times }
+        }
+
+        var url: URL {
+            URL(string: "http://127.0.0.1:\(port)/live/user/pass/1.ts")!
+        }
+
+        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 }
+            }
+            let index: Int = lock.withLock {
+                times.append(Date())
+                return times.count - 1
+            }
+            let response = respond(index)
+            var header = "HTTP/1.1 \(response.status) \(response.status == 200 ? "OK" : "Status")\r\n"
+            header += "Content-Type: video/mp2t\r\n"
+            for (field, value) in response.headers {
+                header += "\(field): \(value)\r\n"
+            }
+            header += "Content-Length: \(response.body.count)\r\nConnection: close\r\n\r\n"
+            _ = header.withCString { write(conn, $0, strlen($0)) }
+            response.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
+                }
+            }
+        }
+    }
+
+    /// Valid sync bytes at 188-byte cadence, enough to be read in several reader calls.
+    private static func streamBytes(count packets: Int) -> Data {
+        var data = Data(capacity: packets * 188)
+        for packet in 0..<packets {
+            var ts = [UInt8](repeating: UInt8(truncatingIfNeeded: packet), count: 188)
+            ts[0] = 0x47
+            data.append(contentsOf: ts)
+        }
+        return data
+    }
+
+    private static func makeLiveReader(_ url: URL) -> AVIOReader {
+        AVIOReader(url: url, label: "live", prefetchEnabled: true, isLive: true)
+    }
+
+    /// Reads until `expectedBytes` have come through or the reader fails; the bytes, and the code
+    /// the read ended with when it did not deliver them.
+    private static func drain(_ reader: AVIOReader, expectedBytes: Int) -> (bytes: Int, failure: Int32?) {
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: 64 * 1024)
+        defer { buf.deallocate() }
+        var total = 0
+        while total < expectedBytes {
+            let n = reader.read(into: buf, size: 64 * 1024)
+            if n <= 0 { return (total, n) }
+            total += Int(n)
+        }
+        return (total, nil)
+    }
+
+    private static func gaps(_ times: [Date]) -> [TimeInterval] {
+        zip(times, times.dropFirst()).map { $1.timeIntervalSince($0) }
+    }
+
+    // MARK: - Tests
+
+    @Test("a stream refused mid-session is asked for again every second until it is served")
+    func refusedMidStreamIsRetriedEverySecond() throws {
+        let first = Self.streamBytes(count: 400)
+        let second = Self.streamBytes(count: 400)
+        let origin = try #require(ScriptedOrigin { index in
+            switch index {
+            case 0: return .init(status: 200, body: first)
+            case 1, 2, 3: return .init(status: 509)
+            default: return .init(status: 200, body: second)
+            }
+        })
+        defer { origin.stop() }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let drained = Self.drain(reader, expectedBytes: first.count + second.count)
+
+        #expect(drained.failure == nil)
+        #expect(drained.bytes >= first.count + second.count)
+        let times = origin.requestTimes
+        #expect(times.count >= 5)
+        // The three refusals are retried a second apart, give or take the request itself and a
+        // loaded test host; never up the 0.5, 1, 2, 4 s ladder, whose third rung alone is 4 s.
+        let retryGaps = Array(Self.gaps(times).dropFirst()).prefix(3)
+        #expect(retryGaps.count == 3)
+        for gap in retryGaps {
+            #expect(gap >= 0.9 && gap <= 3.5, "retry gap \(gap)s")
+        }
+        #expect(retryGaps.reduce(0, +) <= 7, "retry gaps \(Array(retryGaps))")
+        // The refusals armed no pacer and lowered no budget: the books hold no refusal for this
+        // origin (a witness stamp carries no count).
+        let books = OriginRequestBudget.shared.snapshot(for: origin.url)
+        #expect((books?.refusals ?? 0) == 0)
+        #expect(books?.limit == nil)
+    }
+
+    @Test("the origin's Retry-After stretches the wait, up to five seconds")
+    func retryAfterStretchesTheWait() throws {
+        let first = Self.streamBytes(count: 400)
+        let second = Self.streamBytes(count: 400)
+        let origin = try #require(ScriptedOrigin { index in
+            switch index {
+            case 0: return .init(status: 200, body: first)
+            case 1: return .init(status: 503, headers: ["Retry-After": "2"])
+            case 2: return .init(status: 503, headers: ["Retry-After": "30"])
+            default: return .init(status: 200, body: second)
+            }
+        })
+        defer { origin.stop() }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let drained = Self.drain(reader, expectedBytes: first.count + second.count)
+
+        #expect(drained.failure == nil)
+        let retryGaps = Array(Self.gaps(origin.requestTimes).dropFirst())
+        #expect(retryGaps.count >= 2)
+        if retryGaps.count >= 2 {
+            #expect(retryGaps[0] >= 1.9 && retryGaps[0] <= 4.5, "Retry-After 2 gap \(retryGaps[0])s")
+            #expect(retryGaps[1] >= 4.9 && retryGaps[1] <= 8, "Retry-After 30 capped gap \(retryGaps[1])s")
+        }
+    }
+
+    @Test("a stream refused for longer than the budget ends as a read error")
+    func refusedPastTheBudgetGivesUp() throws {
+        let first = Self.streamBytes(count: 400)
+        let origin = try #require(ScriptedOrigin { index in
+            index == 0 ? .init(status: 200, body: first) : .init(status: 509)
+        })
+        defer { origin.stop() }
+        AVIOReader.liveRefusalRetryBudgetForTesting = 3
+        defer { AVIOReader.liveRefusalRetryBudgetForTesting = nil }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let drained = Self.drain(reader, expectedBytes: first.count + 1)
+
+        #expect(drained.bytes == first.count)
+        #expect(drained.failure == FFmpegErr.eio)
+        // Asked about three times over the budget, one a second, then given up.
+        let refusals = origin.requestTimes.count - 1
+        #expect(refusals >= 3 && refusals <= 6, "\(refusals) refused attempts")
+    }
+
+    @Test("a live open the origin refuses fails typed with its status at once")
+    func refusedOpenFailsTyped() throws {
+        let origin = try #require(ScriptedOrigin { _ in .init(status: 509) })
+        defer { origin.stop() }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+
+        let started = Date()
+        let failure = #expect(throws: AVIOReaderError.self) { try reader.open() }
+        #expect(failure == .httpStatus(509))
+        #expect(Date().timeIntervalSince(started) < 5)
+        #expect(origin.requestTimes.count == 1)
+    }
+
+    @Test("a live open answered 403 fails typed too")
+    func forbiddenOpenFailsTyped() throws {
+        let origin = try #require(ScriptedOrigin { _ in .init(status: 403) })
+        defer { origin.stop() }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+
+        let failure = #expect(throws: AVIOReaderError.self) { try reader.open() }
+        #expect(failure == .httpStatus(403))
+    }
+}

From c02ed6616ea13e3f103f3f971d6d8ab281ecc72c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Santos?= <slotted.clean-0a@icloud.com>
Date: Fri, 16 Oct 2026 00:51:43 +0200
Subject: [PATCH 091/132] feat(software): a live join starts near the newest
 media once the connect burst has landed

A continuous live stream over HTTP opens with a burst of what the origin
holds of the channel (8 to 18 s on one IPTV panel, at link speed), and
the software host armed its clock on that burst's first packet. Nothing
on the software path catches up, so the picture ran the whole burst
behind the broadcast for as long as the channel played: measured 17 s
behind on a channel whose native-path session ran 6 s behind.

The live feeder now waits for the burst to land (the ring growing no
faster than real time over a quarter second, from 0.3 s on, or 1.5 s at
most) and starts 4 s behind the newest media, on a keyframe. A source
that delivers in real time, or a ring too shallow to be worth a later
keyframe, still starts from its first packet. The media behind the start
stays in the rewind ring. Measured on the same channel: first picture
1.1 s after the open, 4 to 6 s behind the newest media.

SoftwareLiveJoinPolicy, SoftwareLiveJoinPlacementTests.
---
 CHANGELOG.md                                  | 13 +++
 .../Native/SoftwareLiveJoinPolicy.swift       | 78 +++++++++++++++
 .../Native/SoftwarePlaybackHost.swift         | 59 ++++++++++++
 .../DocumentedConstantsTests.swift            |  9 ++
 .../SoftwareLiveJoinPlacementTests.swift      | 94 +++++++++++++++++++
 docs/formats.md                               |  2 +-
 6 files changed, 254 insertions(+), 1 deletion(-)
 create mode 100644 Sources/AetherEngine/Native/SoftwareLiveJoinPolicy.swift
 create mode 100644 Tests/AetherEngineTests/SoftwareLiveJoinPlacementTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8bca37f58..6ac74bc5c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,19 @@ the public-API contract.
 
 ## [Unreleased]
 
+### Changed
+
+- **A live stream on the software path starts near the newest media.** A continuous live stream over
+  HTTP opens with a burst of what the origin holds of the channel (8 to 18 s on one IPTV panel, at
+  link speed), and the software host armed its clock on that burst's first packet. Nothing on the
+  software path catches up, so the picture then ran the whole burst behind the broadcast for as long
+  as the channel played: measured 17 s behind on a channel whose native-path session ran 6 s behind.
+  The live feeder now waits for the burst to land (the ring growing no faster than real time over a
+  quarter second, from 0.3 s on, or 1.5 s at most) and starts 4 s behind the newest media, on a
+  keyframe; a source that delivers in real time, or a ring too shallow to be worth a later keyframe,
+  still starts from its first packet. The media behind the start stays in the rewind ring.
+  `SoftwareLiveJoinPolicy`, `SoftwareLiveJoinPlacementTests`.
+
 ## [7.37.0] - 2026-10-15
 
 ### Added
diff --git a/Sources/AetherEngine/Native/SoftwareLiveJoinPolicy.swift b/Sources/AetherEngine/Native/SoftwareLiveJoinPolicy.swift
new file mode 100644
index 000000000..fd9222e61
--- /dev/null
+++ b/Sources/AetherEngine/Native/SoftwareLiveJoinPolicy.swift
@@ -0,0 +1,78 @@
+import Foundation
+
+/// Where a live session on the software host starts playing, once what the source sends at connect
+/// has landed.
+///
+/// A continuous live stream over HTTP (an IPTV panel's MPEG-TS form of a channel) opens with a burst:
+/// the panel sends what it holds of the channel, 8 to 18 s of media measured on one panel, at link
+/// speed, and real time after that. The feeder used to arm the clock on the first packet of that
+/// burst, and since nothing on the software path ever catches up, the picture then ran the whole
+/// burst behind the broadcast for as long as the channel played: 17 s on a channel whose native-path
+/// session, which AVPlayer places a holdback behind the newest segment, ran 6 s behind. For live
+/// sport that is the difference other players are judged by.
+///
+/// So a live join on the software host waits for the burst to land, then starts `leadSeconds` behind
+/// the newest media, on the keyframe at or before that moment. The burst is landed when the ring has
+/// grown no faster than real time over `calmWindowSeconds` (a source that delivers in real time is
+/// calm from its first packets and starts after `minimumSettleSeconds`), or after
+/// `maximumSettleSeconds` on a link that is still catching up, where the start takes what has
+/// arrived. A ring holding less than `leadSeconds + minimumSkipSeconds` is played from its start:
+/// there is nothing worth skipping. The media behind the start stays in the rewind ring.
+///
+/// Pure, so the rule is testable without a session; `SoftwarePlaybackHost` feeds it the ring's
+/// first and newest PTS from the feeder thread until it decides.
+struct SoftwareLiveJoinPolicy: Equatable {
+    /// How far behind the newest media the picture starts. The audio pump keeps this much decoded
+    /// audio ahead of the clock (`AudioLookaheadPolicy.targetLeadSeconds`), and a panel that hands
+    /// over about a second of media at a time leaves the lead swinging within it.
+    static let leadSeconds: Double = 4
+    /// The burst is given at least this long to begin landing before the ring's growth is judged.
+    static let minimumSettleSeconds: TimeInterval = 0.3
+    /// After this long the start takes what has arrived, calm or not.
+    static let maximumSettleSeconds: TimeInterval = 1.5
+    /// Growth is judged over windows this long.
+    static let calmWindowSeconds: TimeInterval = 0.25
+    /// A ring that grew by more than this multiple of the wall clock over a window is still landing
+    /// the burst.
+    static let calmGrowthRatio: Double = 1.5
+    /// A start is moved only when it skips at least this much; less is not worth a later keyframe.
+    static let minimumSkipSeconds: Double = 2
+
+    enum Decision: Equatable {
+        /// Play from the ring's first packet.
+        case fromStart
+        /// Start on the keyframe at or before this source PTS.
+        case place(targetPts: Double)
+    }
+
+    private var firstObservedAt: TimeInterval?
+    private var windowStartPts: Double?
+    private var windowStartAt: TimeInterval?
+
+    /// Notes the ring's first and newest PTS at `now` (seconds on any monotonic clock); nil while the
+    /// burst is still landing, then the decision, once.
+    mutating func observe(firstPts: Double, newestPts: Double, at now: TimeInterval) -> Decision? {
+        guard let firstObservedAt, let windowStartPts, let windowStartAt else {
+            self.firstObservedAt = now
+            self.windowStartPts = newestPts
+            self.windowStartAt = now
+            return nil
+        }
+        let elapsed = now - firstObservedAt
+        var settled = elapsed >= Self.maximumSettleSeconds
+        if !settled, elapsed >= Self.minimumSettleSeconds, now - windowStartAt >= Self.calmWindowSeconds {
+            let grew = newestPts - windowStartPts
+            let wall = now - windowStartAt
+            if grew <= wall * Self.calmGrowthRatio {
+                settled = true
+            } else {
+                self.windowStartPts = newestPts
+                self.windowStartAt = now
+            }
+        }
+        guard settled else { return nil }
+        let span = newestPts - firstPts
+        guard span.isFinite, span >= Self.leadSeconds + Self.minimumSkipSeconds else { return .fromStart }
+        return .place(targetPts: newestPts - Self.leadSeconds)
+    }
+}
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 33b97a6ef..aeea19bd9 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -371,6 +371,9 @@ final class SoftwarePlaybackHost {
     nonisolated(unsafe) private var sessionStartPts: Double = .nan
 
     nonisolated(unsafe) private var newestSourcePts: Double = .nan
+    /// Where a live session's picture starts once the source's connect burst has landed; read and
+    /// advanced by the live feeder under `liveEdgeLock`, reset with the session.
+    nonisolated(unsafe) private var liveJoinPolicy = SoftwareLiveJoinPolicy()
 
     /// Guards `sessionStartPts` / `newestSourcePts` against the demux
     /// thread writing while the main-actor time tick reads them.
@@ -2057,6 +2060,7 @@ final class SoftwarePlaybackHost {
         retentionClaims.removeAll()
         liveEdgeLock.lock()
         sessionStartPts = .nan
+        liveJoinPolicy = SoftwareLiveJoinPolicy()
         newestSourcePts = .nan
         liveEdgeLock.unlock()
 
@@ -2219,6 +2223,20 @@ final class SoftwarePlaybackHost {
             let recoverCursor: @Sendable (Int) -> Void = { [weak self] old in
                 self?.recoverEvictedFeedCursor(from: old, ring: ring)
             }
+            // Where the live join starts, once the connect burst has landed (see the policy). Nil
+            // while it is still landing; the feeder asks again a moment later.
+            let liveJoinPlacement: @Sendable () -> SoftwareLiveJoinPolicy.Decision? = { [weak self] in
+                guard let self else { return .fromStart }
+                self.liveEdgeLock.lock()
+                defer { self.liveEdgeLock.unlock() }
+                guard self.sessionStartPts.isFinite, self.newestSourcePts.isFinite else { return nil }
+                return self.liveJoinPolicy.observe(firstPts: self.sessionStartPts,
+                                                   newestPts: self.newestSourcePts,
+                                                   at: ProcessInfo.processInfo.systemUptime)
+            }
+            let placeCursor: @Sendable (Int) -> Void = { [weak self] seq in
+                self?.setFeedCursor(seq)
+            }
             let setSourceEnded: @Sendable () -> Void = { [weak self] in
                 self?.sourceEnded = true
             }
@@ -2267,6 +2285,8 @@ final class SoftwarePlaybackHost {
                     readCursor: readCursor,
                     advanceCursor: advanceCursor,
                     recoverCursor: recoverCursor,
+                    liveJoinPlacement: liveJoinPlacement,
+                    placeCursor: placeCursor,
                     seekGeneration: getSeekGeneration,
                     currentRate: currentRate,
                     isPlaying: getFeederPlaying,
@@ -2541,6 +2561,8 @@ final class SoftwarePlaybackHost {
         readCursor: @Sendable () -> Int,
         advanceCursor: @Sendable (Int) -> Void,
         recoverCursor: @Sendable (Int) -> Void,
+        liveJoinPlacement: @Sendable () -> SoftwareLiveJoinPolicy.Decision? = { .fromStart },
+        placeCursor: @Sendable (Int) -> Void = { _ in },
         seekGeneration: @Sendable () -> UInt64,
         currentRate: @Sendable () -> Float,
         isPlaying: @Sendable () -> Bool,
@@ -2552,6 +2574,9 @@ final class SoftwarePlaybackHost {
         audioTapSink: @Sendable () -> ((@Sendable (CMSampleBuffer) -> Void)?),
         noteDecodeGeneration: @Sendable () -> Void
     ) {
+        // The join's start is placed once, before the first packet is fed; a seek before then is
+        // the viewer's own choice of position and retires it.
+        var liveJoinPending = true
         // Audio look-ahead pump (#107 audio chopping): feed audio packets ahead of the
         // combined cursor so the audio renderer holds AudioLookaheadPolicy.targetLeadSeconds
         // of decoded audio regardless of video decode pace. Without it audio lead is capped
@@ -2689,6 +2714,40 @@ final class SoftwarePlaybackHost {
                 preArmPacketsFed = 0
                 hadLead = false
                 rebuffering = false
+                liveJoinPending = false
+            }
+            if liveJoinPending {
+                switch liveJoinPlacement() {
+                case nil:
+                    if sourceEnded() {
+                        // Nothing more will land; play what there is from its start.
+                        liveJoinPending = false
+                    } else {
+                        condition.lock()
+                        autoreleasepool {
+                            _ = condition.wait(until: Date(timeIntervalSinceNow: 0.05))
+                        }
+                        condition.unlock()
+                        return true
+                    }
+                case .fromStart?:
+                    liveJoinPending = false
+                case .place(let targetPts)?:
+                    liveJoinPending = false
+                    let cursor = readCursor()
+                    if let seq = ring.seq(forKeyframeAtOrBefore: targetPts), seq > cursor,
+                       let keyframe = ring.packet(atSeq: seq) {
+                        let skipped = keyframe.pts - (ring.packet(atSeq: cursor)?.pts ?? keyframe.pts)
+                        EngineLog.emit(
+                            "[SWHost] live join placed \(String(format: "%.1f", SoftwareLiveJoinPolicy.leadSeconds))s "
+                            + "behind the newest media: skipped \(String(format: "%.1f", skipped))s of the "
+                            + "connect burst (cursor seq=\(cursor) -> \(seq), keyframe pts=\(String(format: "%.2f", keyframe.pts)))",
+                            category: .swPlayback
+                        )
+                        placeCursor(seq)
+                        return true
+                    }
+                }
             }
             let cursor = readCursor()
             let bounds = ring.seqBounds
diff --git a/Tests/AetherEngineTests/DocumentedConstantsTests.swift b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
index c7688b15a..4305539a6 100644
--- a/Tests/AetherEngineTests/DocumentedConstantsTests.swift
+++ b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
@@ -107,6 +107,15 @@ final class DocumentedConstantsTests: XCTestCase {
         return text
     }
 
+    /// docs/formats.md quotes the lead a software-path live join keeps behind the newest media.
+    func testSoftwareLiveJoinLeadMatchesDocumentation() throws {
+        XCTAssertEqual(SoftwareLiveJoinPolicy.leadSeconds, 4)
+        XCTAssertEqual(SoftwareLiveJoinPolicy.minimumSettleSeconds, 0.3)
+        XCTAssertEqual(SoftwareLiveJoinPolicy.maximumSettleSeconds, 1.5)
+        XCTAssertEqual(SoftwareLiveJoinPolicy.calmWindowSeconds, 0.25)
+        assertDocumented("`SoftwareLiveJoinPolicy.leadSeconds` (4 s) behind the newest media", try documentation())
+    }
+
     // MARK: - Documentation corpus
 
     private static var repoRoot: URL {
diff --git a/Tests/AetherEngineTests/SoftwareLiveJoinPlacementTests.swift b/Tests/AetherEngineTests/SoftwareLiveJoinPlacementTests.swift
new file mode 100644
index 000000000..c163e7c98
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwareLiveJoinPlacementTests.swift
@@ -0,0 +1,94 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// A live session on the software host starts near the newest media once the source's connect burst
+/// has landed, instead of at the burst's first packet, where it would run the whole burst behind the
+/// broadcast for the rest of the channel.
+@Suite("Software live join placement")
+struct SoftwareLiveJoinPlacementTests {
+
+    /// A panel that sends 12 s of media in the first half second, then real time: the join waits
+    /// for the burst to calm and starts `leadSeconds` behind the newest media.
+    @Test("a connect burst is landed before the start is placed behind the newest media")
+    func burstIsLandedThenPlaced() throws {
+        var policy = SoftwareLiveJoinPolicy()
+        let first = 1000.0
+        var decision: SoftwareLiveJoinPolicy.Decision?
+        var decidedAt: TimeInterval?
+        var now: TimeInterval = 0
+        while now <= 2, decision == nil {
+            // 12 s of media over the first 0.5 s, then one second of media per second.
+            let newest = now < 0.5 ? first + 24 * now : first + 12 + (now - 0.5)
+            decision = policy.observe(firstPts: first, newestPts: newest, at: now)
+            if decision != nil { decidedAt = now }
+            now += 0.05
+        }
+        let at = try #require(decidedAt)
+        // Calm is judged from 0.3 s on, over a quarter-second window.
+        #expect(at >= 0.3 && at <= 1.0, "decided at \(at)s")
+        let newestThen = first + 12 + (at - 0.5)
+        #expect(decision == .place(targetPts: newestThen - SoftwareLiveJoinPolicy.leadSeconds))
+    }
+
+    @Test("a source that delivers in real time starts from its first packet, soon")
+    func realTimeSourceStartsFromTheFirstPacket() throws {
+        var policy = SoftwareLiveJoinPolicy()
+        let first = 50.0
+        var decision: SoftwareLiveJoinPolicy.Decision?
+        var decidedAt: TimeInterval?
+        var now: TimeInterval = 0
+        while now <= 2, decision == nil {
+            decision = policy.observe(firstPts: first, newestPts: first + now, at: now)
+            if decision != nil { decidedAt = now }
+            now += 0.05
+        }
+        #expect(decision == .fromStart)
+        let at = try #require(decidedAt)
+        #expect(at >= SoftwareLiveJoinPolicy.minimumSettleSeconds && at <= 0.7, "decided at \(at)s")
+    }
+
+    @Test("a burst still landing at the deadline is placed on what has arrived")
+    func slowLinkPlacesAtTheDeadline() throws {
+        var policy = SoftwareLiveJoinPolicy()
+        let first = 0.0
+        var decision: SoftwareLiveJoinPolicy.Decision?
+        var decidedAt: TimeInterval?
+        var now: TimeInterval = 0
+        while now <= 3, decision == nil {
+            // Six seconds of media per second for as long as it takes: never calm.
+            decision = policy.observe(firstPts: first, newestPts: first + 6 * now, at: now)
+            if decision != nil { decidedAt = now }
+            now += 0.05
+        }
+        let at = try #require(decidedAt)
+        #expect(abs(at - SoftwareLiveJoinPolicy.maximumSettleSeconds) < 0.06, "decided at \(at)s")
+        #expect(decision == .place(targetPts: 6 * at - SoftwareLiveJoinPolicy.leadSeconds))
+    }
+
+    @Test("a short burst is not worth a later start")
+    func shortBurstPlaysFromTheStart() {
+        var policy = SoftwareLiveJoinPolicy()
+        let first = 10.0
+        var decision: SoftwareLiveJoinPolicy.Decision?
+        var now: TimeInterval = 0
+        while now <= 2, decision == nil {
+            // Five seconds of media at once, then real time: a lead of four leaves one to skip.
+            decision = policy.observe(firstPts: first, newestPts: first + 5 + now, at: now)
+            now += 0.05
+        }
+        #expect(decision == .fromStart)
+    }
+
+    @Test("media whose timestamps run backwards is played from the start")
+    func backwardsTimestampsPlayFromTheStart() {
+        var policy = SoftwareLiveJoinPolicy()
+        var decision: SoftwareLiveJoinPolicy.Decision?
+        var now: TimeInterval = 0
+        while now <= 2, decision == nil {
+            decision = policy.observe(firstPts: 5000, newestPts: 20 + now, at: now)
+            now += 0.05
+        }
+        #expect(decision == .fromStart)
+    }
+}
diff --git a/docs/formats.md b/docs/formats.md
index 142e9dcc3..c69172161 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -607,7 +607,7 @@ Server-side ad insertion (SSAI) plays through the direct path instead of bouncin
 
 The live path's sliding-window eviction (which bounds resident memory) and DVR rewind are confirmed on Apple TV against a real broadcast feed: `behindLiveSeconds` holds at real-time pacing and the resident footprint stays bounded within the tvOS jetsam budget. The same behavior is exercised off-device through the `aetherctl live` / `hlsfixture` harnesses (sliding-window retention, real-time pacing, mid-stream reconnect, program-boundary discontinuities, DVR timeshift).
 
-Raw live MPEG-TS over HTTP (a tuner or tuner proxy serving the transport stream directly, no HLS) plays on the software path; the forward-only reader routes it there automatically. Load it with `isLive: true` plus a `dvrWindowSeconds` for live semantics and the fastest open (an explicitly live load skips the open-time size probes entirely); `SourceProbe.isLive` flags no-duration network streams so hosts can detect and reload. Mid-stream-joined sources, which deliver their first samples at arbitrary PTS hours past zero, anchor the clock at the first decoded sample on every session shape (live, live+DVR, and a plain VOD open of the same URL or of a mid-broadcast capture file), publishing session-relative positions while `sourceTime` stays on the source axis for subtitles (#107).
+Raw live MPEG-TS over HTTP (a tuner, a tuner proxy, or an IPTV panel's continuous form of a channel) is routed like any live source: the native loopback path unless the codec, declared interlace or a host override sends it to the software path. Such a stream opens with whatever the origin holds of the channel, sent at link speed (8 to 18 s on one IPTV panel), and a software session no longer starts on the first packet of that burst, where it would run the whole burst behind the broadcast for as long as it played: once the burst has landed the live feeder places the start `SoftwareLiveJoinPolicy.leadSeconds` (4 s) behind the newest media, on a keyframe, and the burst stays in the rewind ring (the native path's AVPlayer already sits a holdback behind the newest segment). Load it with `isLive: true` plus a `dvrWindowSeconds` for live semantics and the fastest open (an explicitly live load skips the open-time size probes entirely); `SourceProbe.isLive` flags no-duration network streams so hosts can detect and reload. Mid-stream-joined sources, which deliver their first samples at arbitrary PTS hours past zero, anchor the clock at the first decoded sample on every session shape (live, live+DVR, and a plain VOD open of the same URL or of a mid-broadcast capture file), publishing session-relative positions while `sourceTime` stays on the source axis for subtitles (#107).
 
 ## Known limitations
 

From d35e5dfbccae5c7a5b5a592d391e1947208151ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Santos?= <slotted.clean-0a@icloud.com>
Date: Fri, 16 Oct 2026 04:11:07 +0200
Subject: [PATCH 092/132] test(live): judge the live refusal retries by their
 outcome, not by the wall clock

The three loopback cases bounded the gaps between the origin's requests
(a second each, Retry-After stretching them to 2 and 5 s, a count within
the budget), and CI's runner took three times as long as a Mac to run
the same suite, so the bounds decided what the tests reported. They now
run with the reconnect backoff scaled down, as the other reader suites
do, and assert what came through, how many requests it took, and that
the origin's books hold no refusal; the wait itself is a pure rule
(AVIOReader.liveRefusalWait) tested as one.
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift |   8 +-
 .../LiveStreamRefusalRetryTests.swift         | 104 ++++++++----------
 2 files changed, 51 insertions(+), 61 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 6016f98d3..77fbb2646 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -775,6 +775,12 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     static let liveRefusalRetryBudget: TimeInterval = 60
     /// Test seam: a shorter budget, so the give-up is exercised without a minute of wall clock.
     nonisolated(unsafe) static var liveRefusalRetryBudgetForTesting: TimeInterval?
+
+    /// The wait before a live stream's refused request is made again: a second, or the origin's
+    /// Retry-After (0 for none) when that is longer, never more than `liveRefusalMaximumRetryWait`.
+    static func liveRefusalWait(retryAfter: TimeInterval) -> TimeInterval {
+        min(max(liveRefusalRetryInterval, retryAfter), liveRefusalMaximumRetryWait)
+    }
     // Rate-limited attempts that keep the pinned redirect target before one attempt through the
     // source URL is spent on a fresh redirect. Three paced attempts (~7 s of ladder) ride out the
     // lingering-slot 509 of a connection-capped panel (#307 follow-up: the slot frees in seconds);
@@ -2779,7 +2785,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// non-blocking one in `chargeFaultedRunwayRefill`, so both pace an origin identically.
     private func backoffDelay(streak: Int, retryAfter: TimeInterval, isRateLimited: Bool = false) -> TimeInterval {
         if isLive, isRateLimited {
-            return min(max(Self.liveRefusalRetryInterval, retryAfter), Self.liveRefusalMaximumRetryWait) * backoffScale
+            return Self.liveRefusalWait(retryAfter: retryAfter) * backoffScale
         }
         let expo = streak <= 0 ? 0.0 : min(Double(1 << min(streak, 4)) * 0.5, 8.0)
         return min(max(expo, retryAfter), 15.0) * backoffScale
diff --git a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
index bd27a48bd..732ff6c3c 100644
--- a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
+++ b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
@@ -4,9 +4,13 @@ import Foundation
 
 /// A live stream read straight off its URL (an IPTV panel's continuous MPEG-TS form of a channel)
 /// and refused for a while, as a connection-limited panel refuses an account's requests with 509
-/// while another device holds its last slot, keeps its session: the reader asks again every second
-/// and carries on the moment it is served, the refusals arm no pacer, and a refused open is the
-/// origin's answer, typed, rather than a minute of the same request.
+/// while another device holds its last slot, keeps its session: the reader asks again on a short,
+/// steady wait until it is served, the refusals arm no pacer, and a refused open is the origin's
+/// answer, typed, rather than a minute of the same request.
+///
+/// The loopback cases run with the reconnect backoff scaled down, the way the other reader suites
+/// do, and are judged by what came through and how many requests it took, never by the wall clock.
+/// The wait itself is a pure rule, tested as one.
 @Suite("Live stream reader rides out refusals", .offCooperativePool, .timeLimit(.minutes(2)))
 struct LiveStreamRefusalRetryTests {
 
@@ -24,7 +28,7 @@ struct LiveStreamRefusalRetryTests {
         private let listener: LoopbackListener
         private let respond: @Sendable (_ index: Int) -> Response
         private let lock = NSLock()
-        private var times: [Date] = []
+        private var count = 0
 
         /// `respond` gets how many requests came before this one.
         init?(respond: @escaping @Sendable (_ index: Int) -> Response) {
@@ -45,8 +49,8 @@ struct LiveStreamRefusalRetryTests {
             listener.stop()
         }
 
-        var requestTimes: [Date] {
-            lock.withLock { times }
+        var requestCount: Int {
+            lock.withLock { count }
         }
 
         var url: URL {
@@ -64,8 +68,8 @@ struct LiveStreamRefusalRetryTests {
                 if request.count > 64 * 1024 { return }
             }
             let index: Int = lock.withLock {
-                times.append(Date())
-                return times.count - 1
+                count += 1
+                return count - 1
             }
             let response = respond(index)
             var header = "HTTP/1.1 \(response.status) \(response.status == 200 ? "OK" : "Status")\r\n"
@@ -115,20 +119,30 @@ struct LiveStreamRefusalRetryTests {
         return (total, nil)
     }
 
-    private static func gaps(_ times: [Date]) -> [TimeInterval] {
-        zip(times, times.dropFirst()).map { $1.timeIntervalSince($0) }
+    // MARK: - The wait
+
+    @Test("the wait is a second, or the origin's Retry-After up to five seconds")
+    func waitIsASecondOrTheRetryAfterUpToFive() {
+        #expect(AVIOReader.liveRefusalWait(retryAfter: 0) == 1)
+        #expect(AVIOReader.liveRefusalWait(retryAfter: 0.3) == 1)
+        #expect(AVIOReader.liveRefusalWait(retryAfter: 2) == 2)
+        #expect(AVIOReader.liveRefusalWait(retryAfter: 5) == 5)
+        #expect(AVIOReader.liveRefusalWait(retryAfter: 30) == 5)
     }
 
-    // MARK: - Tests
+    // MARK: - The stream
 
-    @Test("a stream refused mid-session is asked for again every second until it is served")
-    func refusedMidStreamIsRetriedEverySecond() throws {
+    @Test("a stream refused mid-session is asked for again until it is served, and arms no pacer")
+    func refusedMidStreamIsRetriedUntilServed() throws {
+        AetherEngine.reconnectBackoffScaleForTesting = 0.02
+        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
         let first = Self.streamBytes(count: 400)
         let second = Self.streamBytes(count: 400)
+        let refusals = 3
         let origin = try #require(ScriptedOrigin { index in
             switch index {
             case 0: return .init(status: 200, body: first)
-            case 1, 2, 3: return .init(status: 509)
+            case 1...refusals: return .init(status: 509)
             default: return .init(status: 200, body: second)
             }
         })
@@ -141,60 +155,28 @@ struct LiveStreamRefusalRetryTests {
 
         #expect(drained.failure == nil)
         #expect(drained.bytes >= first.count + second.count)
-        let times = origin.requestTimes
-        #expect(times.count >= 5)
-        // The three refusals are retried a second apart, give or take the request itself and a
-        // loaded test host; never up the 0.5, 1, 2, 4 s ladder, whose third rung alone is 4 s.
-        let retryGaps = Array(Self.gaps(times).dropFirst()).prefix(3)
-        #expect(retryGaps.count == 3)
-        for gap in retryGaps {
-            #expect(gap >= 0.9 && gap <= 3.5, "retry gap \(gap)s")
-        }
-        #expect(retryGaps.reduce(0, +) <= 7, "retry gaps \(Array(retryGaps))")
+        // The first body, the refusals, and the body that followed them: nothing was given up on
+        // and nothing asked twice over.
+        #expect(origin.requestCount >= refusals + 2)
         // The refusals armed no pacer and lowered no budget: the books hold no refusal for this
         // origin (a witness stamp carries no count).
         let books = OriginRequestBudget.shared.snapshot(for: origin.url)
         #expect((books?.refusals ?? 0) == 0)
         #expect(books?.limit == nil)
-    }
-
-    @Test("the origin's Retry-After stretches the wait, up to five seconds")
-    func retryAfterStretchesTheWait() throws {
-        let first = Self.streamBytes(count: 400)
-        let second = Self.streamBytes(count: 400)
-        let origin = try #require(ScriptedOrigin { index in
-            switch index {
-            case 0: return .init(status: 200, body: first)
-            case 1: return .init(status: 503, headers: ["Retry-After": "2"])
-            case 2: return .init(status: 503, headers: ["Retry-After": "30"])
-            default: return .init(status: 200, body: second)
-            }
-        })
-        defer { origin.stop() }
-        let reader = Self.makeLiveReader(origin.url)
-        defer { reader.markClosed(); reader.close() }
-        try reader.open()
-
-        let drained = Self.drain(reader, expectedBytes: first.count + second.count)
-
-        #expect(drained.failure == nil)
-        let retryGaps = Array(Self.gaps(origin.requestTimes).dropFirst())
-        #expect(retryGaps.count >= 2)
-        if retryGaps.count >= 2 {
-            #expect(retryGaps[0] >= 1.9 && retryGaps[0] <= 4.5, "Retry-After 2 gap \(retryGaps[0])s")
-            #expect(retryGaps[1] >= 4.9 && retryGaps[1] <= 8, "Retry-After 30 capped gap \(retryGaps[1])s")
-        }
+        #expect(!OriginRequestBudget.shared.isPaced(origin.url))
     }
 
     @Test("a stream refused for longer than the budget ends as a read error")
     func refusedPastTheBudgetGivesUp() throws {
+        AetherEngine.reconnectBackoffScaleForTesting = 0.02
+        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
+        AVIOReader.liveRefusalRetryBudgetForTesting = 1
+        defer { AVIOReader.liveRefusalRetryBudgetForTesting = nil }
         let first = Self.streamBytes(count: 400)
         let origin = try #require(ScriptedOrigin { index in
             index == 0 ? .init(status: 200, body: first) : .init(status: 509)
         })
         defer { origin.stop() }
-        AVIOReader.liveRefusalRetryBudgetForTesting = 3
-        defer { AVIOReader.liveRefusalRetryBudgetForTesting = nil }
         let reader = Self.makeLiveReader(origin.url)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
@@ -203,11 +185,13 @@ struct LiveStreamRefusalRetryTests {
 
         #expect(drained.bytes == first.count)
         #expect(drained.failure == FFmpegErr.eio)
-        // Asked about three times over the budget, one a second, then given up.
-        let refusals = origin.requestTimes.count - 1
-        #expect(refusals >= 3 && refusals <= 6, "\(refusals) refused attempts")
+        // Asked again more than the old count-based ladder's six would allow at this pace, and
+        // only given up once the budget ran out.
+        #expect(origin.requestCount - 1 >= 3, "\(origin.requestCount - 1) refused attempts")
     }
 
+    // MARK: - The open
+
     @Test("a live open the origin refuses fails typed with its status at once")
     func refusedOpenFailsTyped() throws {
         let origin = try #require(ScriptedOrigin { _ in .init(status: 509) })
@@ -215,11 +199,10 @@ struct LiveStreamRefusalRetryTests {
         let reader = Self.makeLiveReader(origin.url)
         defer { reader.markClosed(); reader.close() }
 
-        let started = Date()
         let failure = #expect(throws: AVIOReaderError.self) { try reader.open() }
         #expect(failure == .httpStatus(509))
-        #expect(Date().timeIntervalSince(started) < 5)
-        #expect(origin.requestTimes.count == 1)
+        // The one request, not the read loop's ladder on the same one.
+        #expect(origin.requestCount == 1)
     }
 
     @Test("a live open answered 403 fails typed too")
@@ -231,5 +214,6 @@ struct LiveStreamRefusalRetryTests {
 
         let failure = #expect(throws: AVIOReaderError.self) { try reader.open() }
         #expect(failure == .httpStatus(403))
+        #expect(origin.requestCount == 1)
     }
 }

From 71013c4bbb8bffde1129fb26ef2777d14fab7e27 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 06:06:56 +0200
Subject: [PATCH 093/132] docs(dovi): FEL design doc covers every Apple
 platform, names the EL filter choice

The route and the Metal composer have no platform gate; only the display half (the system applying
the attached Profile 8.1 metadata) is measured on tvOS alone, which the doc now says instead of
titling itself "on Apple TV". The chroma kernel line describes the [1 2 1] luma it actually reads,
and section 6.2 records why the EL upsampler is bilinear and which phases it uses (#795).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/dolby-vision-fel.md | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index bbadaa42a..0ddfa26e3 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -1,8 +1,15 @@
-# Dolby Vision Profile 7 FEL on Apple TV
+# Dolby Vision Profile 7 FEL
 
 How AetherEngine plays a Profile 7 dual-layer source (base layer + enhancement layer + RPU) as real
-Dolby Vision on an Apple TV 4K, what has been proven on device, and the design that does it with
-bounded CPU, GPU and memory while staying correct.
+Dolby Vision, what has been proven on device, and the design that does it with bounded CPU, GPU and
+memory while staying correct.
+
+**Platforms.** Nothing in the route or the composer is tvOS-specific: the two VideoToolbox decoders and
+the Metal kernels are the same on iOS, iPadOS and macOS, the route has no platform gate, and
+`aetherctl play --fel --surface` runs it on a Mac. What is measured per platform is the display half:
+that the system reads the per-frame Profile 8.1 attachment and applies Dolby Vision display management
+(§4.1) is established on tvOS only. On iOS, iPadOS and macOS the composed picture is correct; how the
+system presents its attached metadata there has not been measured.
 
 This is the design document for the feature. User-facing behaviour lives in [formats.md](formats.md#dolby-vision-signaling), options in
 [api.md](api.md), tools in [cli.md](cli.md).
@@ -102,8 +109,8 @@ composition fails.
 **Kernels** (`DoviShaderSource.swift`). Luma: base code → piece selection → polynomial (evaluated in
 normalized float) or MMR when the luma curve uses MMR → plus the inverse-NLQ residual of the
 enhancement-layer luma, upsampled with one hardware-bilinear fetch →
-12-bit clamp → dither → 10-bit. Chroma: base chroma plus the average of the two vertically adjacent
-luma samples (chroma siting) → MMR → plus the residual from the enhancement chroma, upsampled with one
+12-bit clamp → dither → 10-bit. Chroma: base chroma plus the base luma at the chroma site ([1 2 1] around
+the even column in each of the cell's two rows, rows averaged; DoViBaker's MMR input) → MMR → plus the residual from the enhancement chroma, upsampled with one
 hardware-bilinear fetch co-sited with the top-left luma sample (DoViBaker's phase) → dither.
 
 **Parameter ABI.** `DoviShaderSource.sharedStructs` on the GPU side, `DoviMetalParams.serialize` on
@@ -623,6 +630,15 @@ Applied: base layer (all planes, MMR luma reads base chroma), enhancement layer
 NLQ with offset, scale, threshold, shift, `vdr_in_max`), the per-component polynomial and MMR curves, the
 bit depths, and the display metadata (carried into the converted Profile 8.1 RPU).
 
+The enhancement-layer upsampler is one hardware-bilinear fetch, not DoViBaker's spline taps. The
+encoder's own filter is not carried in the RPU (`el_spatial_resampling_filter_flag` only says one was
+used), so no kernel inverts it exactly. Against the DoViBaker oracle on a fine-detail set (gratings, zone
+plate, band-limited noise) a 4-fetch Catmull-Rom lowered the per-pixel error sd by about 0.7% on luma and
+left chroma unchanged, for four times the enhancement-layer reads. `dovi_sample_el_1d` / `_2d` keep the
+texture size in their signature so a wider filter can replace bilinear without touching the callers.
+The phases are DoViBaker's: luma texel-centre aligned, chroma co-sited with the top-left luma sample in
+both axes (`DoviEnhancementUpsamplerTests`).
+
 - **Missing or CRC-failed RPU:** the frame borrows the previous real RPU's parameters for up to
   `maxBorrowedParamsRun` (3) frames in a row, then bypasses to the base layer. Reshaping and NLQ are constant
   across a scene. A frame whose RPU sets `use_prev_vdr_rpu_flag` keeps the previous mapping for as long as the

From d3b40beb8af6b0f49498a6939fce1b08e8c05b99 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 06:40:37 +0200
Subject: [PATCH 094/132] test: three suites stop asserting on a wall clock or
 the kernel's mercy

- Issue782RestartReanchorTests failed on CI with exactly the shape a missed
  detour fetch produces: the 4 s interactive budget ran out on a loaded
  runner, the read fell through to the rescue reconnect AT the landing, and
  the parse-read assertions read that as the AE#782 anchor. A 1 ms budget
  reproduces all four failed expectations locally. AVIOReader takes the
  budget as an internal init parameter (like detourIdleSeconds); the suite
  and DetourBlockIdleReleaseTests, which also needs a block to land, pass 30 s.
- LiveRequestHeaderTests renewed the token from the test task after watching
  for the first refusal, which raced the 2-retry credential ladder #792
  part 2 added after the test was written (about 3 s). The origin now renews
  on the last refusal the ladder still retries after, so the reader is
  mid-ladder on the stale token and the renewal cannot be late.
- SoftwareResidentRangesTests' purge test asserted the memory store's
  history was whole before purging it, but that history is volatile VM and
  a full suite's memory pressure had already emptied most of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 15 +++++++----
 .../DetourBlockIdleReleaseTests.swift         |  2 +-
 .../Issue782RestartReanchorTests.swift        | 13 +++++++---
 .../LiveRequestHeaderTests.swift              | 25 +++++++++++++------
 .../SoftwareResidentRangesTests.swift         |  4 ++-
 5 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index d2635a77c..9024f4ff4 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -741,8 +741,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// Effective per-fetch budget for a detour block: the tight interactive cap, never exceeding the
     /// caller's chunk budget (still-extraction passes a smaller one; it never reaches this path, but
     /// the clamp keeps the invariant). Internal so the bound is unit-tested without a live origin.
-    static func effectiveDetourBudget(chunkRequestTimeout: TimeInterval) -> TimeInterval {
-        min(detourFetchBudgetSeconds, chunkRequestTimeout)
+    static func effectiveDetourBudget(chunkRequestTimeout: TimeInterval,
+                                      cap: TimeInterval = detourFetchBudgetSeconds) -> TimeInterval {
+        min(cap, chunkRequestTimeout)
     }
 
     // Cap on CONSECUTIVE rate-limited (429/503/509) network attempts before giving up cleanly.
@@ -986,6 +987,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// the same reason `connStallTimeout` is one: a process-wide hook would leak into whatever suite
     /// runs concurrently.
     private let detourBlockIdleSeconds: TimeInterval
+    // The interactive cap on a detour fetch; tests that assert a block lands raise it, since 4 s is
+    // a wall clock a loaded runner can spend before the fetch does.
+    private let detourFetchBudget: 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
@@ -1144,7 +1148,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, detourIdleSeconds: TimeInterval? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil, sourceOpenPolicy: SourceOpenPolicy = .init(), requestHeaderStore: RequestHeaderStore? = 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, detourFetchBudget: TimeInterval? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil, sourceOpenPolicy: SourceOpenPolicy = .init(), requestHeaderStore: RequestHeaderStore? = nil) {
         self.sourceOpenPolicy = sourceOpenPolicy
         self.probeControl = probeControl
         self.probeRequestSession = probeControl == nil ? nil : probeRequestSession
@@ -1167,6 +1171,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             ?? (isLive ? Self.liveWinHighWaterDefault : Self.winHighWaterDefault))
         self.streamHighWater = max(1, streamHighWater ?? Self.streamHighWaterDefault)
         self.detourBlockIdleSeconds = detourIdleSeconds ?? Self.detourBlockIdleSecondsDefault
+        self.detourFetchBudget = detourFetchBudget ?? Self.detourFetchBudgetSeconds
         self.heldConnectionEnabled = heldConnection
     }
 
@@ -2891,7 +2896,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// 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 budget = Self.effectiveDetourBudget(chunkRequestTimeout: chunkRequestTimeout, cap: detourFetchBudget)
         let rangeEnd = offset + Int64(size) - 1
         var request = URLRequest(url: requestURL())
         request.setValue("bytes=\(offset)-\(rangeEnd)", forHTTPHeaderField: "Range")
@@ -3051,7 +3056,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         }
         var request = URLRequest(url: url)
         request.setValue("bytes=-\(Self.tailPrefetchBytes)", forHTTPHeaderField: "Range")
-        request.timeoutInterval = Self.effectiveDetourBudget(chunkRequestTimeout: chunkRequestTimeout)
+        request.timeoutInterval = Self.effectiveDetourBudget(chunkRequestTimeout: chunkRequestTimeout, cap: detourFetchBudget)
         applyExtraHeaders(&request)
 
         // A delegate rather than a completion handler, and the distinction is load-bearing: a
diff --git a/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift b/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift
index 283abed55..e7c618bb2 100644
--- a/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift
+++ b/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift
@@ -14,7 +14,7 @@ struct DetourBlockIdleReleaseTests {
         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)
+        let reader = AVIOReader(url: url, detourIdleSeconds: 0.2, detourFetchBudget: 30)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
diff --git a/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift b/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift
index 8bb6cf354..a9aa0fb2a 100644
--- a/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift
+++ b/Tests/AetherEngineTests/Issue782RestartReanchorTests.swift
@@ -11,6 +11,13 @@ struct Issue782RestartReanchorTests {
 
     private static let chunk = 256 * 1024
 
+    /// The detour fetch's 4 s interactive budget is a wall clock: on a loaded runner a 4 MB block
+    /// missed it, fell through to the rescue reconnect AT the landing, and the parse-read assertions
+    /// read that as the AE#782 anchor. The policy under test is where the read goes, not how fast.
+    private func makeReader(_ server: ThrottledOriginServer) -> AVIOReader {
+        AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!, detourFetchBudget: 30)
+    }
+
     private func readForward(_ reader: AVIOReader, _ buf: UnsafeMutablePointer<UInt8>, bytes: Int) -> Bool {
         var read = 0
         while read < bytes {
@@ -30,7 +37,7 @@ struct Issue782RestartReanchorTests {
     func repositionAnchorsAtLanding() throws {
         let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000, patternedBody: true))
         defer { server.stop() }
-        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        let reader = makeReader(server)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
         reader.markOpenPhaseFinished()
@@ -56,7 +63,7 @@ struct Issue782RestartReanchorTests {
     func parseReadStillDetours() throws {
         let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000, patternedBody: true))
         defer { server.stop() }
-        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        let reader = makeReader(server)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
         reader.markOpenPhaseFinished()
@@ -77,7 +84,7 @@ struct Issue782RestartReanchorTests {
     func residentBlockServesFirst() throws {
         let server = try #require(ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000, patternedBody: true))
         defer { server.stop() }
-        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        let reader = makeReader(server)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
         reader.markOpenPhaseFinished()
diff --git a/Tests/AetherEngineTests/LiveRequestHeaderTests.swift b/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
index 02620c6ca..2b51ccea0 100644
--- a/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
+++ b/Tests/AetherEngineTests/LiveRequestHeaderTests.swift
@@ -15,19 +15,30 @@ struct LiveRequestHeaderTests {
     /// An origin whose first token lapses after the opening range: "first" is served below
     /// `lapsesAt` and refused from there on, "second" is served everywhere. Tying the lapse to the
     /// offset rather than to a moment keeps the read from racing the rotation.
+    ///
+    /// The host's renewal happens here too, on the refusal numbered `renewsAtRefusal`, before that
+    /// 401 goes out. A test task that watched for the refusal and then renewed raced the reader's
+    /// credential ladder (`AVIOReader.credentialRefusalMaxStreak`, about 3 s), which a loaded
+    /// runner overran: the reader gave up before the renewal landed.
     final class TokenGate: @unchecked Sendable {
         private let lock = NSLock()
         private var refused = 0
         let lapsesAt: Int64
+        let renewsAtRefusal: Int
         weak var origin: ThrottledOriginServer?
+        var renew: (@Sendable () -> Void)?
 
-        init(lapsesAt: Int64) { self.lapsesAt = lapsesAt }
+        init(lapsesAt: Int64, renewsAtRefusal: Int) {
+            self.lapsesAt = lapsesAt
+            self.renewsAtRefusal = renewsAtRefusal
+        }
         var refusals: Int { lock.withLock { refused } }
 
         func answer(_ index: Int, offset: Int64) -> ThrottledOriginServer.Directive {
             let sent = origin?.requestHeaders[index]["authorization"]
             if sent == "Bearer second" || (sent == "Bearer first" && offset < lapsesAt) { return .serve206 }
-            lock.withLock { refused += 1 }
+            let count = lock.withLock { refused += 1; return refused }
+            if count == renewsAtRefusal { renew?() }
             return .status(401)
         }
     }
@@ -36,7 +47,9 @@ struct LiveRequestHeaderTests {
           .timeLimit(.minutes(2)))
     func refusedTokenHealsWithoutReopen() async throws {
         let firstRange: Int64 = 256 * 1024
-        let gate = TokenGate(lapsesAt: firstRange)
+        // The last refusal the ladder still retries after: the reader is mid-ladder, on the stale
+        // token, when the renewal lands.
+        let gate = TokenGate(lapsesAt: firstRange, renewsAtRefusal: AVIOReader.credentialRefusalMaxStreak)
         let originMaybe = ThrottledOriginServer(totalSize: 64 * 1024 * 1024,
                                                 respond: { index, offset, _ in gate.answer(index, offset: offset) })
         let origin = try #require(originMaybe)
@@ -44,6 +57,7 @@ struct LiveRequestHeaderTests {
         defer { origin.stop() }
 
         let store = RequestHeaderStore(["Authorization": "Bearer first"])
+        gate.renew = { store.replace(["Authorization": "Bearer second"]) }
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(origin.port)/movie.bin")!,
                                 extraHeaders: store.current,
                                 boundedInitialFetch: firstRange,
@@ -66,12 +80,9 @@ struct LiveRequestHeaderTests {
             delivered.finish(got)
         }
 
-        // The reader has met the refusal and is in its reconnect ladder before the host renews.
-        try await waitFor { gate.refusals >= 1 }
-        store.replace(["Authorization": "Bearer second"])
-
         try await waitFor { delivered.total != nil }
         #expect(delivered.total == target, "the read healed past the refusal instead of failing")
+        #expect(gate.refusals == AVIOReader.credentialRefusalMaxStreak, "the renewal landed mid-ladder")
         let sent = origin.requestHeaders.map { $0["authorization"] }
         #expect(sent.last == "Bearer second", "the healing request carried the renewed token")
         // One reader all the way through: the same AVIOReader was never reopened, it only reconnected.
diff --git a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
index 81c5a3a8c..7b00968c4 100644
--- a/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
+++ b/Tests/AetherEngineTests/SoftwareResidentRangesTests.swift
@@ -122,7 +122,9 @@ struct SoftwareResidentRangesTests {
         let source = try source(packets, store: store)
         defer { source.close() }
         try await consume(source, expecting: packets, fails: false)
-        #expect(source.residentRanges == [0...16])
+        // The history is volatile VM, so under a full suite's memory pressure the kernel may already
+        // have emptied some of it here (seen: [15.36...16]); the purge below forces the rest.
+        #expect(source.residentRanges.last?.upperBound == 16)
         store.purgeHistoryForTesting()
         let spans = source.residentRanges
         #expect((spans.first?.lowerBound ?? 0) > 0)

From bd5d5fa40e41cfa33a45b4b982753153f25bcb80 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 06:45:38 +0200
Subject: [PATCH 095/132] fix(software): the live join's placement yields to a
 seek that landed first

The feeder decided the placement and then wrote the cursor unconditionally,
so a seek between the two had its target overwritten by the join. The write
is now compare-and-set on the seek generation the feeder iteration read, and
the placement is logged only when it took. Follow-up to #797.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/SoftwarePlaybackHost.swift         | 26 +++++++++++++++----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index aeea19bd9..bd3c8fe16 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -475,6 +475,23 @@ final class SoftwarePlaybackHost {
         demuxCondition.unlock()
     }
 
+    /// The live join's placement (#797), compare-and-set on the seek generation: a seek that landed
+    /// between the feeder's decision and this write already moved the cursor where the viewer asked.
+    nonisolated private func placeFeedCursor(_ value: Int, ifGeneration generation: UInt64) -> Bool {
+        feedLock.lock()
+        guard _seekGeneration == generation else {
+            feedLock.unlock()
+            return false
+        }
+        _feedCursor = value
+        feedLock.unlock()
+        audioLookahead.reset(to: value)
+        demuxCondition.lock()
+        demuxCondition.broadcast()
+        demuxCondition.unlock()
+        return true
+    }
+
     nonisolated private var dvrRecoveryPending: Bool {
         feedLock.lock(); defer { feedLock.unlock() }
         return _dvrRecoveryTicket != nil
@@ -2234,8 +2251,8 @@ final class SoftwarePlaybackHost {
                                                    newestPts: self.newestSourcePts,
                                                    at: ProcessInfo.processInfo.systemUptime)
             }
-            let placeCursor: @Sendable (Int) -> Void = { [weak self] seq in
-                self?.setFeedCursor(seq)
+            let placeCursor: @Sendable (Int, UInt64) -> Bool = { [weak self] seq, generation in
+                self?.placeFeedCursor(seq, ifGeneration: generation) ?? false
             }
             let setSourceEnded: @Sendable () -> Void = { [weak self] in
                 self?.sourceEnded = true
@@ -2562,7 +2579,7 @@ final class SoftwarePlaybackHost {
         advanceCursor: @Sendable (Int) -> Void,
         recoverCursor: @Sendable (Int) -> Void,
         liveJoinPlacement: @Sendable () -> SoftwareLiveJoinPolicy.Decision? = { .fromStart },
-        placeCursor: @Sendable (Int) -> Void = { _ in },
+        placeCursor: @Sendable (Int, UInt64) -> Bool = { _, _ in false },
         seekGeneration: @Sendable () -> UInt64,
         currentRate: @Sendable () -> Float,
         isPlaying: @Sendable () -> Bool,
@@ -2736,7 +2753,7 @@ final class SoftwarePlaybackHost {
                     liveJoinPending = false
                     let cursor = readCursor()
                     if let seq = ring.seq(forKeyframeAtOrBefore: targetPts), seq > cursor,
-                       let keyframe = ring.packet(atSeq: seq) {
+                       let keyframe = ring.packet(atSeq: seq), placeCursor(seq, generation) {
                         let skipped = keyframe.pts - (ring.packet(atSeq: cursor)?.pts ?? keyframe.pts)
                         EngineLog.emit(
                             "[SWHost] live join placed \(String(format: "%.1f", SoftwareLiveJoinPolicy.leadSeconds))s "
@@ -2744,7 +2761,6 @@ final class SoftwarePlaybackHost {
                             + "connect burst (cursor seq=\(cursor) -> \(seq), keyframe pts=\(String(format: "%.2f", keyframe.pts)))",
                             category: .swPlayback
                         )
-                        placeCursor(seq)
                         return true
                     }
                 }

From cc71691f0dea9fb87335c4c07a1868c38d88018c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 07:38:01 +0200
Subject: [PATCH 096/132] fix(live): a live open's server error is asked once
 more before it fails typed

#796 throws a live open's first 4xx/5xx typed at once. Before it, the read loop
gave a hard 5xx on a never-productive source one more attempt, which is what a
500 or 502 during a tuner or transcode spin-up needs. Refusals (429/503/509) and
4xx still fail at once. The live refusal budget's test seam is now read once at
reader init, like the other reader hooks, so a parallel test cannot change it
under a running reader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  3 +-
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 19 ++++++++++-
 .../LiveStreamRefusalRetryTests.swift         | 32 +++++++++++++++++++
 3 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bcb5e62f4..5b167a0d0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,7 +37,8 @@ the public-API contract.
   live open the origin answers with a status fails typed with that status at once
   (`AVIOReaderError.httpStatus`, `sourceRateLimited` or `sourceRefused` at the host), where the read
   loop used to spend the open budget on the same request and hand back an untyped read failure.
-  `LiveStreamRefusalRetryTests`.
+  A server error that is not a refusal (a 500 or 502 while a tuner spins up) is asked once more
+  first, as the read loop did. `LiveStreamRefusalRetryTests`.
 - **Profile 7 FEL chroma residual is sampled where the base chroma sits.** With a quarter-resolution
   enhancement layer (1080p under 4K), the chroma kernel read the enhancement chroma at texel centres,
   a quarter of an EL chroma texel up and to the left of the co-sited (top-left) chroma location HDR
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index a78912727..1ef1d4ce7 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -775,6 +775,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// How long a live stream keeps asking before the refusal is the session's answer.
     static let liveRefusalRetryBudget: TimeInterval = 60
     /// Test seam: a shorter budget, so the give-up is exercised without a minute of wall clock.
+    /// Read once per reader, at init.
     nonisolated(unsafe) static var liveRefusalRetryBudgetForTesting: TimeInterval?
 
     /// The wait before a live stream's refused request is made again: a second, or the origin's
@@ -1141,6 +1142,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// #392: the idle gap this reader takes a first refusal at face value after. Shipped value
     /// unless a test shortens it, captured once at init like the two hooks above.
     private let pinIdleSeconds: TimeInterval
+    /// How long a live refusal streak is ridden out, captured once at init like the hooks above.
+    private let liveRefusalRetryBudgetSeconds: TimeInterval
     /// Stall threshold this reader runs with, `connStallTimeoutDefault` unless a caller overrides it.
     /// One value for both detectors, because they are one policy: a connection that has delivered
     /// nothing for this long is replaced, whether or not a read is waiting on it (#309).
@@ -1200,6 +1203,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         self.throttleKbps = AetherEngine.sourceThrottleKbpsForTesting
         self.backoffScale = AetherEngine.reconnectBackoffScaleForTesting
         self.pinIdleSeconds = AetherEngine.pinIdleSecondsForTesting ?? Self.pinIdleRepinSecondsDefault
+        self.liveRefusalRetryBudgetSeconds = Self.liveRefusalRetryBudgetForTesting ?? Self.liveRefusalRetryBudget
         self.connStallTimeout = max(0.05, connStallTimeout)
         self.winHighWater = max(1, windowHighWater
             ?? (isLive ? Self.liveWinHighWaterDefault : Self.winHighWaterDefault))
@@ -1326,6 +1330,19 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 // way the live HLS ingest reports a refused join: the host retries a 509 on its own
                 // cadence with the right words for it, where the read loop's ladder would have spent
                 // the open budget on the same request and handed back an untyped read failure.
+                // A server error is asked once more first, as the read loop did before this was typed:
+                // a 500/502 while a tuner or transcode spins up is the moment's, not the channel's.
+                if !opened, isLive, let refusal = refusalOfLiveOpenConnection(),
+                   Self.isResolvedHardServerError(refusal) {
+                    EngineLog.emit(
+                        "[AVIOReader] \(label) live open answered status=\(refusal); asking once more",
+                        category: .demux)
+                    backoffBeforeReconnect(streak: 1, retryAfter: 0)
+                    try probeControl?.check()
+                    guard !isClosed else { throw CancellationError() }
+                    startPersistentConnection(at: 0, boundedTo: boundedInitialFetch)
+                    opened = awaitFirstPersistentData()
+                }
                 if !opened, isLive, let refusal = refusalOfLiveOpenConnection() {
                     EngineLog.emit(
                         "[AVIOReader] \(label) live open refused status=\(refusal); failing the open typed",
@@ -2875,7 +2892,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             let now = DispatchTime.now()
             let started = rateLimitStreakStartedAt ?? now
             rateLimitStreakStartedAt = started
-            let budget = Self.liveRefusalRetryBudgetForTesting ?? Self.liveRefusalRetryBudget
+            let budget = liveRefusalRetryBudgetSeconds
             let elapsed = Double(now.uptimeNanoseconds &- started.uptimeNanoseconds) / 1_000_000_000
             return elapsed > budget
         }
diff --git a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
index 732ff6c3c..593db234c 100644
--- a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
+++ b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
@@ -205,6 +205,38 @@ struct LiveStreamRefusalRetryTests {
         #expect(origin.requestCount == 1)
     }
 
+    @Test("a live open answered with a server error is asked once more and plays when served")
+    func serverErrorAtOpenIsAskedOnceMore() throws {
+        AetherEngine.reconnectBackoffScaleForTesting = 0.02
+        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
+        let body = Self.streamBytes(count: 400)
+        let origin = try #require(ScriptedOrigin { index in
+            index == 0 ? .init(status: 502) : .init(status: 200, body: body)
+        })
+        defer { origin.stop() }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let drained = Self.drain(reader, expectedBytes: body.count)
+        #expect(drained.failure == nil)
+        #expect(drained.bytes >= body.count)
+    }
+
+    @Test("a live open answered with a server error twice fails typed with its status")
+    func serverErrorTwiceAtOpenFailsTyped() throws {
+        AetherEngine.reconnectBackoffScaleForTesting = 0.02
+        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
+        let origin = try #require(ScriptedOrigin { _ in .init(status: 500) })
+        defer { origin.stop() }
+        let reader = Self.makeLiveReader(origin.url)
+        defer { reader.markClosed(); reader.close() }
+
+        let failure = #expect(throws: AVIOReaderError.self) { try reader.open() }
+        #expect(failure == .httpStatus(500))
+        #expect(origin.requestCount == 2)
+    }
+
     @Test("a live open answered 403 fails typed too")
     func forbiddenOpenFailsTyped() throws {
         let origin = try #require(ScriptedOrigin { _ in .init(status: 403) })

From 4239cd09c444c4a2c6781ee565ca81f2f2aa21c0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 08:13:01 +0200
Subject: [PATCH 097/132] chore: clear the Swift 6.4 build warnings

- the in-band HEVC record completion discards its Bool explicitly instead of letting the
  detached closure return it into an unused .value
- channelLayoutDescription decodes its buffer instead of the deprecated String(cString: [CChar])
- aetherctl's elmode observer touches its AppKit views through MainActor.assumeIsolated
- tests: #require calls the 6.4 Testing macro flags as redundant (an optional context picks the
  non-optional overload, so they never checked anything) become the plain expression; Sendable
  captures of CVPixelBuffer, AVAssetTrack and the accept handler go through nonisolated(unsafe)
  locals; unused results are discarded with _ =

No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift                |  2 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift             |  2 +-
 Sources/AetherEngine/Native/SoftwarePlaybackHost.swift |  2 +-
 Sources/aetherctl/PlaybackCmd.swift                    |  8 +++++---
 Tests/AetherEngineTests/DoviComposeAsyncTests.swift    |  4 ++--
 Tests/AetherEngineTests/DoviFelFuzzTests.swift         |  2 +-
 Tests/AetherEngineTests/DoviPinTestTests.swift         |  4 ++--
 Tests/AetherEngineTests/HEVCCodecStringTests.swift     |  2 +-
 .../Issue460ReloadWithOptionsTests.swift               |  4 ++--
 .../LiveReopenAfterTeardownTests.swift                 |  2 +-
 Tests/AetherEngineTests/NALUnitChainTests.swift        |  2 +-
 .../SoftwarePathEscalationTests.swift                  |  6 +++---
 Tests/AetherEngineTests/SpatialAudioBridgeTests.swift  |  2 +-
 .../AetherEngineTests/StaleSessionCallbackTests.swift  |  2 +-
 .../SupersededProducerReportTests.swift                |  2 +-
 Tests/AetherEngineTests/SupersededPumpExitTests.swift  | 10 +++++-----
 Tests/AetherEngineTests/Support/LoopbackListener.swift |  1 +
 17 files changed, 30 insertions(+), 27 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 3f855ee65..50c3c70b9 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -5109,7 +5109,7 @@ public final class AetherEngine: ObservableObject {
                canHardwareDecode: nil) {
             let vIdx = probe.videoStreamIndex
             await BlockingWork.detached(priority: .userInitiated) { [probe] in
-                VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: probe, streamIndex: vIdx)
+                _ = VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: probe, streamIndex: vIdx)
             }.value
             if loadGeneration != gen {
                 probe.markClosed()
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 387695c53..fdfd98cab 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1664,7 +1664,7 @@ public final class Demuxer: @unchecked Sendable {
         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)
+        return String(decoding: buffer.prefix { $0 != 0 }.map { UInt8(bitPattern: $0) }, as: UTF8.self)
     }
 
     /// The language to publish for a stream. A disc keeps its track languages in its navigation data
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index bd3c8fe16..2f25da49a 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1044,7 +1044,7 @@ final class SoftwarePlaybackHost {
                dolbyVisionHandling: dolbyVisionHandling) {
             let vIdx = dem.videoStreamIndex
             await BlockingWork.detached(priority: .userInitiated) {
-                VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: dem, streamIndex: vIdx)
+                _ = VideoConfigRecord.completeHEVCRecordFromInBandParameterSets(demuxer: dem, streamIndex: vIdx)
             }.value
             // A stop() can land on this suspension as on the start-position seek below.
             guard !stopRequested else { return }
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 0f3826b82..d3953572c 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -650,9 +650,11 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         pv.addSubview(label)
         NotificationCenter.default.addObserver(forName: Notification.Name("aetherctl.elmode"), object: nil, queue: .main) { note in
             let text = (note.object as? String) ?? ""
-            label.stringValue = " " + text + " "
-            label.isHidden = false
-            win.title = "AetherEngine: " + text
+            MainActor.assumeIsolated {
+                label.stringValue = " " + text + " "
+                label.isHidden = false
+                win.title = "AetherEngine: " + text
+            }
         }
         win.orderFront(nil)
         engine.bind(view: pv)
diff --git a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
index e2cf13f19..77cde13ec 100644
--- a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
+++ b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
@@ -121,8 +121,8 @@ struct DoviComposeAsyncTests {
     func blockingComposeTakesAnInFlightSlot() throws {
         final class Box: @unchecked Sendable { let done = DispatchSemaphore(value: 0); var result: Bool? }
         let composer = try #require(DoviFelComposer())
-        let bl = try #require(Self.makeBuffer(width: 256, height: 256, fill: 0x8000))
-        let el = try #require(Self.makeBuffer(width: 128, height: 128, fill: 0x4000))
+        nonisolated(unsafe) let bl = try #require(Self.makeBuffer(width: 256, height: 256, fill: 0x8000))
+        nonisolated(unsafe) let el = try #require(Self.makeBuffer(width: 128, height: 128, fill: 0x4000))
         let params = Self.identityParams(blW: 256, blH: 256, elW: 128, elH: 128)
         for _ in 0..<DoviFelComposer.maxFramesInFlight { composer.acquireSlot() }
 
diff --git a/Tests/AetherEngineTests/DoviFelFuzzTests.swift b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
index 72fb9cf71..ab716d9c4 100644
--- a/Tests/AetherEngineTests/DoviFelFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
@@ -55,7 +55,7 @@ struct DoviFelFuzzTests {
         let pad = Int(AV_INPUT_BUFFER_PADDING_SIZE)
         let ref = av_buffer_alloc(bytes.count + pad)!
         memset(ref.pointee.data, 0, bytes.count + pad)
-        bytes.withUnsafeBufferPointer { memcpy(ref.pointee.data, $0.baseAddress!, bytes.count) }
+        _ = bytes.withUnsafeBufferPointer { memcpy(ref.pointee.data, $0.baseAddress!, bytes.count) }
         pkt.pointee.buf = ref
         pkt.pointee.data = ref.pointee.data
         pkt.pointee.size = Int32(bytes.count)
diff --git a/Tests/AetherEngineTests/DoviPinTestTests.swift b/Tests/AetherEngineTests/DoviPinTestTests.swift
index e78e2532c..4ef30943d 100644
--- a/Tests/AetherEngineTests/DoviPinTestTests.swift
+++ b/Tests/AetherEngineTests/DoviPinTestTests.swift
@@ -45,13 +45,13 @@ struct DoviPinTestTests {
     func thresholdRuleGivesUpAfterScanLimit() throws {
         let nal = DoviComposedFrameRpuTests.felNAL
         let hit = DoviPinTest(emit: { _ in })
-        hit.configure(try #require(DoviPinTest.parse(spec: "maxpq>=0,period:2")))
+        hit.configure(DoviPinTest.parse(spec: "maxpq>=0,period:2"))
         _ = hit.substitute(nal)
         #expect(hit.isPinned, "the fixture must parse, or the rest of this test proves nothing")
 
         let sink = Sink()
         let pin = DoviPinTest(emit: { sink.append($0) })
-        pin.configure(try #require(DoviPinTest.parse(spec: "maxpq>=4096,period:2")))
+        pin.configure(DoviPinTest.parse(spec: "maxpq>=4096,period:2"))
         for _ in 1..<DoviPinTest.thresholdScanLimit { _ = pin.substitute(nal) }
         #expect(pin.isArmed)
         _ = pin.substitute(nal)
diff --git a/Tests/AetherEngineTests/HEVCCodecStringTests.swift b/Tests/AetherEngineTests/HEVCCodecStringTests.swift
index f106db63a..9547186d9 100644
--- a/Tests/AetherEngineTests/HEVCCodecStringTests.swift
+++ b/Tests/AetherEngineTests/HEVCCodecStringTests.swift
@@ -150,7 +150,7 @@ struct HEVCCodecStringTests {
 
     @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())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         let cp = codecpar!
         cp.pointee.codec_type = AVMEDIA_TYPE_VIDEO
diff --git a/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift b/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift
index 67f75c87e..a517e8c19 100644
--- a/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift
+++ b/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift
@@ -160,7 +160,7 @@ struct Issue460ReloadWithOptionsTests {
 
         // Refused for the session, not for the fields: the tuning change rides along and must not
         // survive a reload that never happened.
-        try? await engine.reloadAtCurrentPosition {
+        _ = try? await engine.reloadAtCurrentPosition {
             $0.autoplay = false
             $0.teletextPage = 888
         }
@@ -178,7 +178,7 @@ struct Issue460ReloadWithOptionsTests {
 
         var seenHeader: String?
         var seenMatchContent: Bool?
-        try? await engine.reloadAtCurrentPosition {
+        _ = try? await engine.reloadAtCurrentPosition {
             seenHeader = $0.httpHeaders["Authorization"]
             seenMatchContent = $0.matchContentEnabled
         }
diff --git a/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift b/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift
index b2754936f..007a81bb7 100644
--- a/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift
+++ b/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift
@@ -10,7 +10,7 @@ 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())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         codecpar!.pointee.codec_id = AV_CODEC_ID_H264
         codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
diff --git a/Tests/AetherEngineTests/NALUnitChainTests.swift b/Tests/AetherEngineTests/NALUnitChainTests.swift
index 8c15c7e2d..f5bb415b4 100644
--- a/Tests/AetherEngineTests/NALUnitChainTests.swift
+++ b/Tests/AetherEngineTests/NALUnitChainTests.swift
@@ -169,7 +169,7 @@ struct NALUnitChainTests {
                 audio: nil, onInitCaptured: { _ in })
         }
         func write(_ bytes: [UInt8], to muxer: MP4SegmentMuxer) throws {
-            var packet: UnsafeMutablePointer<AVPacket>? = try #require(trackedPacketAlloc())
+            var packet: UnsafeMutablePointer<AVPacket>? = trackedPacketAlloc()
             defer { trackedPacketFree(&packet) }
             let pkt = packet!
             #expect(av_new_packet(pkt, Int32(bytes.count)) >= 0)
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index 4056969c1..cfc99b662 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -89,7 +89,7 @@ struct SoftwarePathEscalationTests {
         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"))
+        engine.loadedURL = URL(string: "http://127.0.0.1:\(origin.port)/source.mkv")
 
         let escalation = Task { @MainActor in
             await engine.escalateToSoftwarePath(SoftwarePathEscalation.Request(
@@ -150,7 +150,7 @@ struct SoftwarePathEscalationTests {
         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"))
+        engine.loadedURL = 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.
@@ -182,7 +182,7 @@ struct SoftwarePathEscalationTests {
     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"))
+        engine.loadedURL = 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) }
diff --git a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
index cdd29532a..0c671333c 100644
--- a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
@@ -502,7 +502,7 @@ struct SpatialAudioBridgeTests {
         try (muxed.initBytes + Data(contentsOf: muxed.segment)).write(to: file)
 
         let asset = AVURLAsset(url: file)
-        let track = try #require(try await asset.loadTracks(withMediaType: .audio).first)
+        nonisolated(unsafe) 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.
diff --git a/Tests/AetherEngineTests/StaleSessionCallbackTests.swift b/Tests/AetherEngineTests/StaleSessionCallbackTests.swift
index 13fda7e65..057989bde 100644
--- a/Tests/AetherEngineTests/StaleSessionCallbackTests.swift
+++ b/Tests/AetherEngineTests/StaleSessionCallbackTests.swift
@@ -23,7 +23,7 @@ struct StaleSessionCallbackTests {
     @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"))
+        engine.loadedURL = 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) }
diff --git a/Tests/AetherEngineTests/SupersededProducerReportTests.swift b/Tests/AetherEngineTests/SupersededProducerReportTests.swift
index e5ed112ba..d935093ca 100644
--- a/Tests/AetherEngineTests/SupersededProducerReportTests.swift
+++ b/Tests/AetherEngineTests/SupersededProducerReportTests.swift
@@ -20,7 +20,7 @@ struct SupersededProducerReportTests {
         init() throws {
             engine = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/superseded.mkv"),
                                     dvModeAvailable: false)
-            codecpar = try #require(avcodec_parameters_alloc())
+            codecpar = 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
diff --git a/Tests/AetherEngineTests/SupersededPumpExitTests.swift b/Tests/AetherEngineTests/SupersededPumpExitTests.swift
index bea6553ea..023cf26a2 100644
--- a/Tests/AetherEngineTests/SupersededPumpExitTests.swift
+++ b/Tests/AetherEngineTests/SupersededPumpExitTests.swift
@@ -72,7 +72,7 @@ struct SupersededPumpExitTests {
 
     @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())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         codecpar!.pointee.codec_id = AV_CODEC_ID_H264
         codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
@@ -95,7 +95,7 @@ struct SupersededPumpExitTests {
 
     @Test("a replay exit retunes only the current producer, never a superseded channel")
     func replayExitRequiresCurrentProducer() throws {
-        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         codecpar!.pointee.codec_id = AV_CODEC_ID_H264
         codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
@@ -117,7 +117,7 @@ struct SupersededPumpExitTests {
 
     @Test("verified replay exhaustion cannot silently request a reload that loses its history")
     func replayExhaustionHasSeparateHostEvidence() throws {
-        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         codecpar!.pointee.codec_id = AV_CODEC_ID_H264
         codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
@@ -145,7 +145,7 @@ struct SupersededPumpExitTests {
 
     @Test("without a host that owns the retry, exhausted replay is a source reset")
     func replayExhaustionFallsBackToSourceReset() throws {
-        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         codecpar!.pointee.codec_id = AV_CODEC_ID_H264
         codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
@@ -164,7 +164,7 @@ struct SupersededPumpExitTests {
 
     @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())
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = avcodec_parameters_alloc()
         defer { avcodec_parameters_free(&codecpar) }
         codecpar!.pointee.codec_id = AV_CODEC_ID_H264
         codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
diff --git a/Tests/AetherEngineTests/Support/LoopbackListener.swift b/Tests/AetherEngineTests/Support/LoopbackListener.swift
index 5c194eb9b..95bef39ce 100644
--- a/Tests/AetherEngineTests/Support/LoopbackListener.swift
+++ b/Tests/AetherEngineTests/Support/LoopbackListener.swift
@@ -56,6 +56,7 @@ final class LoopbackListener: @unchecked Sendable {
     /// to `SO_NOSIGPIPE`, and owns it from then on; it returns false to end the loop. It is never
     /// called once `stop()` has run.
     func start(_ onAccept: @escaping (Int32) -> Bool) {
+        nonisolated(unsafe) let onAccept = onAccept
         Thread.detachNewThread { [self] in acceptLoop(onAccept) }
     }
 

From ede2539d9ca968ab8da12fdcd0ea1a29985ed689 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 08:54:57 +0200
Subject: [PATCH 098/132] fix(deps): LibDTSX 2.0.0, a dynamic framework under
 the LGPL

LibDTSX compiles in harletty-bridge's `dca` crate, which is labelled
Apache-2.0 but is a port of FFmpeg's LGPL-2.1-or-later dca decoder, so the
built library is LGPL-3.0-or-later and was linked statically into every host
(#798). 2.0.0 ships DTSX.framework, dynamic, exporting only the C API, which
Xcode embeds next to the FFmpeg frameworks; same decoder, bit-identical
output. The README's license section says what a host now receives.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Package.resolved | 6 +++---
 Package.swift    | 7 ++++---
 README.md        | 4 ++--
 3 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/Package.resolved b/Package.resolved
index ec0c324b3..1ffc1070f 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "a663fca4626d82f009da9299baa967b3baccc87955a9a0c978003f268b8503c6",
+  "originHash" : "8a36d413c7871a759c82699c06441188691f92960e77d298fe53a8d75b9265f2",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
@@ -24,8 +24,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/superuser404notfound/LibDTSX",
       "state" : {
-        "revision" : "9906f8fe9b72eb4d79a85754adbba6fa52cfe7b2",
-        "version" : "1.0.1"
+        "revision" : "1f0dd2daaaeb899b694e8502a5bb6f570046f4f3",
+        "version" : "2.0.0"
       }
     },
     {
diff --git a/Package.swift b/Package.swift
index c8190e1b4..e8d685dc9 100644
--- a/Package.swift
+++ b/Package.swift
@@ -73,9 +73,10 @@ let package = Package(
         .package(url: "https://github.com/superuser404notfound/LibTrueHD", .upToNextMinor(from: "2.3.0")),  // 2.3.0: decodes about a third faster again (harletty's truehd speed work: blocks decoded in place, table-driven Huffman, vectorised prediction filters, whole-block matrices; truehdd#42 included), byte-identical output; 2.2.1: rust_eh_personality exported weak, so it coalesces with LibDovi's copy and a host with its own Objective-C and C++ stays within compact unwind's three personality routines (#752); same decoder; 2.2.0: decodes about 30% faster (the truehd crate with its block and PCM buffers sized to the samples they hold, truehdd#42, from a fork of upstream main until that is merged), byte-identical output; 2.1.0: x86_64 in the iOS simulator slice, so a generic iOS Simulator build of a host links; same decoder; 2.0.0: transferred from Silo-Server/SiloObjectAudio and renamed (product TrueHD), rebuilt from source; same decoder as SiloObjectAudio 1.0.0
         // DTS:X decoder for `objectAudioRendering`: lossless DTS-HD MA with the encoder's height and object
         // folds removed from the bed, the fixed heights, and the alternate presentations' objects placed in
-        // the same room coordinates as LibTrueHD's. The Rust `dca` crate (Apache-2.0) behind a C API,
-        // prebuilt as an xcframework like LibTrueHD. Pinned to the minor for the same reason.
-        .package(url: "https://github.com/superuser404notfound/LibDTSX", .upToNextMinor(from: "1.0.1")),  // 1.0.1: rust_eh_personality weak (#752); dca 0.8.0 (harletty-bridge a717bae); the first two frames after a start or seek only prime the decoder
+        // the same room coordinates as LibTrueHD's. The Rust `dca` crate behind a C API, a port of FFmpeg's
+        // LGPL-2.1-or-later dca decoder, so the built library is LGPL-3.0-or-later and ships as a dynamic
+        // framework the app embeds, like FFmpegBuild's (#798). Pinned to the minor for the same reason.
+        .package(url: "https://github.com/superuser404notfound/LibDTSX", .upToNextMinor(from: "2.0.0")),  // 2.0.0: DTSX.framework, dynamic, exporting only the C API, with dSYMs; NOTICE states the LGPL; same decoder, bit-identical output (#798); 1.0.1: rust_eh_personality weak (#752); dca 0.8.0 (harletty-bridge a717bae); the first two frames after a start or seek only prime the decoder
     ],
     targets: [
         .target(
diff --git a/README.md b/README.md
index f25a49f43..3830a19cc 100644
--- a/README.md
+++ b/README.md
@@ -694,12 +694,12 @@ The exception covers AetherEngine's own code; it does not extend to its dependen
 
 **LibTrueHD** ([superuser404notfound/LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) reaches your app as a static library and decodes TrueHD for `objectAudioRendering`. Its C API, framer and packaging are MIT (Copyright Quick104, who wrote it for Silo as SiloObjectAudio, and Vincent Herbst). It compiles in the `truehd` and `oamd` crates from [truehdd](https://github.com/truehdd/truehdd), Copyright Rainbaby and the truehdd contributors, under the Apache License 2.0, which asks for the license text and LibTrueHD's `NOTICE` to travel with the binary. Apache-2.0 combines with the engine's LGPL-3.0. It comes in through the `TrueHDObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it ([Package traits](#package-traits)).
 
-**LibDTSX** ([superuser404notfound/LibDTSX](https://github.com/superuser404notfound/LibDTSX)) reaches your app as a static library and decodes DTS:X for `objectAudioRendering`. Its C API, framing and packaging are Apache-2.0, and it compiles in the `dca` crate from [harletty-bridge](https://github.com/harletty/harletty-bridge), also under the Apache License 2.0, which asks for the license text and LibDTSX's `NOTICE` to travel with the binary. It comes in through the `DTSXObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it.
+**LibDTSX** ([superuser404notfound/LibDTSX](https://github.com/superuser404notfound/LibDTSX)) reaches your app as a **dynamic framework**, `DTSX.framework`, which Xcode embeds in `YourApp.app/Frameworks/` next to the FFmpeg frameworks, and decodes DTS:X for `objectAudioRendering`. Its C API, framing and packaging are Apache-2.0, and it compiles in the `dca` crate from [harletty-bridge](https://github.com/harletty/harletty-bridge), which is labelled Apache-2.0 but is a port of FFmpeg's LGPL-2.1-or-later `dca` decoder. The built library is therefore LGPL-3.0-or-later, and it stays a separate, replaceable framework for the same reason the FFmpeg frameworks do (#798); LibDTSX's `NOTICE` and `LICENSES/` travel with the binary. It comes in through the `DTSXObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it.
 
 **SMBClient** ([kishikawakatsumi/SMBClient](https://github.com/kishikawakatsumi/SMBClient), MIT) reaches your app only if you link the `AetherEngineSMB` product. Linking `AetherEngine` alone pulls in none of its symbols, even though SwiftPM still records the package in `Package.resolved`, which describes the resolved graph rather than what the linker kept.
 
 ### Linking the engine statically
 
-An SPM library product links statically by default, and for the engine itself that is the intended shape on the App Store path. LGPL-3.0 section 4(d)(0) would otherwise ask for your application's object code in a relinkable form; the exception's fourth bullet names end-user re-linking explicitly, so that half does not apply. What the exception does not waive is the source side: point at the exact tag you built against rather than the repository root, and if you patched the engine, publish the patched source under LGPL. No separate written offer is needed while that pointer resolves. The dependencies above keep their own terms either way, which is why the FFmpeg frameworks have to stay dynamically embedded in `YourApp.app/Frameworks/` instead of merged into the app binary.
+An SPM library product links statically by default, and for the engine itself that is the intended shape on the App Store path. LGPL-3.0 section 4(d)(0) would otherwise ask for your application's object code in a relinkable form; the exception's fourth bullet names end-user re-linking explicitly, so that half does not apply. What the exception does not waive is the source side: point at the exact tag you built against rather than the repository root, and if you patched the engine, publish the patched source under LGPL. No separate written offer is needed while that pointer resolves. The dependencies above keep their own terms either way, which is why the FFmpeg frameworks and `DTSX.framework` have to stay dynamically embedded in `YourApp.app/Frameworks/` instead of merged into the app binary.
 
 Being dynamic is not the same as being reached. The engine calls `avcodec_*` as ordinary external symbols, so a second FFmpeg elsewhere in the app can serve them instead: a static archive pulled in with `-force_load` becomes a definition inside your executable and beats every dylib, and a dependency that exports the same symbols (libVLC does, and CocoaPods sorts a pod ahead of a vendored framework) wins on order alone. Link AetherEngine's frameworks first. `nm -m <executable> | grep _avcodec_find_encoder` says who currently wins; the engine's own startup line says the same thing from the inside.

From 5aca5539b9bc0f88d56fd75a67e28d8852fca430 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 09:11:26 +0200
Subject: [PATCH 099/132] fix(live): retain the outgoing video tail when audio
 opens the replay check

A reconnect whose returning audio rolls back before the outgoing
connection's last pictures leave the PES parser opened the overlap
without a held damaged boundary. The flagged picture and its unflagged
truncated successor stayed beyond the retained video frontier, so the
returning copy of the first committed the batch and the returning copy
of the truncated one was published after it with a bumped DTS
(AE#747, cut 2 of 3 on an Apple TV, superseded=0).

While no returning video has matched yet, a video packet past the
frontier is now an outgoing straggler: it raises the retained frontier
and joins the pending signatures, bounded like a held boundary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 10 +++++
 .../Video/LivePacketReplayGuard.swift         | 22 ++++++++++-
 .../LivePacketReplayGuardTests.swift          | 38 +++++++++++++++++++
 3 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b167a0d0..3d36e7e8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,16 @@ the public-API contract.
 
 ### Fixed
 
+- **A live reconnect whose audio returns first no longer publishes a picture twice.** When the
+  returning connection's audio opened the replay check before the outgoing connection's last pictures
+  left the PES parser (a flagged picture and its unflagged, truncated successor), those pictures were
+  not part of the held boundary. The returning copy of the first one committed the batch, the
+  returning copy of the truncated one arrived after it, and the producer published both and bumped the
+  second DTS, which poisons Apple's reference chain until the next IDR. Measured on one reconnect in
+  three on an Apple TV (AE#747, `superseded=0`). Such a tail now raises the retained video frontier,
+  bounded like a held damaged boundary, so the returning copies land in the verified batch and replace
+  the outgoing ones. `LivePacketReplayGuardTests`.
+
 - **A live stream read off its URL and refused for a while keeps its session.** The continuous
   MPEG-TS form of an IPTV channel is one connection for as long as it plays, and a connection-limited
   panel answers its reconnects with 509 while another device on the account holds the last slot, for
diff --git a/Sources/AetherEngine/Video/LivePacketReplayGuard.swift b/Sources/AetherEngine/Video/LivePacketReplayGuard.swift
index e38a73bc2..b4d77f40e 100644
--- a/Sources/AetherEngine/Video/LivePacketReplayGuard.swift
+++ b/Sources/AetherEngine/Video/LivePacketReplayGuard.swift
@@ -61,7 +61,7 @@ struct LivePacketReplayGuard {
     }
 
     private struct Overlap {
-        let videoFrontier: Int64
+        var videoFrontier: Int64
         let admittedVideoFrontier: Int64
         let audioFrontier: Int64
         let requiresAudioMatch: Bool
@@ -79,6 +79,8 @@ struct LivePacketReplayGuard {
         var firstUnmatchedAudioSeconds: Double?
         var containsUnmatchedPackets = false
         var pendingVideoSignatures: Set<Signature> = []
+        var outgoingVideoTailSeconds: Double?
+        var outgoingVideoTailPackets = 0
     }
 
     private struct DamagedBoundary {
@@ -270,6 +272,24 @@ struct LivePacketReplayGuard {
             return Decision(drop: false, event: .mismatch(
                 videoPackets: current.videoPackets, audioPackets: current.audioPackets))
         }
+        if signature.stream == .video, current.videoPackets == 0, signature.dts > current.videoFrontier {
+            // Returning audio can open the overlap while the outgoing connection's last
+            // pictures are still inside the PES parser. Retain them like a held boundary,
+            // so their returning copies land in the same verified batch instead of after it.
+            let start = current.outgoingVideoTailSeconds ?? sourceSeconds
+            if sourceSeconds >= start,
+               sourceSeconds - start <= Swift.max(Self.maximumUnmatchedSeconds, 2 * (videoCadence.cadence ?? 0))
+                + timeBaseSeconds,
+               current.outgoingVideoTailPackets < Self.maximumUnmatchedPackets {
+                current.outgoingVideoTailSeconds = start
+                current.outgoingVideoTailPackets += 1
+                current.videoFrontier = signature.dts
+                if isCorrupt { current.containsUnmatchedPackets = true }
+                else { current.pendingVideoSignatures.insert(signature) }
+                overlap = current
+                return Decision(drop: false, event: nil)
+            }
+        }
         if signature.stream == .video, signature.dts > current.admittedVideoFrontier,
            signature.dts <= current.videoFrontier, !current.pendingVideoSignatures.contains(signature) {
             // The intact replacement for the damaged picture was never admitted.
diff --git a/Tests/AetherEngineTests/LivePacketReplayGuardTests.swift b/Tests/AetherEngineTests/LivePacketReplayGuardTests.swift
index cd683e227..8e43310bc 100644
--- a/Tests/AetherEngineTests/LivePacketReplayGuardTests.swift
+++ b/Tests/AetherEngineTests/LivePacketReplayGuardTests.swift
@@ -170,6 +170,44 @@ final class LivePacketReplayGuardTests: XCTestCase {
         }
         XCTAssertFalse(guard_.isDroppingReplay)
     }
+    /// AE#747, cut 2 on an Apple TV: returning audio opened the overlap before the outgoing
+    /// connection's flagged picture and its unflagged truncated successor left the parser.
+    func testAudioOpenedOverlapRetainsTheOutgoingVideoTailUntilItsReturningCopies() {
+        var guard_ = LivePacketReplayGuard()
+        for tick in 0..<600 {
+            if tick < 598 { guard_.record(packet(.video, Int64(tick)), sourceSeconds: Double(tick) / 25) }
+            guard_.record(packet(.audio, Int64(tick)), sourceSeconds: Double(tick) / 25)
+        }
+        func inspect(_ value: LivePacketReplayGuard.Signature, corrupt: Bool = false) -> LivePacketReplayGuard.Decision {
+            guard_.inspect(value, sourceSeconds: Double(value.dts) / 25, timeBaseSeconds: 0.04,
+                videoFrontier: 597, audioFrontier: 599, hasAudio: true, isCorrupt: corrupt)
+        }
+        XCTAssertEqual(inspect(packet(.audio, 300)).event, .began)
+        let flagged = inspect(packet(.video, 598), corrupt: true)
+        let truncated = inspect(packet(.video, 599, payload: 0xFF))
+        XCTAssertFalse(flagged.drop)
+        XCTAssertFalse(truncated.drop)
+        for tick in 300..<598 {
+            XCTAssertTrue(inspect(packet(.video, Int64(tick))).drop)
+            XCTAssertTrue(inspect(packet(.audio, Int64(tick + 1))).drop)
+        }
+        XCTAssertTrue(inspect(packet(.audio, 598)).drop)
+        XCTAssertTrue(inspect(packet(.audio, 599)).drop)
+        XCTAssertNil(inspect(packet(.audio, 600)).event)
+        let returning598 = inspect(packet(.video, 598))
+        let returning599 = inspect(packet(.video, 599))
+        XCTAssertNil(returning598.event, "the outgoing tail's returning copy must not commit the batch")
+        XCTAssertFalse(returning598.drop)
+        XCTAssertNil(returning599.event, "a returning copy committed after the batch is bumped downstream")
+        XCTAssertFalse(returning599.drop)
+        guard case .finished = inspect(packet(.video, 600)).event else { return XCTFail("must reach new media") }
+
+        // The producer discards the flagged copy and keeps the returning picture over the truncated one.
+        let batch = [packet(.video, 599, payload: 0xFF), packet(.video, 598), packet(.video, 599), packet(.video, 600)]
+        XCTAssertEqual(LivePacketReplayGuard.verifiedPacketOrder(batch).map { batch[$0] },
+                       [packet(.video, 598), packet(.video, 599), packet(.video, 600)])
+    }
+
     func testFreshProducerContinuationRecognizesShortCachedOverlap() {
         var original = LivePacketReplayGuard()
         for tick in 0..<40 {

From 5bbeaacb5b05c9e43a62d9b8a124236633150789 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 09:28:31 +0200
Subject: [PATCH 100/132] fix(deps): LibTrueHD 2.3.1, the version string names
 the truehd commit built in

Same decoder. The CHANGELOG also gains the LibDTSX 2.0.0 entry that
ede2539d left out: hosts with DTSXObjectAudio now embed a dynamic,
LGPL-3.0-or-later DTSX.framework (#798).

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3d36e7e8b..805348eff 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,6 +23,15 @@ the public-API contract.
   still starts from its first packet. The media behind the start stays in the rewind ring.
   `SoftwareLiveJoinPolicy`, `SoftwareLiveJoinPlacementTests`.
 
+- **LibDTSX 2.0.0: `DTSX.framework` is a dynamic framework the app embeds, under the LGPL.** The
+  `dca` crate it compiles in is labelled Apache-2.0 but is a port of FFmpeg's LGPL-2.1-or-later
+  `dca` decoder, so the built library is LGPL-3.0-or-later and now ships, like the FFmpeg
+  frameworks, as a replaceable framework in `YourApp.app/Frameworks/`, exporting only the C API.
+  Same decoder, bit-identical output. A host with the `DTSXObjectAudio` trait on ships LibDTSX's
+  `NOTICE` and `LICENSES/` with the app (#798, thanks @tweakapps and @cmcpherson274).
+- **LibTrueHD 2.3.1:** `truehd_atmos_version_string()` names the `truehd` commit actually built in;
+  it still named an older one. Same decoder (LibTrueHD#2, thanks @cmcpherson274).
+
 ### Fixed
 
 - **A live reconnect whose audio returns first no longer publishes a picture twice.** When the
diff --git a/Package.resolved b/Package.resolved
index 1ffc1070f..5a54bff98 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -33,8 +33,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/superuser404notfound/LibTrueHD",
       "state" : {
-        "revision" : "577de495184254e2c660ebfd6ce3f7d97f45899d",
-        "version" : "2.3.0"
+        "revision" : "3eab2e7c10ff1b3c2078afbab138471f2511859b",
+        "version" : "2.3.1"
       }
     },
     {
diff --git a/Package.swift b/Package.swift
index e8d685dc9..86cd81a39 100644
--- a/Package.swift
+++ b/Package.swift
@@ -70,7 +70,7 @@ let package = Package(
         // TrueHD decoder that also decodes the Atmos object presentation (beds, objects, OAMD) for
         // `objectAudioRendering` (#731). The Rust `truehd` crate (Apache-2.0) behind a C API, prebuilt
         // as an xcframework like LibDovi so consumers need no Rust. Pinned to the minor for the same reason.
-        .package(url: "https://github.com/superuser404notfound/LibTrueHD", .upToNextMinor(from: "2.3.0")),  // 2.3.0: decodes about a third faster again (harletty's truehd speed work: blocks decoded in place, table-driven Huffman, vectorised prediction filters, whole-block matrices; truehdd#42 included), byte-identical output; 2.2.1: rust_eh_personality exported weak, so it coalesces with LibDovi's copy and a host with its own Objective-C and C++ stays within compact unwind's three personality routines (#752); same decoder; 2.2.0: decodes about 30% faster (the truehd crate with its block and PCM buffers sized to the samples they hold, truehdd#42, from a fork of upstream main until that is merged), byte-identical output; 2.1.0: x86_64 in the iOS simulator slice, so a generic iOS Simulator build of a host links; same decoder; 2.0.0: transferred from Silo-Server/SiloObjectAudio and renamed (product TrueHD), rebuilt from source; same decoder as SiloObjectAudio 1.0.0
+        .package(url: "https://github.com/superuser404notfound/LibTrueHD", .upToNextMinor(from: "2.3.1")),  // 2.3.1: truehd_atmos_version_string() names the truehd commit actually built in (read from Cargo.lock, LibTrueHD#2), same decoder; 2.3.0: decodes about a third faster again (harletty's truehd speed work: blocks decoded in place, table-driven Huffman, vectorised prediction filters, whole-block matrices; truehdd#42 included), byte-identical output; 2.2.1: rust_eh_personality exported weak, so it coalesces with LibDovi's copy and a host with its own Objective-C and C++ stays within compact unwind's three personality routines (#752); same decoder; 2.2.0: decodes about 30% faster (the truehd crate with its block and PCM buffers sized to the samples they hold, truehdd#42, from a fork of upstream main until that is merged), byte-identical output; 2.1.0: x86_64 in the iOS simulator slice, so a generic iOS Simulator build of a host links; same decoder; 2.0.0: transferred from Silo-Server/SiloObjectAudio and renamed (product TrueHD), rebuilt from source; same decoder as SiloObjectAudio 1.0.0
         // DTS:X decoder for `objectAudioRendering`: lossless DTS-HD MA with the encoder's height and object
         // folds removed from the bed, the fixed heights, and the alternate presentations' objects placed in
         // the same room coordinates as LibTrueHD's. The Rust `dca` crate behind a C API, a port of FFmpeg's

From 713c62a5ec0eceb52c3f6300ab6ddd4620dee0d3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 09:44:16 +0200
Subject: [PATCH 101/132] fix(sw): hold the clock until the first frames are
 queued on every VOD route (#800)

The software host started its clock on the first video packet fed (no
audio) or the first decoded audio, while the decoder was still working
from the keyframe before the target up to it. The first frames then
reached the layer late and were dropped: 0.9 s and 5 to 7 frames on a 4K
HEVC title with no audio and 10 s GOPs after an in-place switch onto the
software path, on an Apple TV 4K.

The #774 video preroll now covers every VOD software route, not only
the FEL one: the gate opens once frames up to videoPrerollSeconds
(0.125 s) past the clock are handed to the layer. A live stream off the
FEL route still starts at once.

aetherctl play --sw on a 4K 10 s GOP fixture: the clock now waits
889 ms and starts at the target, where it used to start at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 14 ++++
 Sources/AetherEngine/Audio/AudioOutput.swift  |  5 +-
 .../Native/SoftwarePlaybackHost.swift         | 10 +--
 .../Renderer/SampleBufferRenderer.swift       | 27 ++++++--
 .../AetherEngineTests/VideoPrerollTests.swift | 65 ++++++++++++++-----
 5 files changed, 92 insertions(+), 29 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 805348eff..e0a63f5af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,20 @@ the public-API contract.
 
 ### Fixed
 
+- **A software start or seek no longer runs the clock while the decoder works up to the target
+  (#800).** The software host started its clock the moment the first packet went in (video-only) or
+  the first audio decoded, while the video decoder was still working from the keyframe before the
+  target up to it, so the first frames reached the layer late and were dropped: a 4K HEVC title
+  with no audio and 10 s GOPs ran its clock 0.9 s ahead of the first frame after a switch onto the
+  software path and dropped 5 to 7 frames on an Apple TV 4K, a 1080p H.264 title with audio 0.3 s
+  and 3. Before 7.32.2 the #724 re-anchor hid this by starting the clock a whole GOP behind. The
+  video preroll #774 added for the Profile 7 FEL route now holds every VOD software route: the
+  clock waits at rate 0 until frames from its position on are in the layer
+  (`SampleBufferRenderer.videoPrerollSeconds`, 0.125 s) and then starts `prerollStartLead` from
+  now. A live stream off the FEL route still starts at once. Measured with `aetherctl play --sw` on
+  a 4K 10 s GOP fixture: `preroll ready after 889 ms; starting at t=36.600`, where the clock used to
+  start at once. Reported with measurements by @cmcpherson274. `VideoPrerollTests`.
+
 - **A live reconnect whose audio returns first no longer publishes a picture twice.** When the
   returning connection's audio opened the replay check before the outgoing connection's last pictures
   left the PES parser (a flagged picture and its unflagged, truncated successor), those pictures were
diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index 7a365d59f..feceb8351 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -407,8 +407,9 @@ final class AudioOutput: @unchecked Sendable {
     // MARK: - Video preroll
 
     /// Whether the video renderer holds enough to start the clock at a source time: nil when this
-    /// session does not preroll, so the clock starts at once as it always has. Set by the host for the
-    /// Profile 7 FEL route (`SampleBufferRenderer.felPrerollSatisfied(clock:)`).
+    /// session does not preroll, so the clock starts at once as it always has. Set by the software
+    /// host (`SampleBufferRenderer.prerollSatisfied(clock:live:)`): the FEL route since #774, every
+    /// other VOD route since #800.
     ///
     /// The video queue is filled with the timebase stopped and the clock starts only once that is done,
     /// the same idea as `AVPlayer.preroll(atRate:)`. Starting at full rate the moment
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 2f25da49a..c0dbf13b8 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1239,13 +1239,15 @@ final class SoftwarePlaybackHost {
         renderer.setTimeline(audioOutput.timeline)   // AE#395
         self.audioOutput?.volume = volume
         self.audioOutput?.setPresentationOffset(seconds: audioDelaySeconds)   // AE#464
-        // The FEL path holds the clock until composed frames are queued, then starts it a little ahead
-        // (`AudioOutput.videoPrerollSatisfied`); every other route answers nil and starts at once, and
-        // so does a session playing audio only in the background, which feeds the renderer nothing.
+        // The clock waits until frames from its position on are queued, then starts a little ahead
+        // (`AudioOutput.videoPrerollSatisfied`, #774, #800). A live stream off the FEL path starts at
+        // once, and so does a session playing audio only in the background, which feeds the renderer
+        // nothing.
         let prerollRenderer = renderer
+        let prerollLive = isLive
         self.audioOutput?.videoPrerollSatisfied = { [weak self] clock in
             guard self?.backgroundAudioOnly != true else { return nil }
-            return prerollRenderer.felPrerollSatisfied(clock: clock)
+            return prerollRenderer.prerollSatisfied(clock: clock, live: prerollLive)
         }
         // 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.
diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 5cc33d51f..68d7c8bc9 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -171,7 +171,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
     }
 
     /// How much composed video the FEL path hands the layer before the clock starts, in seconds
-    /// (`felPrerollSatisfied(clock:)`): four frames at 24 fps, which covers a decode-order burst of a
+    /// (`prerollSatisfied(clock:live:)`): four frames at 24 fps, which covers a decode-order burst of a
     /// hierarchical GOP. Measured on the Apple TV 4K (A12) with 4K FEL, the preroll completes after
     /// 90 to 100 ms at a start and 0.3 to 0.9 s after a seek.
     static let felPrerollSeconds = 0.167
@@ -184,16 +184,29 @@ final class SampleBufferRenderer: @unchecked Sendable {
         min(felPrerollSeconds, Double(felVideoLookaheadFrames - 1) / frameRate)
     }
 
-    /// The FEL path's preroll gate for `AudioOutput.videoPrerollSatisfied`: true once frames up to
-    /// `felPrerollSeconds` past `clock` (source seconds) are in the layer, nil off the FEL path. On
-    /// the arrival-order path only the frontier counts, the newest timestamp with every earlier slot
-    /// handed over, so a frame that came early past a gap does not open the gate.
-    func felPrerollSatisfied(clock: Double) -> Bool? {
+    /// How much video every other software route hands the layer before the clock starts, in seconds
+    /// past it (`prerollSatisfied(clock:live:)`): the frame at the clock and three after it at 24 fps.
+    /// Without it a start or a seek ran the clock while the decoder was still working from the keyframe
+    /// up to the target, and the first frames arrived late: 0.9 s and 5 to 7 dropped frames on a 4K
+    /// HEVC title with no audio after a 10 s GOP on an Apple TV 4K (A15), 0.3 s and 3 on 1080p H.264
+    /// with audio (#800).
+    static let videoPrerollSeconds = 0.125
+
+    /// The preroll gate for `AudioOutput.videoPrerollSatisfied`: true once frames up to the preroll
+    /// past `clock` (source seconds) are in the layer, `felPrerollSeconds` on the FEL path and
+    /// `videoPrerollSeconds` on every other one. nil for a clock with no position, and off the FEL
+    /// path on a live stream, whose join starts the clock from the first audio and lets the picture
+    /// follow. On the arrival-order path only the frontier counts, the newest timestamp with every
+    /// earlier slot handed over, so a frame that came early past a gap does not open the gate.
+    func prerollSatisfied(clock: Double, live: Bool) -> Bool? {
         reorderLock.lock()
         defer { reorderLock.unlock() }
-        guard let rate = felFrameRate, clock.isFinite else { return nil }
+        guard clock.isFinite else { return nil }
+        let rate = felFrameRate
+        if rate == nil, live { return nil }
         let handed = arrivalFloor != nil ? arrivalFloor?.frontier : _lastReleasedPtsSeconds
         guard let handed else { return false }
+        guard let rate else { return handed - clock >= Self.videoPrerollSeconds }
         return handed + 1 / rate - clock >= Self.felPrerollSeconds(frameRate: rate)
     }
 
diff --git a/Tests/AetherEngineTests/VideoPrerollTests.swift b/Tests/AetherEngineTests/VideoPrerollTests.swift
index 052def52e..4a15d9774 100644
--- a/Tests/AetherEngineTests/VideoPrerollTests.swift
+++ b/Tests/AetherEngineTests/VideoPrerollTests.swift
@@ -6,10 +6,11 @@ import os
 import Testing
 @testable import AetherEngine
 
-/// The FEL path's start: the clock waits at rate 0 until composed frames are in the layer, then
-/// starts a fixed lead from now (`AudioOutput.videoPrerollSatisfied`, `prerollStartLead`,
-/// `SampleBufferRenderer.felPrerollSatisfied(clock:)`). On an Apple TV 4K a clock started the moment
-/// the first packet arrived dropped 3 to 5 frames at every start and seek; with both, none.
+/// The software path's start: the clock waits at rate 0 until frames are in the layer, then starts a
+/// fixed lead from now (`AudioOutput.videoPrerollSatisfied`, `prerollStartLead`,
+/// `SampleBufferRenderer.prerollSatisfied(clock:live:)`). On an Apple TV 4K a clock started the moment
+/// the first packet arrived dropped 3 to 7 frames at every start and seek; with both, none on FEL
+/// (#774). Every other VOD route since #800.
 @Suite("Video preroll before the clock starts")
 struct VideoPrerollTests {
 
@@ -24,11 +25,43 @@ struct VideoPrerollTests {
 
     // MARK: - Renderer gate
 
-    @Test("Off the FEL path the renderer has no opinion, so the clock starts at once")
+    @Test("Off the FEL path the gate opens once frames reach videoPrerollSeconds past the clock")
     @MainActor
-    func noGateOffTheFELPath() {
+    func singleLayerGate() {
         let renderer = SampleBufferRenderer()
-        #expect(renderer.felPrerollSatisfied(clock: 0) == nil)
+        renderer.setReorderDepth(SampleBufferRenderer.presentationOrderReorderDepth)
+        let pixels = Self.makePixelBuffer()
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == false, "nothing handed over yet")
+        // One frame stays held for its duration, so 0 to 3 hands over 0 to 2.
+        for i in 0...3 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == false)
+        renderer.enqueue(pixelBuffer: pixels, pts: Self.time(4))
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == true)
+        #expect(renderer.prerollSatisfied(clock: Self.time(2).seconds, live: false) == false)
+    }
+
+    @Test("Off the FEL path a live stream does not preroll")
+    @MainActor
+    func singleLayerLiveHasNoGate() {
+        let renderer = SampleBufferRenderer()
+        #expect(renderer.prerollSatisfied(clock: 0, live: true) == nil)
+        renderer.setFELLookahead(enabled: true, frameRate: 24)
+        #expect(renderer.prerollSatisfied(clock: 0, live: true) == false, "the FEL route still does")
+    }
+
+    @Test("A resume between keyframes counts from the target, not from the GOP decoded up to it")
+    @MainActor
+    func singleLayerGateAfterAResume() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(SampleBufferRenderer.presentationOrderReorderDepth)
+        let pixels = Self.makePixelBuffer()
+        // #800: the keyframe sits 3 s before the target; everything up to it is decoded and skipped.
+        let target = Self.time(2078).seconds
+        renderer.setSkipThreshold(Self.time(2078))
+        for i in 2000..<2078 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        #expect(renderer.prerollSatisfied(clock: target, live: false) == false)
+        for i in 2078...2082 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
+        #expect(renderer.prerollSatisfied(clock: target, live: false) == true)
     }
 
     @Test("The gate opens once the contiguous frames reach the preroll past the clock")
@@ -38,17 +71,17 @@ struct VideoPrerollTests {
         renderer.setFELLookahead(enabled: true, frameRate: 24)
         renderer.setArrivalOrderHandover(frameRate: 24)
         let pixels = Self.makePixelBuffer()
-        #expect(renderer.felPrerollSatisfied(clock: 0) == false, "nothing handed over yet")
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == false, "nothing handed over yet")
         // A frame past a gap does not count: 0, 1, 2 and then 6 leave the frontier at frame 2.
         for i in [0, 1, 2, 6] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
-        #expect(renderer.felPrerollSatisfied(clock: 0) == false)
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == false)
         // 0 to 3 is four frames, 0.1667 s: just short of the preroll.
         renderer.enqueue(pixelBuffer: pixels, pts: Self.time(3))
-        #expect(renderer.felPrerollSatisfied(clock: 0) == false)
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == false)
         renderer.enqueue(pixelBuffer: pixels, pts: Self.time(4))
-        #expect(renderer.felPrerollSatisfied(clock: 0) == true)
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == true)
         // The same frames are not enough for a clock further on.
-        #expect(renderer.felPrerollSatisfied(clock: Self.time(4).seconds) == false)
+        #expect(renderer.prerollSatisfied(clock: Self.time(4).seconds, live: false) == false)
     }
 
     @Test("After a seek the gate counts from the seek target, not from the frames before it")
@@ -62,9 +95,9 @@ struct VideoPrerollTests {
         renderer.flush(removingDisplayedImage: false)
         renderer.setSkipThreshold(Self.time(100))
         let target = Self.time(100).seconds
-        #expect(renderer.felPrerollSatisfied(clock: target) == false)
+        #expect(renderer.prerollSatisfied(clock: target, live: false) == false)
         for i in 100..<105 { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i)) }
-        #expect(renderer.felPrerollSatisfied(clock: target) == true)
+        #expect(renderer.prerollSatisfied(clock: target, live: false) == true)
     }
 
     @Test("After a seek to a target between two frames the gate still opens without a running clock",
@@ -81,7 +114,7 @@ struct VideoPrerollTests {
         for i in PresentationFloorTests.decodeOrder(gop: 8, frames: 24, startingAt: 96) {
             renderer.enqueue(pixelBuffer: pixels, pts: Self.time(i))
         }
-        #expect(renderer.felPrerollSatisfied(clock: target) == true)
+        #expect(renderer.prerollSatisfied(clock: target, live: false) == true)
         #expect(renderer.framesBelowFloor == 0)
     }
 
@@ -100,7 +133,7 @@ struct VideoPrerollTests {
             renderer.enqueue(pixelBuffer: pixels, pts: CMTime(value: Int64(admitted), timescale: 60))
             admitted += 1
         }
-        #expect(renderer.felPrerollSatisfied(clock: 0) == true, "\(admitted) frames admitted")
+        #expect(renderer.prerollSatisfied(clock: 0, live: false) == true, "\(admitted) frames admitted")
     }
 
     // MARK: - Clock

From 80339d247625161fb0c81d240bbeef378b4d440f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 09:51:01 +0200
Subject: [PATCH 102/132] chore(release): prep 7.38.0 - a software start waits
 for its first frames, a live software join starts near the newest media,
 LibDTSX under the LGPL

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                                       | 8 ++++----
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e0a63f5af..89a4e3dfd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.38.0] - 2026-10-16
+
 ### Changed
 
 - **A live stream on the software path starts near the newest media.** A continuous live stream over
diff --git a/Examples/README.md b/Examples/README.md
index 5d93f9d34..783533d8c 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.37.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.38.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 3830a19cc..072c751ac 100644
--- a/README.md
+++ b/README.md
@@ -386,7 +386,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.37.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -633,10 +633,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.37.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.37.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.38.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
@@ -665,7 +665,7 @@ The two object-audio decoder libraries are behind package traits, both on by def
 A host that cannot ship one of the libraries turns its trait off; the library is then neither linked nor resolved (it drops out of the host's `Package.resolved`), and the session log says why the codec stayed on the bridge (`built without the TrueHDObjectAudio trait`). In a package manifest, list the traits to keep (an empty list keeps none):
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.37.0", traits: [])
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.0", traits: [])
 ```
 
 In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: []` on the package). `swift build --disable-default-traits` builds the engine itself that way.
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 76762277d..3dc72c7f5 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.37.0"
+    public nonisolated static let version = "7.38.0"
 }

From 9b16ebdfac0125e7c2a374e87bcc69cf57178995 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 10:26:30 +0200
Subject: [PATCH 103/132] fix(diag): FelResidualMeasure type-checks in time on
 Xcode 26

Xcode 26.3 gave up on the closure FelResidualMeasure hands its queue (a Release x86_64 archive of
AetherPlayer 1.0.0 failed with "unable to type-check this expression in reasonable time"): since
Swift 5.7 a multi-statement closure is checked with its body, and the body built the luma-band line
as one + chain of three map/joined expressions. The closure now calls measure(...), and the three
parts are typed constants. No behaviour change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Diagnostics/FelResidualMeasure.swift      | 40 +++++++++++--------
 1 file changed, 23 insertions(+), 17 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift b/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
index 8fc7b442d..a80500edc 100644
--- a/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
+++ b/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
@@ -34,25 +34,31 @@ enum FelResidualMeasure {
         let b = SendableBuffer(value: base), e = SendableBuffer(value: enhancement)
         queue.async {
             defer { inFlight.withLock { $0 = false } }
-            var full = params; full.ditherMode = .none; full.flags.remove(.disableResidual)
-            var mel = params; mel.ditherMode = .none; mel.flags.insert(.disableResidual)
-            guard let a = composer.compose(baseBuffer: b.value, enhancementBuffer: e.value, params: full, frameIndex: frameIndex),
-                  let m = composer.compose(baseBuffer: b.value, enhancementBuffer: e.value, params: mel, frameIndex: frameIndex)
-            else { return }
-            let planes = ["Y", "Cb", "Cr"]
-            var parts: [String] = []
-            for (k, name) in planes.enumerated() {
-                let s = stats(a, m, plane: k)
-                parts.append(String(format: "%@ diff=%.2f%% mean=%.3f signed=%+.3f p99=%d max=%d ge2=%.3f%% ge4=%.3f%%",
-                                    name, s.diffPct, s.mean, s.signedMean, s.p99, s.max, s.ge2Pct, s.ge4Pct))
-                if k == 0 {
-                    parts.append("Yband[0-255|256-511|512-767|768+] mean=" + s.bandMean.map { String(format: "%.2f", $0) }.joined(separator: "/")
-                                 + " signed=" + s.bandSignedMean.map { String(format: "%+.2f", $0) }.joined(separator: "/")
-                                 + " share%=" + s.bandFrac.map { String(format: "%.1f", $0) }.joined(separator: "/"))
-                }
+            measure(composer: composer, base: b.value, enhancement: e.value, params: params, frameIndex: frameIndex, pts: pts)
+        }
+    }
+
+    private static func measure(composer: DoviFelComposer, base: CVPixelBuffer, enhancement: CVPixelBuffer,
+                                params: DoviMetalParams, frameIndex: UInt32, pts: CMTime) {
+        var full = params; full.ditherMode = .none; full.flags.remove(.disableResidual)
+        var mel = params; mel.ditherMode = .none; mel.flags.insert(.disableResidual)
+        guard let a = composer.compose(baseBuffer: base, enhancementBuffer: enhancement, params: full, frameIndex: frameIndex),
+              let m = composer.compose(baseBuffer: base, enhancementBuffer: enhancement, params: mel, frameIndex: frameIndex)
+        else { return }
+        let planes = ["Y", "Cb", "Cr"]
+        var parts: [String] = []
+        for (k, name) in planes.enumerated() {
+            let s = stats(a, m, plane: k)
+            parts.append(String(format: "%@ diff=%.2f%% mean=%.3f signed=%+.3f p99=%d max=%d ge2=%.3f%% ge4=%.3f%%",
+                                name, s.diffPct, s.mean, s.signedMean, s.p99, s.max, s.ge2Pct, s.ge4Pct))
+            if k == 0 {
+                let mean: String = s.bandMean.map { String(format: "%.2f", $0) }.joined(separator: "/")
+                let signed: String = s.bandSignedMean.map { String(format: "%+.2f", $0) }.joined(separator: "/")
+                let share: String = s.bandFrac.map { String(format: "%.1f", $0) }.joined(separator: "/")
+                parts.append("Yband[0-255|256-511|512-767|768+] mean=\(mean) signed=\(signed) share%=\(share)")
             }
-            EngineLog.emit("[FELMeasure] pts=\(String(format: "%.3f", pts.seconds)) " + parts.joined(separator: " | "), category: .swPlayback)
         }
+        EngineLog.emit("[FELMeasure] pts=\(String(format: "%.3f", pts.seconds)) " + parts.joined(separator: " | "), category: .swPlayback)
     }
 
     private struct Stats { var diffPct = 0.0, mean = 0.0, signedMean = 0.0, p99 = 0, max = 0, ge2Pct = 0.0, ge4Pct = 0.0, bandMean = [Double](repeating: 0, count: 4), bandSignedMean = [Double](repeating: 0, count: 4), bandFrac = [Double](repeating: 0, count: 4) }

From ce1670f8c6c4b8b11a8020e9c40a10c0d6da9823 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 16 Oct 2026 10:26:30 +0200
Subject: [PATCH 104/132] chore(release): prep 7.38.1 - the package compiles in
 Release with Xcode 26 again

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89a4e3dfd..983309090 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,18 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.38.1] - 2026-10-16
+
+### Fixed
+
+- **The package compiles in Release with Xcode 26 again.** `FelResidualMeasure` (the
+  `AETHER_FEL_MEASURE` diagnostic from 7.37.0) formatted its luma-band line inside the closure it
+  hands its queue, as one `+` chain of three `map`/`joined` expressions, and Xcode 26.3's type checker
+  gave up on that closure ("unable to type-check this expression in reasonable time", x86_64 Release
+  archive), so a host archiving a universal macOS app on Xcode 26 could not build 7.37.0 or 7.38.0.
+  Xcode 27 checked it in time, which is what this repository's CI runs. The closure now calls a
+  function, and the three parts are bound to typed constants first. No behaviour change.
+
 ## [7.38.0] - 2026-10-16
 
 ### Changed
diff --git a/Examples/README.md b/Examples/README.md
index 783533d8c..4f7f7d479 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.38.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.38.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 072c751ac..25b361976 100644
--- a/README.md
+++ b/README.md
@@ -386,7 +386,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.38.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -633,10 +633,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.38.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.38.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.38.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
@@ -665,7 +665,7 @@ The two object-audio decoder libraries are behind package traits, both on by def
 A host that cannot ship one of the libraries turns its trait off; the library is then neither linked nor resolved (it drops out of the host's `Package.resolved`), and the session log says why the codec stayed on the bridge (`built without the TrueHDObjectAudio trait`). In a package manifest, list the traits to keep (an empty list keeps none):
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.0", traits: [])
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.1", traits: [])
 ```
 
 In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: []` on the package). `swift build --disable-default-traits` builds the engine itself that way.
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 3dc72c7f5..529484f2a 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.38.0"
+    public nonisolated static let version = "7.38.1"
 }

From ba44f0c80f7b0520bbbeb4be21c0f82309e2539a Mon Sep 17 00:00:00 2001
From: superuser404notfound
 <264232962+superuser404notfound@users.noreply.github.com>
Date: Fri, 16 Oct 2026 10:01:33 +0000
Subject: [PATCH 105/132] docs(used-by): add LillyPlayer

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

diff --git a/README.md b/README.md
index 25b361976..4b037d7bd 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,7 @@ You provide the transport bar. You provide the dropdowns. You provide the pretty
 - [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.
 - [GiVo Stream](https://givostreamapp.com): media player for iPhone, iPad and Apple TV with bring-your-own playlists, live timeshift, DVR and VOD.
+- [LillyPlayer](https://lillyplayer.com): The all-in-one IPTV and media player for Apple TV, iPhone and iPad (live TV, EPG, replay, Jellyfin, Plex, SMB...).
 <!-- 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 6b7017837ab322b4e776a34d09ad9e493485eb11 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 09:40:01 +0200
Subject: [PATCH 106/132] refactor(audio): compile the object renderer only
 with an object-audio trait

The renderer (ObjectAudioRenderer, AllocentricPanner, ObjectMetadataHold),
the decoder seam it renders from (ObjectAudioDecoding), BedLevelMeter and
SpatialAudioBridge exist only to place decoded objects, so they now sit
behind `TrueHDObjectAudio || DTSXObjectAudio`, like the two decoders
already did. The APAC encoder, its sample entry, the encode pipeline, the
peak limiter, the speaker layouts and the Atmos output activator stay in
every build.

The eligibility check asks whether the source's decoder is built in, so a
build without a codec's trait logs "<format> rendering requested but not
built in (<trait> trait off)" instead of the not-Atmos line, and the
bridge construction moves into a function that only exists with a trait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/Spatial/AllocentricPanner.swift     |  3 +
 .../Audio/Spatial/BedLevelMeter.swift         |  3 +
 .../Audio/Spatial/ObjectAudioDecoding.swift   |  3 +
 .../Audio/Spatial/ObjectAudioRenderer.swift   |  3 +
 .../Audio/Spatial/ObjectMetadataHold.swift    |  3 +
 .../Audio/Spatial/SpatialAudioBridge.swift    |  3 +
 .../Video/HLSVideoEngine+SpatialAudio.swift   | 60 +++++++++++++++----
 .../ObjectMetadataHoldTests.swift             |  3 +
 .../SpatialAudioBridgeTests.swift             | 13 ++++
 .../SpatialObjectRenderingTests.swift         |  3 +
 10 files changed, 86 insertions(+), 11 deletions(-)

diff --git a/Sources/AetherEngine/Audio/Spatial/AllocentricPanner.swift b/Sources/AetherEngine/Audio/Spatial/AllocentricPanner.swift
index 4674dd749..f4a6177d3 100644
--- a/Sources/AetherEngine/Audio/Spatial/AllocentricPanner.swift
+++ b/Sources/AetherEngine/Audio/Spatial/AllocentricPanner.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait (both off by default).
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Foundation
 import simd
 
@@ -158,3 +160,4 @@ struct AllocentricPanner: Sendable {
         simd_clamp(p, SIMD3(repeating: 0), SIMD3(repeating: 1))
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift b/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift
index d85d893af..0365858c4 100644
--- a/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift
+++ b/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait (both off by default).
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Accelerate
 import Foundation
 
@@ -183,3 +185,4 @@ struct BedLevelMeter {
         amplitude > 0 ? String(format: "%.1f", 20 * log10(amplitude)) : "-inf"
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
index a37ef490e..bbe3fc29b 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait (both off by default).
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Foundation
 
 /// One block of decoded object audio, borrowed from the decoder: `planes` stay valid only until the
@@ -44,3 +46,4 @@ extension ObjectAudioDecoding {
     var selfResetCount: Int { 0 }
     func releaseHeldBlocks() {}
 }
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift
index e2b0b98ad..4d1ab1701 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait (both off by default).
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Accelerate
 import Foundation
 
@@ -277,3 +279,4 @@ final class ObjectAudioRenderer {
         }
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift b/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift
index 7541ed0ff..dd756c359 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait (both off by default).
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Foundation
 
 /// Holds the blocks an object decoder returns between a reset and the stream's first object metadata.
@@ -105,3 +107,4 @@ final class ObjectMetadataHold {
         heldFrames = 0
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
index 42d05f2ba..6b1c99e0e 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait (both off by default).
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Foundation
 import AetherLibavcodec
 import AetherLibavutil
@@ -504,3 +506,4 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         }
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index a35f0c0a1..3ab67b27f 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -20,6 +20,22 @@ extension HLSVideoEngine {
             case .dtsHDMasterAudio: return "DTS:X"
             }
         }
+
+        /// Whether this build carries the source's decoder (its package trait). Without it the source
+        /// keeps the channel bridge whatever `objectAudioRendering` asks.
+        var isBuiltIn: Bool {
+            switch self {
+            case .trueHDAtmos: return AetherEngine.linksTrueHDObjectDecoder
+            case .dtsHDMasterAudio: return AetherEngine.linksDTSXObjectDecoder
+            }
+        }
+
+        var traitName: String {
+            switch self {
+            case .trueHDAtmos: return "TrueHDObjectAudio"
+            case .dtsHDMasterAudio: return "DTSXObjectAudio"
+            }
+        }
     }
 
     /// The bed a source should be rendered into, or nil to keep the ordinary bridge.
@@ -31,7 +47,7 @@ extension HLSVideoEngine {
     /// markers, so the label misses some DTS:X, and a DTS-HD MA track that turns out not to be DTS:X
     /// is refused before the bridge is built (`buildSpatialAudioProducerIfEligible`). 48 kHz, or not
     /// yet known, since TrueHD reports its rate from the first frame and both formats are only ever
-    /// authored at 48 kHz.
+    /// authored at 48 kHz. Nil as well when the build lacks the source's decoder trait.
     static func spatialRenderingLayout(
         rendering: ObjectAudioRendering,
         codecID: AVCodecID,
@@ -39,7 +55,7 @@ extension HLSVideoEngine {
         sampleRate: Int32
     ) -> SpatialSpeakerLayout? {
         guard let layout = rendering.layout,
-              objectAudioSource(codecID: codecID, profile: profile) != nil,
+              objectAudioSource(codecID: codecID, profile: profile)?.isBuiltIn == true,
               sampleRate == 0 || sampleRate == Int32(ObjectAudioRendering.sampleRate)
         else { return nil }
         return layout
@@ -108,7 +124,15 @@ extension HLSVideoEngine {
             profile: par.profile, sampleRate: par.sample_rate),
               let source = Self.objectAudioSource(codecID: par.codec_id, profile: par.profile)
         else {
-            if par.codec_id == AV_CODEC_ID_TRUEHD {
+            if objectAudioRendering != .off,
+               let source = Self.objectAudioSource(codecID: par.codec_id, profile: par.profile),
+               !source.isBuiltIn {
+                EngineLog.emit(
+                    "[HLSVideoEngine] \(source.name) rendering requested but not built in (\(source.traitName) "
+                    + "trait off); keeping the channel bridge",
+                    category: .session
+                )
+            } else if par.codec_id == AV_CODEC_ID_TRUEHD {
                 if objectAudioRendering != .off {
                     EngineLog.emit(
                         "[HLSVideoEngine] object rendering requested but TrueHD is not 48 kHz Atmos "
@@ -151,7 +175,28 @@ extension HLSVideoEngine {
             )
             return nil
         }
+        #if TrueHDObjectAudio || DTSXObjectAudio
+        return buildSpatialAudioProducer(
+            audioStream: audioStream, audioDemuxer: audioDemuxer, sourceAudioStreamIndex: sourceAudioStreamIndex,
+            sourceCodecLabel: sourceCodecLabel, audioHLSCodecs: &audioHLSCodecs, audioLanguage: audioLanguage,
+            layout: layout, source: source)
+        #else
+        return nil
+        #endif
+    }
 
+    #if TrueHDObjectAudio || DTSXObjectAudio
+    @available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *)
+    private func buildSpatialAudioProducer(
+        audioStream: UnsafeMutablePointer<AVStream>,
+        audioDemuxer: Demuxer,
+        sourceAudioStreamIndex: Int32,
+        sourceCodecLabel: String,
+        audioHLSCodecs: inout String?,
+        audioLanguage: String?,
+        layout: SpatialSpeakerLayout,
+        source: ObjectAudioSource
+    ) -> HLSSegmentProducer? {
         let bridge: SpatialAudioBridge
         do {
             let decoder: ObjectAudioDecoding
@@ -160,10 +205,6 @@ extension HLSVideoEngine {
                 #if TrueHDObjectAudio
                 decoder = try TrueHDObjectAudioDecoder()
                 #else
-                EngineLog.emit(
-                    "[HLSVideoEngine] built without the TrueHDObjectAudio trait (no LibTrueHD); keeping the channel bridge",
-                    category: .session
-                )
                 return nil
                 #endif
             case .dtsHDMasterAudio:
@@ -205,10 +246,6 @@ extension HLSVideoEngine {
                     return nil
                 }
                 #else
-                EngineLog.emit(
-                    "[HLSVideoEngine] built without the DTSXObjectAudio trait (no LibDTSX); keeping the channel bridge",
-                    category: .session
-                )
                 return nil
                 #endif
             }
@@ -271,4 +308,5 @@ extension HLSVideoEngine {
             return nil
         }
     }
+    #endif
 }
diff --git a/Tests/AetherEngineTests/ObjectMetadataHoldTests.swift b/Tests/AetherEngineTests/ObjectMetadataHoldTests.swift
index 7a2ed11e3..79a5bbffe 100644
--- a/Tests/AetherEngineTests/ObjectMetadataHoldTests.swift
+++ b/Tests/AetherEngineTests/ObjectMetadataHoldTests.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait: the renderer is not built without one.
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Testing
 import Foundation
 @testable import AetherEngine
@@ -145,3 +147,4 @@ struct ObjectMetadataHoldTests {
         #expect(out[1].updates.first?.frameOffset == 0)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
index 0c671333c..3961f34f3 100644
--- a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
@@ -15,6 +15,7 @@ import AetherLibavutil
 /// behaves like the real one on exactly those points.
 @Suite("TrueHD Atmos spatial bridge", .timeLimit(.minutes(2)))
 struct SpatialAudioBridgeTests {
+    #if TrueHDObjectAudio || DTSXObjectAudio
 
     /// Stand-in object decoder: one pushed byte is one 40-frame access unit (TrueHD's 1/1200 s),
     /// the first `skipAfterReset` access units after a reset are discarded as a real decoder does
@@ -142,6 +143,9 @@ struct SpatialAudioBridgeTests {
         return out
     }
 
+    #endif
+
+    #if TrueHDObjectAudio
     @Test("only TrueHD that FFmpeg marks Atmos, at 48 kHz or not yet known, is rendered")
     func eligibility() {
         let on = ObjectAudioRendering.apac(.l714)
@@ -154,7 +158,9 @@ struct SpatialAudioBridgeTests {
                 "E-AC-3 JOC is already Atmos and stream-copies")
         #expect(HLSVideoEngine.spatialRenderingLayout(rendering: .off, codecID: AV_CODEC_ID_TRUEHD, profile: 30, sampleRate: 48_000) == nil)
     }
+    #endif
 
+    #if DTSXObjectAudio
     @Test("every 48 kHz DTS-HD MA track is a DTS:X candidate, whatever FFmpeg's label; lossy DTS is not")
     func dtsEligibility() {
         let on = ObjectAudioRendering.apac(.l714)
@@ -171,7 +177,9 @@ struct SpatialAudioBridgeTests {
         #expect(HLSVideoEngine.spatialRenderingLayout(rendering: .off, codecID: AV_CODEC_ID_DTS, profile: AV_PROFILE_DTS_HD_MA_X, sampleRate: 48_000) == nil)
         #expect(HLSVideoEngine.objectAudioSource(codecID: AV_CODEC_ID_TRUEHD, profile: 30) == .trueHDAtmos)
     }
+    #endif
 
+    #if TrueHDObjectAudio || DTSXObjectAudio
     @Test("the first packet sits at the source position of the first decodable frame, and steps by 1024")
     func anchorsOnSource() throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
@@ -442,6 +450,7 @@ struct SpatialAudioBridgeTests {
         return (try #require(initBytes), segment, sessionDir)
     }
 
+    #endif
     @Test("the Atmos output activator's bundled stream reads as E-AC-3 with the Atmos extension")
     @MainActor
     func silentAtmosStreamIsAtmos() async throws {
@@ -457,6 +466,7 @@ struct SpatialAudioBridgeTests {
         #expect(CMFormatDescriptionGetMediaSubType(format) == kAudioFormatEnhancedAC3)
     }
 
+    #if TrueHDObjectAudio || DTSXObjectAudio
     @Test("movenc muxes the stand-in and the init segment carries the real apac entry")
     func muxedInitCarriesAPAC() throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
@@ -545,8 +555,10 @@ struct SpatialAudioBridgeTests {
         }
         return nil
     }
+    #endif
 }
 
+#if TrueHDObjectAudio || DTSXObjectAudio
 /// The bed level line is the engine's half of a missing-heights report: it says which channels of the
 /// rendered bed carried sound in what AVPlayer was handed, so a silent height here and a silent height
 /// at the receiver are told apart.
@@ -791,3 +803,4 @@ extension SpatialAudioBridgeTests {
         #expect(bridge.servedChannelCount == layout.channelCount)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/SpatialObjectRenderingTests.swift b/Tests/AetherEngineTests/SpatialObjectRenderingTests.swift
index b5335b024..7f81d5086 100644
--- a/Tests/AetherEngineTests/SpatialObjectRenderingTests.swift
+++ b/Tests/AetherEngineTests/SpatialObjectRenderingTests.swift
@@ -1,3 +1,5 @@
+// Only with the TrueHDObjectAudio or DTSXObjectAudio trait: the renderer is not built without one.
+#if TrueHDObjectAudio || DTSXObjectAudio
 import Testing
 import Foundation
 @testable import AetherEngine
@@ -345,3 +347,4 @@ struct SpatialObjectRenderingTests {
         }
     }
 }
+#endif

From 1e7bcbcc84773597574491539c77fc34d2723a58 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 09:40:12 +0200
Subject: [PATCH 107/132] feat: object audio and Profile 7 FEL composition are
 opt-in traits

TrueHDObjectAudio and DTSXObjectAudio are now off by default, and the new
DualLayerDolbyVision trait (off by default) compiles the Profile 7 FEL
dual-layer path: DualLayerVideoDecoder, DualLayerPictureAlignment,
FrameSideDataRing, the Metal composer, its parameter structs and shader
source, FelResidualMeasure and the @_spi(Diagnostics) FEL probe.

Public API is unchanged. Without a trait, `objectAudioRendering` keeps the
codec on the channel bridge and `preferDualLayerDolbyVision` keeps a
Profile 7 source on the native route: DualLayerRouteDecision reports
`notBuiltIn` (logged as "built without the DualLayerDolbyVision trait"),
VideoRoutingPolicy and the software host's decoder selection never pick
the dual-layer decoder, and DoviRpuConverter skips the composition
parameters. VideoSessionRebuilding moves next to HardwareVideoDecoder.
aetherctl's feltest and play --cycle-el need the trait and say so.

Tests that need a component sit behind its trait; the shared FEL fixtures
and the libdovi fuzzing of the conversion path stay in every build.
OptionalComponentFallbackTests pins the fallback with the traits off.
README gains an Optional components section, and docs/ and the changelog
state the trait each feature needs. These components may be subject to
third-party patent licensing; integrators who enable them are responsible
for their own licensing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 17 ++++-
 Package.resolved                              |  2 +-
 Package.swift                                 | 20 ++++--
 README.md                                     | 32 +++++----
 .../Spatial/DTSXObjectAudioDecoder.swift      |  2 +-
 .../Spatial/TrueHDObjectAudioDecoder.swift    |  2 +-
 .../Decoder/DualLayerPictureAlignment.swift   |  3 +
 .../Decoder/DualLayerRouteDecision.swift      | 12 ++++
 .../Decoder/DualLayerVideoDecoder.swift       | 11 +--
 .../Decoder/FrameSideDataRing.swift           |  3 +
 .../Decoder/HardwareVideoDecoder.swift        |  9 +++
 .../Decoder/VideoRoutingPolicy.swift          |  3 +-
 .../Diagnostics/FelResidualMeasure.swift      |  3 +
 .../Native/SoftwarePlaybackHost.swift         | 34 +++++++---
 .../Video/AetherEngine+FelProbe.swift         |  3 +
 .../AetherEngine/Video/DoviRpuConverter.swift | 36 +++++++++-
 .../Video/Metal/DoviFelComposer.swift         |  3 +
 .../Video/Metal/DoviMetalParams.swift         |  3 +
 .../Video/Metal/DoviShaderSource.swift        |  3 +
 Sources/aetherctl/FelTest.swift               |  2 +
 Sources/aetherctl/main.swift                  | 18 ++++-
 .../DTSXObjectMetadataMappingTests.swift      |  2 +-
 Tests/AetherEngineTests/DTSXSampleTests.swift |  2 +-
 .../DocumentedConstantsTests.swift            | 14 ++--
 .../DoviComposeAsyncTests.swift               |  3 +
 .../AetherEngineTests/DoviCpuModelTests.swift |  3 +
 .../DoviCrcValidFuzzTests.swift               |  2 +
 Tests/AetherEngineTests/DoviDitherTests.swift |  3 +
 .../DoviElBitDepthTests.swift                 |  3 +
 .../DoviEnhancementUpsamplerTests.swift       |  3 +
 .../AetherEngineTests/DoviFelFuzzTests.swift  |  4 ++
 .../AetherEngineTests/DoviFelMathTests.swift  |  3 +
 .../DoviFelRealFileTests.swift                |  6 ++
 .../DoviGpuAdversarialTests.swift             |  3 +
 .../DoviGpuCurveSweepTests.swift              |  3 +
 .../DoviGpuEdgeCaseTests.swift                |  3 +
 .../DoviLayoutProbeTests.swift                |  3 +
 .../DoviRealFileExportTests.swift             |  3 +
 .../DoviRpuConverterTests.swift               |  2 +
 .../DoviShaderSyncTests.swift                 |  3 +
 .../DualLayerEdgeCaseTests.swift              |  3 +
 .../DualLayerGpuSlotWaitTests.swift           |  3 +
 ...lLayerPictureAlignmentSyntheticTests.swift |  3 +
 .../DualLayerPictureAlignmentTests.swift      |  3 +
 .../DualLayerRouteAudioTests.swift            |  2 +-
 .../DualLayerRouteDecisionTests.swift         |  3 +
 .../DualLayerSeekRealignmentTests.swift       |  3 +
 .../DualLayerStreamClassificationTests.swift  |  3 +
 .../DualLayerVideoDecoderTests.swift          |  3 +
 .../FrameSideDataRingTests.swift              |  3 +
 .../OptionalComponentFallbackTests.swift      | 67 +++++++++++++++++++
 .../SampleBufferRendererLookaheadTests.swift  |  2 +
 .../SoftwareDecoderSelectionTests.swift       | 22 +++++-
 .../TrueHDAtmosSampleTests.swift              |  2 +-
 .../TrueHDObjectMetadataMappingTests.swift    |  2 +-
 .../VideoRoutingPolicyTests.swift             | 13 ++--
 docs/api.md                                   |  6 +-
 docs/architecture.md                          | 10 +--
 docs/cli.md                                   |  8 +--
 docs/dolby-vision-fel.md                      | 14 +++-
 docs/formats.md                               | 10 +--
 61 files changed, 394 insertions(+), 80 deletions(-)
 create mode 100644 Tests/AetherEngineTests/OptionalComponentFallbackTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 983309090..b8239c69a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,22 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Changed
+
+- **TrueHD Atmos and DTS:X object rendering, and Profile 7 FEL dual-layer composition, are optional
+  components, off by default.** Each is compiled only with its package trait: `TrueHDObjectAudio`
+  (LibTrueHD and the object renderer), `DTSXObjectAudio` (LibDTSX and the object renderer) and the new
+  `DualLayerDolbyVision` (`DualLayerVideoDecoder`, the Metal composer and the FEL diagnostics). The two
+  audio traits used to be on by default. Without a trait the component is not in the binary, and the
+  option that asks for it stays in the API and changes nothing: `objectAudioRendering` keeps the codec on
+  the channel bridge, `preferDualLayerDolbyVision` keeps a Profile 7 source on the native route (the
+  route line reads `not taken (built without the DualLayerDolbyVision trait)`). These components may be
+  subject to third-party patent licensing; integrators who enable them are responsible for their own
+  licensing. **A host that relied on TrueHD Atmos or DTS:X rendering enables the traits** on its package
+  dependency (`traits: ["TrueHDObjectAudio", "DTSXObjectAudio"]`, [README › Optional
+  components](README.md#optional-components)). The `@_spi(Diagnostics)` FEL tooling (`felDecodeProbe`,
+  `FelProbeResult`, `felResidualEnabled`) exists only with `DualLayerDolbyVision`, as do `aetherctl
+  feltest` and `play --cycle-el`. CI builds and tests the default and the all-traits configuration.
 
 ## [7.38.1] - 2026-10-16
 
diff --git a/Package.resolved b/Package.resolved
index 5a54bff98..69765087e 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "8a36d413c7871a759c82699c06441188691f92960e77d298fe53a8d75b9265f2",
+  "originHash" : "36e04bcc609a78f08b50a1d52363ff6d088a26a672a10b7ff9f948ae3a221929",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
diff --git a/Package.swift b/Package.swift
index 86cd81a39..a8d5d147e 100644
--- a/Package.swift
+++ b/Package.swift
@@ -25,20 +25,26 @@ let package = Package(
         // platforms. The target is preserved below so `swift build` on
         // macOS still produces the CLI for upstream development.
     ],
-    // Each object-audio decoder library sits behind a trait of its own, both on by default. A host that
-    // cannot ship one of them turns its trait off (`.package(url:..., traits: [...])`, or the package's
-    // traits in Xcode): the library is then not linked, and its codec keeps the channel bridge whatever
-    // `objectAudioRendering` asks. LibDovi, FFmpeg and everything else are unaffected.
+    // Three optional components, all off by default. A host that wants one enables its trait
+    // (`.package(url:..., traits: [...])`, or the package's traits in Xcode); without it the code is not
+    // compiled and the library behind it is not linked. These components may be subject to third-party
+    // patent licensing; an integrator that enables one is responsible for its own licensing. Off, the
+    // matching LoadOptions are accepted and change nothing: object audio keeps the channel bridge, and a
+    // Profile 7 source keeps the native route. LibDovi, FFmpeg and everything else are unaffected.
     traits: [
         .trait(
             name: "TrueHDObjectAudio",
-            description: "Link LibTrueHD, so objectAudioRendering can render TrueHD Atmos objects to APAC."
+            description: "Link LibTrueHD and the object renderer, so objectAudioRendering can render TrueHD Atmos objects to APAC."
         ),
         .trait(
             name: "DTSXObjectAudio",
-            description: "Link LibDTSX, so objectAudioRendering can render DTS:X heights and objects to APAC."
+            description: "Link LibDTSX and the object renderer, so objectAudioRendering can render DTS:X heights and objects to APAC."
         ),
-        .default(enabledTraits: ["TrueHDObjectAudio", "DTSXObjectAudio"]),
+        .trait(
+            name: "DualLayerDolbyVision",
+            description: "Compile the Dolby Vision Profile 7 FEL dual-layer composer, so preferDualLayerDolbyVision can take that route."
+        ),
+        .default(enabledTraits: []),
     ],
     dependencies: [
         // Minimal FFmpeg build (avcodec, avformat, avutil, swresample only).
diff --git a/README.md b/README.md
index 4b037d7bd..ec0ed81ca 100644
--- a/README.md
+++ b/README.md
@@ -66,9 +66,9 @@ 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 on the native route as single-layer 8.1 (HDR10 base layer on a display without Dolby Vision), or composed dual-layer on Metal with per-frame DV metadata for FEL when `preferDualLayerDolbyVision` is set and VideoToolbox decodes HEVC in hardware, P8.1, P8.4, AV1 P10.x), HLG, HDR Vivid (played on its HLG / PQ base, CUVA metadata reported by `probe`) |
+| HDR | HDR10, HDR10+ (per-frame ST 2094-40), Dolby Vision (P5, P7 on the native route as single-layer 8.1 (HDR10 base layer on a display without Dolby Vision), or composed dual-layer on Metal with per-frame DV metadata for FEL when `preferDualLayerDolbyVision` is set, the `DualLayerDolbyVision` trait is on and VideoToolbox decodes HEVC in hardware, 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) except the opt-in Profile 7 FEL dual-layer route (`preferDualLayerDolbyVision`), which runs on the software host and plays an E-AC-3 JOC track as its 5.1 / 7.1 bed without the objects. 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. TrueHD Atmos keeps its heights too, opt-in through `LoadOptions.objectAudioRendering`: the engine decodes the Atmos objects, renders them into a speaker bed and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio ([details](docs/formats.md#truehd-atmos-with-heights)). DTS:X takes the same route, its heights and objects unfolded from the compatible 7.1 ([details](docs/formats.md#dtsx-with-heights)) |
+| Dolby Atmos | EAC3+JOC stream-copied on every route (HDMI MAT 2.0, AirPods spatial, BT downmix) except the opt-in Profile 7 FEL dual-layer route (`preferDualLayerDolbyVision`, `DualLayerDolbyVision` trait), which runs on the software host and plays an E-AC-3 JOC track as its 5.1 / 7.1 bed without the objects. 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. TrueHD Atmos keeps its heights too, opt-in through `LoadOptions.objectAudioRendering` in a build with the `TrueHDObjectAudio` trait ([Optional components](#optional-components)): the engine decodes the Atmos objects, renders them into a speaker bed and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio ([details](docs/formats.md#truehd-atmos-with-heights)). DTS:X takes the same route with the `DTSXObjectAudio` trait, its heights and objects unfolded from the compatible 7.1 ([details](docs/formats.md#dtsx-with-heights)) |
 | Surround | 5.1 / 7.1 with correct `AudioChannelLayout` |
 | Audio-only | `LoadOptions.audioOnly`: lean pipeline, no video machinery, system Now-Playing on tvOS / iOS |
 | Background audio | Audio keeps playing when the app backgrounds on iOS: native AVPlayer stays alive, the software path drops video and keeps decoding audio (`backgroundPlaybackEnabled` / `pictureInPictureActive`); a paused session survives quick app switches for a grace window (`backgroundTeardownGraceSeconds`, default 15 s) before the wedge-safe teardown runs. tvOS tears down immediately (wedge-safe) unless a PiP window is active, which keeps the pipeline and loopback server alive; with PiP the software path keeps decoding video too (the window needs frames). Hosts gate corrective actions on the published `isSessionReady` |
@@ -95,7 +95,7 @@ On Apple platforms the real choice is between AVPlayer, with deep OS integration
 | **Container & codec breadth** | Wide, FFmpeg demux | Wide, FFmpeg demux | Narrow, Apple's set | Wide | Wide |
 | **Hardware decode** | VideoToolbox, dav1d SW fallback | VideoToolbox, FFmpeg SW fallback | VideoToolbox | VideoToolbox plus software | VideoToolbox plus software |
 | **Dolby Vision** | P5, P7 as 8.1 (or opt-in FEL dual-layer), P8.1, P8.4, AV1 P10.x, real display switch | P5, P8 via AVPlayer; their matrix lists P5 HDR display without overheating as paid LGPL | P5 and P8.1 only | Tone-maps, no DV display | Tone-maps, no DV display |
-| **Dolby Atmos** | EAC3+JOC stream-copied (HDMI MAT, spatial); TrueHD Atmos and DTS:X rendered to APAC, heights kept | EAC3+JOC via AVPlayer | EAC3+JOC passthrough | Decodes to PCM, no object passthrough | No Atmos passthrough on Apple |
+| **Dolby Atmos** | EAC3+JOC stream-copied (HDMI MAT, spatial); TrueHD Atmos and DTS:X rendered to APAC, heights kept (optional components) | EAC3+JOC via AVPlayer | EAC3+JOC passthrough | Decodes to PCM, no object passthrough | No Atmos passthrough on Apple |
 | **HDR on tvOS** | Native Match Content switch | Native Match Content on AVPlayer path, else Metal tone-map | Native Match Content | Software tone-mapping | Software tone-mapping |
 | **Rendering & UI** | OS-native, you ship SwiftUI | Own Metal renderer, bundled controls | OS-native, you ship UI | Own renderer, bundled controls | Own renderer, bundled OSC |
 | **Apple TV / App Store** | Yes, LGPL plus store exception | Free build GPL, paid LGPL tier for AV1 hardware decode and the full decoder set | Yes | Yes, LGPL | Not practical, GPL, no tvOS |
@@ -654,22 +654,28 @@ The Swift and Xcode rows are the toolchain CI builds and tests with (GitHub's `x
 
 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")`.
 
-### Package traits
+### Optional components
 
-The two object-audio decoder libraries are behind package traits, both on by default, so nothing changes for a host that does not ask:
+Three components are compiled only when a host asks for them, each behind a package trait that is **off by default**:
 
-| Trait | Links | Without it |
+| Trait | Compiles and links | Without it |
 | --- | --- | --- |
-| `TrueHDObjectAudio` | [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD) | TrueHD Atmos keeps the channel bridge whatever `objectAudioRendering` asks |
-| `DTSXObjectAudio` | [LibDTSX](https://github.com/superuser404notfound/LibDTSX) | DTS:X keeps the channel bridge whatever `objectAudioRendering` asks |
+| `TrueHDObjectAudio` | [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD) and the object renderer | TrueHD Atmos keeps the channel bridge whatever `objectAudioRendering` asks |
+| `DTSXObjectAudio` | [LibDTSX](https://github.com/superuser404notfound/LibDTSX) and the object renderer | DTS:X keeps the channel bridge whatever `objectAudioRendering` asks |
+| `DualLayerDolbyVision` | the Profile 7 FEL dual-layer composer (`DualLayerVideoDecoder` and its Metal composer) | a Profile 7 source keeps the native route whatever `preferDualLayerDolbyVision` asks |
 
-A host that cannot ship one of the libraries turns its trait off; the library is then neither linked nor resolved (it drops out of the host's `Package.resolved`), and the session log says why the codec stayed on the bridge (`built without the TrueHDObjectAudio trait`). In a package manifest, list the traits to keep (an empty list keeps none):
+Without its trait a component is not in the binary: its code is not compiled, and a library behind it is neither linked nor resolved (it drops out of the host's `Package.resolved`). The options that ask for it stay in the API, so a host compiles the same either way; they change nothing, and the session log says why (`TrueHD Atmos rendering requested but not built in (TrueHDObjectAudio trait off)`, `DV P7 dual-layer route: not taken (built without the DualLayerDolbyVision trait)`).
+
+These components may be subject to third-party patent licensing. Integrators who enable them are responsible for their own licensing.
+
+To enable them, list the traits on the package dependency:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.1", traits: [])
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.1",
+         traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision"])
 ```
 
-In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: []` on the package). `swift build --disable-default-traits` builds the engine itself that way.
+In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: [...]` on the package). The engine itself builds with them through `swift build --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision` (or `--enable-all-traits`); CI builds and tests both the default and the all-traits configuration.
 
 ## Support
 
@@ -693,9 +699,9 @@ The exception covers AetherEngine's own code; it does not extend to its dependen
 
 **libdovi** reaches your app through [LibDovi](https://github.com/superuser404notfound/LibDovi) as a static library. It is the compiled `dolby_vision` crate from [dovi_tool](https://github.com/quietvoid/dovi_tool), Copyright (c) quietvoid and contributors, dual-licensed MIT OR Apache-2.0 and consumed here under the MIT option. MIT asks for that copyright notice to travel with the binary, and it is quietvoid's notice that belongs on the acknowledgements screen. The MIT text in LibDovi's own `LICENSE` covers the packaging and build scripts only; both parts are in that one file.
 
-**LibTrueHD** ([superuser404notfound/LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) reaches your app as a static library and decodes TrueHD for `objectAudioRendering`. Its C API, framer and packaging are MIT (Copyright Quick104, who wrote it for Silo as SiloObjectAudio, and Vincent Herbst). It compiles in the `truehd` and `oamd` crates from [truehdd](https://github.com/truehdd/truehdd), Copyright Rainbaby and the truehdd contributors, under the Apache License 2.0, which asks for the license text and LibTrueHD's `NOTICE` to travel with the binary. Apache-2.0 combines with the engine's LGPL-3.0. It comes in through the `TrueHDObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it ([Package traits](#package-traits)).
+**LibTrueHD** ([superuser404notfound/LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) reaches your app as a static library and decodes TrueHD for `objectAudioRendering`. Its C API, framer and packaging are MIT (Copyright Quick104, who wrote it for Silo as SiloObjectAudio, and Vincent Herbst). It compiles in the `truehd` and `oamd` crates from [truehdd](https://github.com/truehdd/truehdd), Copyright Rainbaby and the truehdd contributors, under the Apache License 2.0, which asks for the license text and LibTrueHD's `NOTICE` to travel with the binary. Apache-2.0 combines with the engine's LGPL-3.0. It comes in only through the `TrueHDObjectAudio` trait, off by default ([Optional components](#optional-components)); with the trait on it is linked whether or not a host turns the option on.
 
-**LibDTSX** ([superuser404notfound/LibDTSX](https://github.com/superuser404notfound/LibDTSX)) reaches your app as a **dynamic framework**, `DTSX.framework`, which Xcode embeds in `YourApp.app/Frameworks/` next to the FFmpeg frameworks, and decodes DTS:X for `objectAudioRendering`. Its C API, framing and packaging are Apache-2.0, and it compiles in the `dca` crate from [harletty-bridge](https://github.com/harletty/harletty-bridge), which is labelled Apache-2.0 but is a port of FFmpeg's LGPL-2.1-or-later `dca` decoder. The built library is therefore LGPL-3.0-or-later, and it stays a separate, replaceable framework for the same reason the FFmpeg frameworks do (#798); LibDTSX's `NOTICE` and `LICENSES/` travel with the binary. It comes in through the `DTSXObjectAudio` trait, on by default, and is linked whether or not a host turns the option on; a host that turns the trait off ships without it.
+**LibDTSX** ([superuser404notfound/LibDTSX](https://github.com/superuser404notfound/LibDTSX)) reaches your app as a **dynamic framework**, `DTSX.framework`, which Xcode embeds in `YourApp.app/Frameworks/` next to the FFmpeg frameworks, and decodes DTS:X for `objectAudioRendering`. Its C API, framing and packaging are Apache-2.0, and it compiles in the `dca` crate from [harletty-bridge](https://github.com/harletty/harletty-bridge), which is labelled Apache-2.0 but is a port of FFmpeg's LGPL-2.1-or-later `dca` decoder. The built library is therefore LGPL-3.0-or-later, and it stays a separate, replaceable framework for the same reason the FFmpeg frameworks do (#798); LibDTSX's `NOTICE` and `LICENSES/` travel with the binary. It comes in only through the `DTSXObjectAudio` trait, off by default; with the trait on it is linked whether or not a host turns the option on.
 
 **SMBClient** ([kishikawakatsumi/SMBClient](https://github.com/kishikawakatsumi/SMBClient), MIT) reaches your app only if you link the `AetherEngineSMB` product. Linking `AetherEngine` alone pulls in none of its symbols, even though SwiftPM still records the package in `Package.resolved`, which describes the resolved graph rather than what the linker kept.
 
diff --git a/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
index 27d392f38..324cbe74b 100644
--- a/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
@@ -1,4 +1,4 @@
-// Only with the DTSXObjectAudio trait (on by default), which links LibDTSX.
+// Only with the DTSXObjectAudio trait (off by default), which links LibDTSX.
 #if DTSXObjectAudio
 import Foundation
 import DTSX
diff --git a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
index 94564dbcf..1064456be 100644
--- a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
@@ -1,4 +1,4 @@
-// Only with the TrueHDObjectAudio trait (on by default), which links LibTrueHD.
+// Only with the TrueHDObjectAudio trait (off by default), which links LibTrueHD.
 #if TrueHDObjectAudio
 import Foundation
 import TrueHD
diff --git a/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift b/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift
index 80a27660e..084bb09df 100644
--- a/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerPictureAlignment.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 
 /// Gives each enhancement-layer packet the presentation time of the base-layer picture it belongs to.
@@ -171,3 +173,4 @@ struct DualLayerPictureAlignment {
         let (v, o) = a.addingReportingOverflow(b); return o ? nil : v
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift b/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
index 406ff8d2a..997391dfa 100644
--- a/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
@@ -18,6 +18,8 @@ enum DualLayerRouteDecision: Equatable {
         /// Not HEVC Dolby Vision Profile 7: nothing to decide, and nothing is logged.
         case notProfile7
         case preferenceOff
+        /// The package was built without the `DualLayerDolbyVision` trait, so there is no composer.
+        case notBuiltIn
         case baseLayerOnlyHandling
         case liveOrNotSeekable
         case noHardwareHEVC
@@ -51,6 +53,13 @@ enum DualLayerRouteDecision: Equatable {
         }
     }
 
+    /// Whether the composer is compiled in (the `DualLayerDolbyVision` package trait, off by default).
+    #if DualLayerDolbyVision
+    static let isBuiltIn = true
+    #else
+    static let isBuiltIn = false
+    #endif
+
     /// The most pixels per second, base layer plus enhancement layer, the route is willing to decode in
     /// real time: UHD 3840x2160 at 30 fps (248.8 Mpx/s) plus a 1920x1080 enhancement layer at 30 fps
     /// (62.2 Mpx/s), 311.04 Mpx/s in all. The anchor is a 24p UHD FEL master, the shape UHD Blu-ray
@@ -98,6 +107,7 @@ enum DualLayerRouteDecision: Equatable {
     ) -> Reason? {
         guard codecID == AV_CODEC_ID_HEVC, dvProfile == 7 else { return .notProfile7 }
         guard preferDualLayerDolbyVision else { return .preferenceOff }
+        guard isBuiltIn else { return .notBuiltIn }
         guard dolbyVisionHandling == .automatic else { return .baseLayerOnlyHandling }
         guard !isLive, isSourceSeekable else { return .liveOrNotSeekable }
         guard canHardwareDecode?() ?? true else { return .noHardwareHEVC }
@@ -165,6 +175,8 @@ extension DualLayerRouteDecision.Reason {
             return "not Dolby Vision Profile 7"
         case .preferenceOff:
             return "preferDualLayerDolbyVision is off"
+        case .notBuiltIn:
+            return "built without the DualLayerDolbyVision trait"
         case .baseLayerOnlyHandling:
             return "dolbyVisionHandling is baseLayerOnly"
         case .liveOrNotSeekable:
diff --git a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
index 53f1157f0..802a28166 100644
--- a/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerVideoDecoder.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 import CoreMedia
 import CoreVideo
@@ -93,14 +95,6 @@ extension SingleLayerVideoDecoder {
 
 extension HardwareVideoDecoder: SingleLayerVideoDecoder {}
 
-/// AE#739: a decoder whose VideoToolbox sessions the system can invalidate behind its back, and that
-/// can build them again. The host recovers through this rather than through one decoder type.
-protocol VideoSessionRebuilding: AnyObject {
-    var onSessionLost: (@Sendable () -> Void)? { get set }
-    @discardableResult func rebuildSession() -> Bool
-}
-
-extension HardwareVideoDecoder: VideoSessionRebuilding {}
 extension DualLayerVideoDecoder: VideoSessionRebuilding {}
 
 /// Video decoding pipeline that transparently coordinates dual VideoToolbox HEVC decoders
@@ -1853,3 +1847,4 @@ final class DualLayerVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         recordSideData(key: key, params: params, dmNAL: displayMetadataNAL, usesPrevious: usesPrevious, disableResidual: disableResidual)
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Decoder/FrameSideDataRing.swift b/Sources/AetherEngine/Decoder/FrameSideDataRing.swift
index 51310d5e1..bd6c5d3cf 100644
--- a/Sources/AetherEngine/Decoder/FrameSideDataRing.swift
+++ b/Sources/AetherEngine/Decoder/FrameSideDataRing.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 
 /// Fixed-capacity ring buffer for Dolby Vision per-frame side data (dolby-vision-fel.md §5.3).
@@ -162,3 +164,4 @@ struct FrameSideDataRing: Sendable {
         entryCount = 0
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 4e322adaa..115a30b28 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -790,3 +790,12 @@ private func hwDecoderOutputCallback(
         pts: presentationTimeStamp
     )
 }
+
+/// AE#739: a decoder whose VideoToolbox sessions the system can invalidate behind its back, and that
+/// can build them again. The host recovers through this rather than through one decoder type.
+protocol VideoSessionRebuilding: AnyObject {
+    var onSessionLost: (@Sendable () -> Void)? { get set }
+    @discardableResult func rebuildSession() -> Bool
+}
+
+extension HardwareVideoDecoder: VideoSessionRebuilding {}
\ No newline at end of file
diff --git a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
index e75673ba3..1bc70e1a4 100644
--- a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
+++ b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
@@ -24,7 +24,8 @@ enum VideoRoutingPolicy {
         canHardwareDecode: (() -> Bool)?
     ) -> Bool {
         guard codecID == AV_CODEC_ID_HEVC, dvProfile == 7,
-              preferDualLayerDolbyVision, dolbyVisionHandling == .automatic else { return false }
+              preferDualLayerDolbyVision, DualLayerRouteDecision.isBuiltIn,
+              dolbyVisionHandling == .automatic else { return false }
         return canHardwareDecode?() ?? true
     }
 
diff --git a/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift b/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
index a80500edc..3df396dd3 100644
--- a/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
+++ b/Sources/AetherEngine/Diagnostics/FelResidualMeasure.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 import CoreVideo
 import CoreMedia
@@ -109,3 +111,4 @@ enum FelResidualMeasure {
         return s
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index c0dbf13b8..a388656f6 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -146,7 +146,7 @@ final class SoftwarePlaybackHost {
 
     /// Whether load selected VideoToolbox rather than libavcodec / dav1d for video decoding.
     /// Only meaningful after load has returned successfully.
-    var usesHardwareVideoDecoder: Bool { videoDecoder is HardwareVideoDecoder || videoDecoder is DualLayerVideoDecoder }
+    var usesHardwareVideoDecoder: Bool { videoDecoder is HardwareVideoDecoder || decodesDualLayer }
 
     /// AE#711 follow-up: the picture on screen now, read back from the renderer before a rebuild's
     /// `stop()` flushes it, so the engine can hold it over the new host's startup. Falls back to the
@@ -931,7 +931,7 @@ final class SoftwarePlaybackHost {
 
     /// Pure decoder selection predicate for Profile 7 / HEVC streams on the software host.
     /// DualLayerVideoDecoder is selected ONLY when dvProfile == 7 && elType == "FEL" && preferDualLayerDolbyVision
-    /// && dolbyVisionHandling == .automatic.
+    /// && dolbyVisionHandling == .automatic, in a build with the DualLayerDolbyVision trait.
     /// All other combinations (e.g. MEL, baseLayerOnly, preferDualLayerDolbyVision == false) pick HardwareVideoDecoder.
     nonisolated static func shouldUseDualLayerDecoder(
         dvProfile: Int?,
@@ -939,12 +939,24 @@ final class SoftwarePlaybackHost {
         preferDualLayerDolbyVision: Bool,
         dolbyVisionHandling: DolbyVisionHandling
     ) -> Bool {
-        dvProfile == 7
+        DualLayerRouteDecision.isBuiltIn
+            && dvProfile == 7
             && elType == "FEL"
             && preferDualLayerDolbyVision
             && dolbyVisionHandling == .automatic
     }
 
+    /// Whether `decoder` is a `DualLayerVideoDecoder`; always false without the trait.
+    nonisolated static func isDualLayer(_ decoder: any VideoDecodingPipeline) -> Bool {
+        #if DualLayerDolbyVision
+        return decoder is DualLayerVideoDecoder
+        #else
+        return false
+        #endif
+    }
+
+    var decodesDualLayer: Bool { Self.isDualLayer(videoDecoder) }
+
     /// Selects and instantiates the appropriate VideoDecodingPipeline based on stream and host options.
     func selectVideoDecoder(
         codecID: AVCodecID,
@@ -958,6 +970,7 @@ final class SoftwarePlaybackHost {
                 preferDualLayerDolbyVision: preferDualLayerDolbyVision,
                 dolbyVisionHandling: dolbyVisionHandling
             ) {
+                #if DualLayerDolbyVision
                 // No Metal device: the composer cannot be built, so decode the base layer alone (the
                 // decoder the software host uses for any other Profile 7 stream) instead of opening a
                 // decoder whose `open()` can only throw. A shader that fails to compile is caught later,
@@ -966,6 +979,7 @@ final class SoftwarePlaybackHost {
                     return DualLayerVideoDecoder(composer: composer)
                 }
                 EngineLog.emit("[SWHost] DV P7 dual-layer route: no Metal device for the composer, decoding the base layer alone", category: .swPlayback)
+                #endif
                 return HardwareVideoDecoder()
             } else {
                 return HardwareVideoDecoder()
@@ -1067,6 +1081,7 @@ final class SoftwarePlaybackHost {
                 dvProfile: dvProfile
             )
             videoDecoder = chosen
+            #if DualLayerDolbyVision
             if let dual = chosen as? DualLayerVideoDecoder {
                 // An in-band primary open failure (no hvcC to open from) leaves nothing to show. Surface it
                 // through the same `failure` the read loops use for a decode error. It belongs to the
@@ -1083,7 +1098,8 @@ final class SoftwarePlaybackHost {
                     }
                 }
             }
-            if chosen is DualLayerVideoDecoder {
+            #endif
+            if decodesDualLayer {
                 EngineLog.emit(
                     "[SWHost] selected DualLayerVideoDecoder (Metal P7 FEL) for codec_id=\(codecpar.pointee.codec_id.rawValue)",
                     category: .swPlayback
@@ -1110,14 +1126,14 @@ final class SoftwarePlaybackHost {
         // the same reorder depth as the single-layer hardware decoder, used only when arrival-order handover
         // below is off (no frame rate).
         renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(
-            forHardwareDecoder: videoDecoder is HardwareVideoDecoder || videoDecoder is DualLayerVideoDecoder))
+            forHardwareDecoder: videoDecoder is HardwareVideoDecoder || decodesDualLayer))
         renderer.setFELLookahead(
-            enabled: videoDecoder is DualLayerVideoDecoder,
+            enabled: decodesDualLayer,
             frameRate: AetherEngine.detectFrameRate(stream: vStream))
         // The FEL look-ahead window only holds if none of it waits in the reorder buffer; see
         // `SampleBufferRenderer.arrivalFloor`. Without a frame rate it stays on the reorder buffer.
         renderer.setArrivalOrderHandover(
-            frameRate: videoDecoder is DualLayerVideoDecoder ? AetherEngine.detectFrameRate(stream: vStream) : nil)
+            frameRate: decodesDualLayer ? AetherEngine.detectFrameRate(stream: vStream) : nil)
 
         // 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 {
@@ -1583,10 +1599,12 @@ final class SoftwarePlaybackHost {
 
     #if DEBUG
     func invalidateVideoSessionForTesting() -> Bool {
+        #if DualLayerDolbyVision
         if let dual = videoDecoder as? DualLayerVideoDecoder {
             dual.invalidateSessionsForTesting()
             return true
         }
+        #endif
         guard let hw = videoDecoder as? HardwareVideoDecoder else { return false }
         hw.invalidateSessionForTesting()
         return true
@@ -3466,7 +3484,7 @@ final class SoftwarePlaybackHost {
                 while !mayDecodeVideoPacket(packet) && !stopRequested() && !backgroundAudioOnly() {
                     // A seek can move the clock backwards while this compressed FEL packet is
                     // held. Leave the wait so the generation check below discards it immediately.
-                    if videoDecoder is DualLayerVideoDecoder, seekGeneration() != genBeforeRead { break }
+                    if Self.isDualLayer(videoDecoder), seekGeneration() != genBeforeRead { break }
                     autoreleasepool {
                         if !isPlaying() {
                             condition.lock()
diff --git a/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift b/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
index 09f01281a..466258fb3 100644
--- a/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
+++ b/Sources/AetherEngine/Video/AetherEngine+FelProbe.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 import CoreMedia
 import CoreVideo
@@ -247,3 +249,4 @@ extension AetherEngine {
         set { DoviFelComposer.residualEnabled = newValue }
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/DoviRpuConverter.swift b/Sources/AetherEngine/Video/DoviRpuConverter.swift
index 149b7d0d0..02959628d 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter.swift
@@ -29,7 +29,9 @@ public enum DoviRpuConverter {
         /// (L1 statistics, L2 trims, L5/L8/L9/L11), which `DoviDisplayMetadata` attaches to the
         /// composed pixel buffer. Nil when there was no RPU or the conversion failed.
         let convertedRpu: [UInt8]?
+        #if DualLayerDolbyVision
         let rpuParams: DoviMetalParams?
+        #endif
         let isFEL: Bool
         let isMEL: Bool
         let success: Bool
@@ -39,17 +41,30 @@ public enum DoviRpuConverter {
         /// a `use_prev_vdr_rpu_flag` frame can still say whether its residual applies.
         let disableResidual: Bool
 
+        #if DualLayerDolbyVision
         init(elPacket: UnsafeMutablePointer<AVPacket>?, rpuData: [UInt8]?, convertedRpu: [UInt8]? = nil, rpuParams: DoviMetalParams? = nil, isFEL: Bool, isMEL: Bool = false, success: Bool, usesPreviousMapping: Bool = false, disableResidual: Bool = false) {
+            self.rpuParams = rpuParams
+            self.elPacket = elPacket
+            self.rpuData = rpuData
+            self.convertedRpu = convertedRpu
+            self.isFEL = isFEL
+            self.isMEL = isMEL
+            self.success = success
+            self.usesPreviousMapping = usesPreviousMapping
+            self.disableResidual = disableResidual
+        }
+        #else
+        init(elPacket: UnsafeMutablePointer<AVPacket>?, rpuData: [UInt8]?, convertedRpu: [UInt8]? = nil, isFEL: Bool, isMEL: Bool = false, success: Bool, usesPreviousMapping: Bool = false, disableResidual: Bool = false) {
             self.elPacket = elPacket
             self.rpuData = rpuData
             self.convertedRpu = convertedRpu
-            self.rpuParams = rpuParams
             self.isFEL = isFEL
             self.isMEL = isMEL
             self.success = success
             self.usesPreviousMapping = usesPreviousMapping
             self.disableResidual = disableResidual
         }
+        #endif
     }
 
     /// Stream classification from one RPU (dolby-vision-fel.md §5.2, invariant I9): a property of the
@@ -162,7 +177,9 @@ public enum DoviRpuConverter {
         let keepRpuBytes = extractEL || extractParams
         var rawRpuBytes: [UInt8]?
         var convertedRpuBytes: [UInt8]?
+        #if DualLayerDolbyVision
         var rpuParams: DoviMetalParams?
+        #endif
         var converted = false
         var isFEL = false
         var isMEL = false
@@ -188,7 +205,9 @@ public enum DoviRpuConverter {
                     return
                 }
                 defer { dovi_rpu_free(rpu) }
+                #if DualLayerDolbyVision
                 let thisParams: DoviMetalParams? = extractParams ? DoviFelComposer.parseRpuParameters(rpu: rpu) : nil
+                #endif
                 var thisPrevious = false, thisDisableResidual = false, thisFEL = false, thisMEL = false
                 // Only the dual-layer outputs read the header; the P8.1 rewrite drops what it yields.
                 if keepRpuBytes, let hdr = dovi_rpu_get_header(rpu) {
@@ -223,7 +242,9 @@ public enum DoviRpuConverter {
 
                 rawRpuBytes = thisRaw
                 convertedRpuBytes = keepRpuBytes ? [UInt8](UnsafeBufferPointer(start: outData, count: out.pointee.len)) : nil
+                #if DualLayerDolbyVision
                 rpuParams = thisParams
+                #endif
                 usesPrevious = thisPrevious
                 disableResidual = thisDisableResidual
                 isFEL = thisFEL
@@ -287,6 +308,7 @@ public enum DoviRpuConverter {
 
         // A dropped-RPU degrade still produces a valid HDR10 packet, but reports failure so callers
         // can log it and the probe can flag the source for dovi_tool inspection.
+        #if DualLayerDolbyVision
         return DualLayerPacketResult(
             elPacket: producedElPacket,
             rpuData: rawRpuBytes,
@@ -298,6 +320,18 @@ public enum DoviRpuConverter {
             usesPreviousMapping: usesPrevious,
             disableResidual: disableResidual
         )
+        #else
+        return DualLayerPacketResult(
+            elPacket: producedElPacket,
+            rpuData: rawRpuBytes,
+            convertedRpu: convertedRpuBytes,
+            isFEL: isFEL && !isMEL,
+            isMEL: isMEL,
+            success: !degraded && !allocationFailed,
+            usesPreviousMapping: usesPrevious,
+            disableResidual: disableResidual
+        )
+        #endif
     }
 
     /// Returns `false` when a libdovi conversion fails (or on an internal allocation failure).
diff --git a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
index e7d40c05d..e4aa16b46 100644
--- a/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviFelComposer.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 import Metal
 import CoreVideo
@@ -1451,3 +1453,4 @@ final class DoviFelComposer: @unchecked Sendable {
         return params
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift b/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift
index 04287391f..738507acd 100644
--- a/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviMetalParams.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 
 /// How one reshaping piece is evaluated (`mapping_idc`).
@@ -313,3 +315,4 @@ struct DoviMetalParams: Sendable {
         return data
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
index 10fd9795f..a44aa68a0 100644
--- a/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
+++ b/Sources/AetherEngine/Video/Metal/DoviShaderSource.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 
 /// Canonical Metal source for the Dolby Vision FEL composer.
@@ -728,3 +730,4 @@ kernel void dovi_layout_probe(
         preamble + "\n" + sharedStructs + "\n" + kernels + "\n"
     }
 }
+#endif
diff --git a/Sources/aetherctl/FelTest.swift b/Sources/aetherctl/FelTest.swift
index ba9dfb237..3e3e8698c 100644
--- a/Sources/aetherctl/FelTest.swift
+++ b/Sources/aetherctl/FelTest.swift
@@ -1,3 +1,4 @@
+#if DualLayerDolbyVision
 import Foundation
 @_spi(Diagnostics) import AetherEngine
 
@@ -66,3 +67,4 @@ func runFelTest(url: URL, maxFrames: Int = 100) -> Int32 {
         return 2
     }
 }
+#endif
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 4e8ef3a1d..6e64e515b 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -81,7 +81,8 @@ func printUsage() {
              [--max-concurrent-requests N]
                      [--audio-stats] [--host-calls play,extractor,setrate,pausestart,reloadlive,seekback,seekfar,pauseseek,pausereload,playreload,extplayreload,reloadnext] <url>
                      (full load+play session smoke test; --fel opts into the Profile 7
-                      FEL dual-layer route (off by default, as in the engine; --no-fel
+                      FEL dual-layer route (off by default, as in the engine, and only in
+                      a build with the DualLayerDolbyVision trait; --no-fel
                       is accepted and does nothing); --surface (or --window) presents
                       into a window; --cycle-el S flips the FEL residual every S
                       seconds, which needs --fel and a surface; --subs activates the first
@@ -111,7 +112,7 @@ func printUsage() {
                           (#92: SW-decode each segment in isolation; framesDecoded==0 => not independent)
       aetherctl disc-inspect <disc.iso>
       aetherctl dovitest [--out PATH.hevc] <file>
-      aetherctl feltest [--frames N] <file>
+      aetherctl feltest [--frames N] <file>   (DualLayerDolbyVision trait)
       aetherctl dvsurvey [--frames N] [--list K] <file>
       aetherctl extract [--at <sec>] [--snapshot] [--width <px>] [--loops <n>] <url>
       aetherctl audio [--seconds N] <url>
@@ -489,7 +490,12 @@ if first == "feltest" {
     }
     rest.removeAll { $0 == urlArg }
     rejectStrayFlags(rest, subcommand: "feltest")
+    #if DualLayerDolbyVision
     exit(runFelTest(url: parseSourceURL(urlArg), maxFrames: frames))
+    #else
+    print("ERROR: feltest needs the DualLayerDolbyVision trait (swift build --traits DualLayerDolbyVision)")
+    exit(64)
+    #endif
 }
 
 // Dolby Vision display-metadata survey: picks the pin for the on-device consumption test.
@@ -718,6 +724,10 @@ if first == "play" {
             print("ERROR: --cycle-el takes a period of at least 0.1 seconds, got '\(spec)'")
             exit(64)
         }
+        #if !DualLayerDolbyVision
+        print("ERROR: --cycle-el needs the DualLayerDolbyVision trait (swift build --traits DualLayerDolbyVision)")
+        exit(64)
+        #else
         if !playFel {
             print("[aetherctl] note: --cycle-el only changes a session on the dual-layer route; add --fel")
         }
@@ -737,6 +747,7 @@ if first == "play" {
             }
         }
         t.start()
+        #endif
     }
     // `--dv-pin <spec>`: arm the Dolby Vision pin test (DEBUG builds), same grammar `dvsurvey` prints.
     if let spec = takeStringFlag("--dv-pin", from: &rest) {
@@ -1112,6 +1123,9 @@ if ["probe", "serve", "validate", "swdecode", "extract", "audio", "customio"].co
             exit(64)
         }
         serveObjectAudioRendering = .apac(layout)
+        #if !(TrueHDObjectAudio || DTSXObjectAudio)
+        print("[aetherctl] note: --atmos-bed renders nothing without the TrueHDObjectAudio / DTSXObjectAudio traits")
+        #endif
     } else {
         serveObjectAudioRendering = .off
     }
diff --git a/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift b/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
index e2de14761..8670baf8d 100644
--- a/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
+++ b/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
@@ -1,4 +1,4 @@
-// Only with the DTSXObjectAudio trait (on by default): the decoder and its library are not built without it.
+// Only with the DTSXObjectAudio trait (off by default): the decoder and its library are not built without it.
 #if DTSXObjectAudio
 import Testing
 import Foundation
diff --git a/Tests/AetherEngineTests/DTSXSampleTests.swift b/Tests/AetherEngineTests/DTSXSampleTests.swift
index ea4ff2918..7acde0cfa 100644
--- a/Tests/AetherEngineTests/DTSXSampleTests.swift
+++ b/Tests/AetherEngineTests/DTSXSampleTests.swift
@@ -1,4 +1,4 @@
-// Only with the DTSXObjectAudio trait (on by default): the decoder and its library are not built without it.
+// Only with the DTSXObjectAudio trait (off by default): the decoder and its library are not built without it.
 #if DTSXObjectAudio
 import Testing
 import Foundation
diff --git a/Tests/AetherEngineTests/DocumentedConstantsTests.swift b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
index 4305539a6..17396049f 100644
--- a/Tests/AetherEngineTests/DocumentedConstantsTests.swift
+++ b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
@@ -61,6 +61,7 @@ final class DocumentedConstantsTests: XCTestCase {
         assertDocumented("A 24p UHD FEL master needs 80% of the budget", fel)
     }
 
+    #if DualLayerDolbyVision
     func testDualLayerPipelineBoundsMatchDocumentation() throws {
         let docs = try documentation()
         let fel = try felDocument()
@@ -98,6 +99,7 @@ final class DocumentedConstantsTests: XCTestCase {
         assertDocumented("Counters feed a 1 Hz summary", fel)
         _ = docs
     }
+    #endif
 
     private func felDocument() throws -> String {
         let url = Self.repoRoot.appendingPathComponent("docs/dolby-vision-fel.md")
@@ -312,12 +314,9 @@ final class DocumentedConstantsTests: XCTestCase {
     func testTrueHDAtmosNumbersAreWhatTheDocsSay() throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
         let docs = try documentation()
+        #if TrueHDObjectAudio || DTSXObjectAudio
         XCTAssertEqual(SpatialAudioBridge.bitRatePerChannel, 320_000)
         assertDocumented("320 kbps per bed channel", docs)
-        XCTAssertEqual(PeakLimiter.threshold, 0.98)
-        assertDocumented("nothing leaves above −0.18 dBFS", docs)
-        XCTAssertEqual(PeakLimiter.releaseSeconds, 0.25)
-        assertDocumented("a 250 ms release", docs)
         XCTAssertEqual(BedLevelMeter.firstWindowSeconds, 5)
         XCTAssertEqual(BedLevelMeter.windowSeconds, 30)
         assertDocumented("after the first 5 s of audio (and again after every seek), then every 30 s", docs)
@@ -325,6 +324,11 @@ final class DocumentedConstantsTests: XCTestCase {
         assertDocumented("returns nothing for 1200 packets in a row, a second of TrueHD", docs)
         XCTAssertEqual(ObjectMetadataHold.maxHeldFrames, 4_800)
         assertDocumented("(it waits at most 100 ms)", docs)
+        #endif
+        XCTAssertEqual(PeakLimiter.threshold, 0.98)
+        assertDocumented("nothing leaves above −0.18 dBFS", docs)
+        XCTAssertEqual(PeakLimiter.releaseSeconds, 0.25)
+        assertDocumented("a 250 ms release", docs)
         XCTAssertEqual(APACSampleEntry.codecsString(channelCount: 12), "apac.31.03")
         XCTAssertEqual(APACSampleEntry.codecsString(channelCount: 16), "apac.31.04")
     }
@@ -419,8 +423,10 @@ final class DocumentedConstantsTests: XCTestCase {
 
     // MARK: - Picture-order pairing (docs/dolby-vision-fel.md §5.3)
 
+    #if DualLayerDolbyVision
     func testPictureOrderPairingBoundMatchesDocumentation() throws {
         XCTAssertEqual(DualLayerPictureAlignment.maxSlotDistance, 16)
         assertDocumented("more than 16 slots off its unit", try felDocument())
     }
+    #endif
 }
diff --git a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
index 77cde13ec..2f677b1d9 100644
--- a/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
+++ b/Tests/AetherEngineTests/DoviComposeAsyncTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreVideo
 import Foundation
@@ -279,3 +281,4 @@ struct DoviComposeAsyncTests {
         }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviCpuModelTests.swift b/Tests/AetherEngineTests/DoviCpuModelTests.swift
index 17760e07f..33e199d1d 100644
--- a/Tests/AetherEngineTests/DoviCpuModelTests.swift
+++ b/Tests/AetherEngineTests/DoviCpuModelTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -441,3 +443,4 @@ struct DoviCpuModelTests {
         }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
index e570f4061..c8d901655 100644
--- a/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviCrcValidFuzzTests.swift
@@ -92,6 +92,7 @@ struct DoviCrcValidFuzzTests {
             if let dump = env["AETHER_FUZZ_DUMP"] { try? Data(m).write(to: URL(fileURLWithPath: dump + label)) }
             guard let rpu = m.withUnsafeBufferPointer({ DoviRpuGuard.parse($0.baseAddress!, $0.count) }) else { guarded += 1; continue }
             defer { dovi_rpu_free(rpu) }
+            #if DualLayerDolbyVision
             if let p = DoviFelComposer.parseRpuParameters(rpu: rpu) {
                 parsed += 1
                 for poly in [p.polyY, p.polyCb, p.polyCr] {
@@ -99,6 +100,7 @@ struct DoviCrcValidFuzzTests {
                     #expect(q.numPivots <= UInt32(DoviPolynomialParams.maxPivots))
                 }
             }
+            #endif
             if let out = DoviRpuConverter.convertedUnspec62(rpu) {
                 written += 1
                 dovi_data_free(out)
diff --git a/Tests/AetherEngineTests/DoviDitherTests.swift b/Tests/AetherEngineTests/DoviDitherTests.swift
index 5a98ea34f..b3ed5f520 100644
--- a/Tests/AetherEngineTests/DoviDitherTests.swift
+++ b/Tests/AetherEngineTests/DoviDitherTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -290,3 +292,4 @@ struct DoviDitherTests {
         #expect(recovered == Self.bayerGolden, "recovered \(recovered)")
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviElBitDepthTests.swift b/Tests/AetherEngineTests/DoviElBitDepthTests.swift
index 36df3cf37..0b65a760d 100644
--- a/Tests/AetherEngineTests/DoviElBitDepthTests.swift
+++ b/Tests/AetherEngineTests/DoviElBitDepthTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import Dovi
@@ -98,3 +100,4 @@ struct DoviElBitDepthTests {
         #expect(DoviFelComposer.parseRpuParameters(rpu: rpu) == nil)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
index f57287025..66a2d4021 100644
--- a/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
+++ b/Tests/AetherEngineTests/DoviEnhancementUpsamplerTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Foundation
 import Testing
 import Metal
@@ -96,3 +98,4 @@ struct DoviEnhancementUpsamplerTests {
         for gx in 1..<64 { #expect(row[gx] >= row[gx - 1], "monotone at \(gx)") }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviFelFuzzTests.swift b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
index ab716d9c4..537717868 100644
--- a/Tests/AetherEngineTests/DoviFelFuzzTests.swift
+++ b/Tests/AetherEngineTests/DoviFelFuzzTests.swift
@@ -72,7 +72,9 @@ struct DoviFelFuzzTests {
         defer { dovi_rpu_free(rpu) }
         #expect(dovi_rpu_get_error(rpu) == nil, "\(dovi_rpu_get_error(rpu).map { String(cString: $0) } ?? "")",
                 sourceLocation: sourceLocation)
+        #if DualLayerDolbyVision
         #expect(DoviFelComposer.parseRpuParameters(rpu: rpu) != nil, sourceLocation: sourceLocation)
+        #endif
     }
 
     static func mutate(_ input: [UInt8], _ rng: inout RNG) -> [UInt8] {
@@ -113,6 +115,7 @@ struct DoviFelFuzzTests {
         return framed(base) + framed(el) + framed(rpu)
     }
 
+    #if DualLayerDolbyVision
     static func checkMutatedRpuParsing(seedRPU: [UInt8], label: String, rngState: UInt64, iterations: Int) throws {
         #expect(seedRPU.withUnsafeBufferPointer { DoviRpuGuard.crcIsValid($0.baseAddress!, $0.count) }, "a seed RPU must pass the CRC guard")
         try expectLibdoviAccepts(seedRPU)
@@ -169,6 +172,7 @@ struct DoviFelFuzzTests {
         let seed = try #require(try Self.seed())
         try Self.checkMutatedRpuParsing(seedRPU: seed.rpu, label: "clip", rngState: 0xFE1, iterations: 4000)
     }
+    #endif
 
     static func checkMutatedPacketSplitting(seedPacket: [UInt8], useCustomBlockSource: Bool, iterations: Int) {
         var rng = RNG(state: useCustomBlockSource ? 0xA11 : 0xB22)
diff --git a/Tests/AetherEngineTests/DoviFelMathTests.swift b/Tests/AetherEngineTests/DoviFelMathTests.swift
index b647689e4..f4ea129c4 100644
--- a/Tests/AetherEngineTests/DoviFelMathTests.swift
+++ b/Tests/AetherEngineTests/DoviFelMathTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -323,3 +325,4 @@ struct DoviFelMathTests {
         #expect(sampleY > 400 && sampleY < 600, "Output Y sample must be near mid-gray (~512), was \(sampleY)")
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviFelRealFileTests.swift b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
index b80a5669f..dec4587cc 100644
--- a/Tests/AetherEngineTests/DoviFelRealFileTests.swift
+++ b/Tests/AetherEngineTests/DoviFelRealFileTests.swift
@@ -49,6 +49,11 @@ struct DoviFelRealFileTests {
 
     /// The first two clips, when present: the ones long enough to seek into.
     static var firstTwoClips: [String] { [fixtures[0], fixtures[1]].filter(available) }
+}
+
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
+extension DoviFelRealFileTests {
 
     // MARK: - Harness
 
@@ -478,3 +483,4 @@ struct DoviFelRealFileTests {
         }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
index 5c8380987..fe6ac7ec0 100644
--- a/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuAdversarialTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -209,3 +211,4 @@ extension DoviGpuAdversarialTests {
         for plane in DoviTestSupport.rawVDR(out)[1...] { #expect(Set(plane) == [2048]) }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
index 910881014..2966d226f 100644
--- a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -392,3 +394,4 @@ struct DoviGpuCurveSweepTests {
         #expect(output[1023][0] == 940)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
index 2709d8f36..8ed9e42cc 100644
--- a/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuEdgeCaseTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -518,3 +520,4 @@ extension DoviGpuEdgeCaseTests {
         #expect(Set(DoviTestSupport.rawVDR(c)[2]) == [3996])
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
index 8581033f0..e74019d2b 100644
--- a/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
+++ b/Tests/AetherEngineTests/DoviLayoutProbeTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import Metal
@@ -239,3 +241,4 @@ struct DoviLayoutProbeTests {
         #expect(Data(rawBytes) == expectedData)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviRealFileExportTests.swift b/Tests/AetherEngineTests/DoviRealFileExportTests.swift
index a08c97830..869b1e4b6 100644
--- a/Tests/AetherEngineTests/DoviRealFileExportTests.swift
+++ b/Tests/AetherEngineTests/DoviRealFileExportTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -94,3 +96,4 @@ struct DoviRealFileExportTests {
     }
 }
 #endif
+#endif
diff --git a/Tests/AetherEngineTests/DoviRpuConverterTests.swift b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
index f3fd1197a..96c0b29dc 100644
--- a/Tests/AetherEngineTests/DoviRpuConverterTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
@@ -459,6 +459,7 @@ struct DoviRpuConverterTests {
         #expect(packetBytes(pkt) == input)
     }
 
+    #if DualLayerDolbyVision
     // MARK: - Single parse per RPU
 
     /// Each RPU must be parsed exactly once. Before the fix, `separateDualLayers`
@@ -628,6 +629,7 @@ struct DoviRpuConverterTests {
         #expect(result.isMEL == false)
         #expect(result.success == true)
     }
+    #endif
 
     /// Hex-string decoder for RPU fixtures.
     private func hexToBytes(_ hex: String) -> [UInt8] {
diff --git a/Tests/AetherEngineTests/DoviShaderSyncTests.swift b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
index 9e134ce03..dedc9da77 100644
--- a/Tests/AetherEngineTests/DoviShaderSyncTests.swift
+++ b/Tests/AetherEngineTests/DoviShaderSyncTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import Metal
@@ -80,3 +82,4 @@ struct DoviShaderSyncTests {
         #expect(compiles.count == 1)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift b/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift
index 233cbb465..23553ce9e 100644
--- a/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift
+++ b/Tests/AetherEngineTests/DualLayerEdgeCaseTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreMedia
 import CoreVideo
@@ -631,3 +633,4 @@ struct DualLayerEdgeCaseTests {
             dvProfile: 7, elType: "MEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic))
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
index 0785c91a3..7f9ebab87 100644
--- a/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
+++ b/Tests/AetherEngineTests/DualLayerGpuSlotWaitTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreMedia
 import CoreVideo
@@ -310,3 +312,4 @@ struct DualLayerGpuSlotWaitTests {
         }
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift b/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift
index 5fdb46267..5743c166d 100644
--- a/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift
+++ b/Tests/AetherEngineTests/DualLayerPictureAlignmentSyntheticTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 @testable import AetherEngine
@@ -168,3 +170,4 @@ struct DualLayerPictureAlignmentSyntheticTests {
         #expect(r == Result(pts: 6000, placed: true))
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift b/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
index 8ca3ea0ee..d245a0ac3 100644
--- a/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
+++ b/Tests/AetherEngineTests/DualLayerPictureAlignmentTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import AetherLibavformat
@@ -136,3 +138,4 @@ struct DualLayerPictureAlignmentTests {
         #expect(DualLayerPictureAlignment.extrapolate(origin: (3, 0), latest: (3, 40), slot: 6) == nil)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift b/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift
index 864da889a..b78718436 100644
--- a/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift
+++ b/Tests/AetherEngineTests/DualLayerRouteAudioTests.swift
@@ -23,7 +23,7 @@ struct DualLayerRouteAudioTests {
                 dvProfile: 7, dolbyVisionHandling: .automatic,
                 preferDualLayerDolbyVision: prefer, canHardwareDecode: { true }, elType: "FEL")
         }
-        #expect(requiresSoftware(prefer: true))
+        #expect(requiresSoftware(prefer: true) == DualLayerRouteDecision.isBuiltIn)
         #expect(!requiresSoftware(prefer: false))
     }
 
diff --git a/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift b/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift
index 90d81005f..00cc1f99f 100644
--- a/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift
+++ b/Tests/AetherEngineTests/DualLayerRouteDecisionTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: without it every Profile 7 decision is `notBuiltIn`.
+#if DualLayerDolbyVision
 import Testing
 import AetherLibavcodec
 @testable import AetherEngine
@@ -211,3 +213,4 @@ struct DualLayerRouteDecisionTests {
                                               settledGeneration: 3, stopRequested: false))
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
index 94c70fa9f..e67dfa4e2 100644
--- a/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
+++ b/Tests/AetherEngineTests/DualLayerSeekRealignmentTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreMedia
 import CoreVideo
@@ -305,3 +307,4 @@ struct DualLayerSeekRealignmentTests {
         #expect(pairs.last?.base === postBL && pairs.last?.enhancement === postEL)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
index 152c364dc..fd9109849 100644
--- a/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
+++ b/Tests/AetherEngineTests/DualLayerStreamClassificationTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreMedia
 import CoreVideo
@@ -238,3 +240,4 @@ struct DualLayerStreamClassificationTests {
         #expect(got.0 !== bl, "a disable_residual RPU must not bypass composition")
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
index 5bc74d201..612c0bf8b 100644
--- a/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
+++ b/Tests/AetherEngineTests/DualLayerVideoDecoderTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreMedia
 import CoreVideo
@@ -2753,3 +2755,4 @@ struct DualLayerVideoDecoderTests {
         #expect(PacketBalanceTracker.alive - aliveBefore < iterations / 2)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/FrameSideDataRingTests.swift b/Tests/AetherEngineTests/FrameSideDataRingTests.swift
index 4ca82368b..709f65743 100644
--- a/Tests/AetherEngineTests/FrameSideDataRingTests.swift
+++ b/Tests/AetherEngineTests/FrameSideDataRingTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the composer is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 @testable import AetherEngine
@@ -150,3 +152,4 @@ struct FrameSideDataRingTests {
         #expect(ring.find(key: 1_000) == nil)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift b/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift
new file mode 100644
index 000000000..b3b5359f9
--- /dev/null
+++ b/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift
@@ -0,0 +1,67 @@
+import Testing
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// The object renderer and the dual-layer composer are compiled only with their package traits, all off
+/// by default. A build without one still accepts the option that asks for it, and the option changes
+/// nothing: object audio keeps the channel bridge, a Profile 7 source keeps the native route. The track
+/// pick is pinned the same way in `AudioLanguageSelectionTests.withoutTraitNothingIsPreferred`.
+@Suite("Optional components fall back when their trait is off")
+struct OptionalComponentFallbackTests {
+
+    #if !DualLayerDolbyVision
+    private static let uhd24 = DualLayerRouteDecision.Geometry(width: 3840, height: 2160, frameRate: 24)
+
+    private static func decide(prefer: Bool) -> DualLayerRouteDecision {
+        DualLayerRouteDecision.decide(
+            codecID: AV_CODEC_ID_HEVC, dvProfile: 7, dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: prefer, isLive: false, isSourceSeekable: true,
+            canHardwareDecode: { true }, elType: "FEL", geometry: uhd24)
+    }
+
+    @Test("preferDualLayerDolbyVision keeps a Profile 7 FEL source on the native route and says why")
+    func dualLayerPreferenceKeepsNativeRoute() {
+        #expect(!DualLayerRouteDecision.isBuiltIn)
+        #expect(Self.decide(prefer: true) == .notTaken(.notBuiltIn))
+        #expect(Self.decide(prefer: true).logLine
+                == "[AetherEngine] DV P7 dual-layer route: not taken (built without the DualLayerDolbyVision trait), "
+                + "keeps the native route (8.1 where the display takes Dolby Vision)")
+        #expect(Self.decide(prefer: false) == .notTaken(.preferenceOff), "not asking is still reported as such")
+        #expect(!VideoRoutingPolicy.dualLayerRouteIsWanted(
+            codecID: AV_CODEC_ID_HEVC, dvProfile: 7, dolbyVisionHandling: .automatic,
+            preferDualLayerDolbyVision: true, canHardwareDecode: { true }),
+            "no el_type probe for a route that cannot be taken")
+        for prefer in [true, false] {
+            #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+                codecID: AV_CODEC_ID_HEVC, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: true,
+                dvProfile: 7, preferDualLayerDolbyVision: prefer, canHardwareDecode: { true }, elType: "FEL"))
+        }
+    }
+    #endif
+
+    #if !TrueHDObjectAudio
+    @Test("objectAudioRendering keeps TrueHD Atmos on the channel bridge")
+    func trueHDAtmosKeepsChannelBridge() {
+        #expect(HLSVideoEngine.objectAudioSource(codecID: AV_CODEC_ID_TRUEHD, profile: AV_PROFILE_TRUEHD_ATMOS) == .trueHDAtmos)
+        #expect(HLSVideoEngine.ObjectAudioSource.trueHDAtmos.isBuiltIn == false)
+        for layout in SpatialSpeakerLayout.allCases {
+            #expect(HLSVideoEngine.spatialRenderingLayout(
+                rendering: .apac(layout), codecID: AV_CODEC_ID_TRUEHD,
+                profile: AV_PROFILE_TRUEHD_ATMOS, sampleRate: 48_000) == nil)
+        }
+    }
+    #endif
+
+    #if !DTSXObjectAudio
+    @Test("objectAudioRendering keeps DTS-HD Master Audio on the channel bridge")
+    func dtsHDMasterAudioKeepsChannelBridge() {
+        #expect(HLSVideoEngine.ObjectAudioSource.dtsHDMasterAudio.isBuiltIn == false)
+        for profile in [AV_PROFILE_DTS_HD_MA, AV_PROFILE_DTS_HD_MA_X, AV_PROFILE_DTS_HD_MA_X_IMAX] {
+            #expect(HLSVideoEngine.objectAudioSource(codecID: AV_CODEC_ID_DTS, profile: profile) == .dtsHDMasterAudio)
+            #expect(HLSVideoEngine.spatialRenderingLayout(
+                rendering: .apac(.l714), codecID: AV_CODEC_ID_DTS, profile: profile, sampleRate: 48_000) == nil)
+        }
+    }
+    #endif
+}
diff --git a/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift b/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
index 6bfd1ee56..55b004250 100644
--- a/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
+++ b/Tests/AetherEngineTests/SampleBufferRendererLookaheadTests.swift
@@ -180,10 +180,12 @@ struct SampleBufferRendererLookaheadTests {
         #expect(abs(r.lead - 4 * frame) < 1e-9)
     }
 
+    #if DualLayerDolbyVision
     @Test("The pool threshold follows the look-ahead cap")
     func poolFollowsCap() {
         #expect(DoviFelComposer.outputPoolAllocationThreshold == SampleBufferRenderer.felVideoLookaheadFrames + 2 + DoviFelComposer.maxFramesInFlight + 1)
     }
+    #endif
 
     private func mayEnqueue(rate: Double?, pts: Double, clock: Double,
                             ready: Bool = true, armed: Bool = true) -> Bool {
diff --git a/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift b/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift
index faa314d6e..07de672c1 100644
--- a/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift
+++ b/Tests/AetherEngineTests/SoftwareDecoderSelectionTests.swift
@@ -21,6 +21,7 @@ struct SoftwareDecoderSelectionTests {
         #expect(decoder is HardwareVideoDecoder)
     }
 
+    #if DualLayerDolbyVision
     @MainActor
     @Test("P7 FEL opted in selects DualLayerVideoDecoder")
     func felOptedInSelectsDualLayer() {
@@ -36,6 +37,25 @@ struct SoftwareDecoderSelectionTests {
         )
         #expect(decoder is DualLayerVideoDecoder)
     }
+    #else
+    @MainActor
+    @Test("P7 FEL opted in keeps HardwareVideoDecoder in a build without the DualLayerDolbyVision trait")
+    func felOptedInWithoutTraitKeepsBaseLayer() {
+        let host = SoftwarePlaybackHost()
+        host.elType = "FEL"
+        host.preferDualLayerDolbyVision = true
+
+        let decoder = host.selectVideoDecoder(
+            codecID: AV_CODEC_ID_HEVC,
+            canHardwareDecode: true,
+            dvProfile: 7
+        )
+        #expect(decoder is HardwareVideoDecoder)
+        #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
+            dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
+        ))
+    }
+    #endif
 
     @MainActor
     @Test("P7 MEL selects HardwareVideoDecoder across all option combinations")
@@ -149,7 +169,7 @@ struct SoftwareDecoderSelectionTests {
         // Section 5.2 table: only dvProfile == 7 && elType == "FEL" && preferDualLayerDolbyVision && .automatic
         #expect(SoftwarePlaybackHost.shouldUseDualLayerDecoder(
             dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .automatic
-        ))
+        ) == DualLayerRouteDecision.isBuiltIn)
         #expect(!SoftwarePlaybackHost.shouldUseDualLayerDecoder(
             dvProfile: 7, elType: "FEL", preferDualLayerDolbyVision: true, dolbyVisionHandling: .baseLayerOnly
         ))
diff --git a/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift b/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift
index 1341e9174..ca6bf8469 100644
--- a/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift
+++ b/Tests/AetherEngineTests/TrueHDAtmosSampleTests.swift
@@ -1,4 +1,4 @@
-// Only with the TrueHDObjectAudio trait (on by default): the decoder and its library are not built without it.
+// Only with the TrueHDObjectAudio trait (off by default): the decoder and its library are not built without it.
 #if TrueHDObjectAudio
 import Testing
 import Foundation
diff --git a/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift b/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
index bf8be5e0a..480f11248 100644
--- a/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
+++ b/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
@@ -1,4 +1,4 @@
-// Only with the TrueHDObjectAudio trait (on by default): the decoder and its library are not built without it.
+// Only with the TrueHDObjectAudio trait (off by default): the decoder and its library are not built without it.
 #if TrueHDObjectAudio
 import Testing
 import Foundation
diff --git a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
index 53220c78f..4201ea456 100644
--- a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
+++ b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
@@ -298,7 +298,7 @@ struct VideoRoutingPolicyTests {
             preferDualLayerDolbyVision: true,
             canHardwareDecode: { true },
             elType: "FEL"
-        ))
+        ) == DualLayerRouteDecision.isBuiltIn)
     }
 
     @Test("the el_type probe is only wanted when its answer can change the route")
@@ -310,7 +310,7 @@ struct VideoRoutingPolicyTests {
                 codecID: codec, dvProfile: profile, dolbyVisionHandling: handling,
                 preferDualLayerDolbyVision: prefer, canHardwareDecode: hardware)
         }
-        #expect(wanted())
+        #expect(wanted() == DualLayerRouteDecision.isBuiltIn)
         #expect(!wanted(prefer: false), "not opted in: no probe")
         #expect(!wanted(handling: .baseLayerOnly))
         #expect(!wanted(hardware: { false }), "no proven hardware session: the host would not compose")
@@ -431,9 +431,10 @@ struct VideoRoutingPolicyTests {
                 for prefer in preferOptions {
                     for hw in hwOptions {
                         // Section 5.2 table:
-                        // P7 FEL + .automatic + preferDualLayerDolbyVision (true) + HW decode -> software host
-                        // All other combinations -> native (false)
-                        let expected = (el == "FEL")
+                        // P7 FEL + .automatic + preferDualLayerDolbyVision (true) + HW decode -> software host,
+                        // in a build with the DualLayerDolbyVision trait. All other combinations -> native (false)
+                        let expected = DualLayerRouteDecision.isBuiltIn
+                            && el == "FEL"
                             && handling == .automatic
                             && prefer
                             && hw
@@ -480,7 +481,7 @@ struct VideoRoutingPolicyTests {
             preferDualLayerDolbyVision: true,
             canHardwareDecode: { true },
             elType: "FEL"
-        ))
+        ) == DualLayerRouteDecision.isBuiltIn)
     }
 
     @Test("Profile 7 MEL stays native regardless of preferences")
diff --git a/docs/api.md b/docs/api.md
index 96d51a557..01c778926 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1279,7 +1279,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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. |
-| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731). `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Each codec needs its package trait (`TrueHDObjectAudio`, `DTSXObjectAudio`, both on by default); with one turned off, that codec keeps the channel bridge and the automatic audio pick no longer prefers it. |
+| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731), in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default, [README › Optional components](../README.md#optional-components)); without a codec's trait the option is accepted and that codec keeps `audioBridgeMode`. `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Each codec needs its package trait (`TrueHDObjectAudio`, `DTSXObjectAudio`, both on by default); with one turned off, that codec keeps the channel bridge and the automatic audio pick no longer prefers it. |
 | `confirmAtmos` | false | Background per-track JOC confirmation, republishing `audioTracks` as tracks confirm. Never on the start path; skipped for live and forward-only readers. |
 | `preferredAudioLanguages` | empty | First-frame audio pick from the engine's single probe. Ordered BCP-47 / ISO 639 tags; region and script are normalized and rank within one preference (#590). An explicit `audioSourceStreamIndex` still wins. |
 | `preferredSubtitleLanguages` | empty | Post-load subtitle activation on the host-overlay path. Ranks language specificity (an explicitly opposite script is rejected, not demoted) before the descriptor axis. Pure convenience: no reload and no pre-probe, unlike the audio equivalent. |
@@ -1300,7 +1300,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). |
-| `preferDualLayerDolbyVision` | false | Opt in to composing Profile 7 FEL sources on the GPU instead of taking the native route (the single-layer 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where it does not). When true, `dolbyVisionHandling` is `.automatic`, the source is a seekable VOD, the first RPU says `el_type` FEL, VideoToolbox decodes HEVC in hardware and the stream fits the real-time budget (UHD at 30 fps for the base layer plus a 1080p enhancement layer; a 24p UHD master uses 80% of it), Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`: both layers decode in VideoToolbox, `DoviFelComposer` reconstructs the picture in Metal and delivers 10-bit P010, and every frame carries its RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, which tvOS applies as Dolby Vision display management. A Profile 7 MEL source, and anything the device cannot decode twice in real time, keeps the native route (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not; the conversion is lossless only for MEL); the load logs one `DV P7 dual-layer route: taken` / `not taken (<reason>)` line either way. What the route gives up against the native one (Picture in Picture, scrub thumbnails, subtitles, AirPlay) is listed in [dolby-vision-fel.md](dolby-vision-fel.md#523-what-the-route-gives-up-against-the-native-route). Known trade-off, audio: the route runs on the software host, whose audio is decoded by FFmpeg and played through the sample-buffer audio renderer, and on tvOS only AVPlayer emits Atmos objects, so an E-AC-3 (JOC) track plays as its channel-bed core (5.1 or 7.1) without the objects; TrueHD behaves as on the native route. The route does not consult the display: with the flag on and a display that does not take Dolby Vision, the route is still taken, the composed full-FEL picture is presented with its attached metadata, and how tvOS presents it is up to the platform (the native route would have played the HDR10 base layer there). The E-AC-3 Atmos trade-off above applies there too. A tuning field, correctable through `reloadAtCurrentPosition(applying:)` on a URL source (which re-runs `load()` and re-decides the route); on a custom `IOReader` source a Profile 7 session refuses a change of this option, or a change of `dolbyVisionHandling` while this option is on, with `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, because the in-place rebuild keeps the route the session was loaded with: call `load()` again with the new option. See [dolby-vision-fel.md](dolby-vision-fel.md). |
+| `preferDualLayerDolbyVision` | false | Opt in to composing Profile 7 FEL sources on the GPU instead of taking the native route (the single-layer 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where it does not). Needs the `DualLayerDolbyVision` package trait (off by default, [README › Optional components](../README.md#optional-components)); without it the option is accepted and changes nothing. When true, `dolbyVisionHandling` is `.automatic`, the source is a seekable VOD, the first RPU says `el_type` FEL, VideoToolbox decodes HEVC in hardware and the stream fits the real-time budget (UHD at 30 fps for the base layer plus a 1080p enhancement layer; a 24p UHD master uses 80% of it), Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`: both layers decode in VideoToolbox, `DoviFelComposer` reconstructs the picture in Metal and delivers 10-bit P010, and every frame carries its RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, which tvOS applies as Dolby Vision display management. A Profile 7 MEL source, and anything the device cannot decode twice in real time, keeps the native route (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not; the conversion is lossless only for MEL); the load logs one `DV P7 dual-layer route: taken` / `not taken (<reason>)` line either way. What the route gives up against the native one (Picture in Picture, scrub thumbnails, subtitles, AirPlay) is listed in [dolby-vision-fel.md](dolby-vision-fel.md#523-what-the-route-gives-up-against-the-native-route). Known trade-off, audio: the route runs on the software host, whose audio is decoded by FFmpeg and played through the sample-buffer audio renderer, and on tvOS only AVPlayer emits Atmos objects, so an E-AC-3 (JOC) track plays as its channel-bed core (5.1 or 7.1) without the objects; TrueHD behaves as on the native route. The route does not consult the display: with the flag on and a display that does not take Dolby Vision, the route is still taken, the composed full-FEL picture is presented with its attached metadata, and how tvOS presents it is up to the platform (the native route would have played the HDR10 base layer there). The E-AC-3 Atmos trade-off above applies there too. A tuning field, correctable through `reloadAtCurrentPosition(applying:)` on a URL source (which re-runs `load()` and re-decides the route); on a custom `IOReader` source a Profile 7 session refuses a change of this option, or a change of `dolbyVisionHandling` while this option is on, with `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, because the in-place rebuild keeps the route the session was loaded with: call `load()` again with the new option. See [dolby-vision-fel.md](dolby-vision-fel.md). |
 | `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). |
 | `hostRetriesExhaustedLiveReplay` | `false` | The host owns the retry after a verified live replay exhausts the in-engine reopen: the engine publishes `liveSourceReplayExhausted` and holds production until `retryLiveSourceRecovery()`. `false` publishes `liveSourceReset` for the same exhaustion. |
 | `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. |
@@ -1354,6 +1354,6 @@ Public for the CLI, the test suite, or a diagnostic overlay, and outside the sha
 - **`playbackBackend`**: the internal rendering backend, exposed read-only for overlays. Hosts must not branch on it; `videoRoute` is the surface that answers the same question honestly.
 - **`HLSVideoEngine`** and its `DiagnosticStats`: the loopback session's own machinery, public because `aetherctl` drives it directly.
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
-- **Dolby Vision Profile 7 FEL tooling** (`@_spi(Diagnostics)`): `FelProbeResult` / `felDecodeProbe` (`aetherctl feltest`), `DoviRpuSurvey` / `DoviRpuSurveyResult` / `DoviRpuFrameSurvey` / `doviRpuSurvey` (`aetherctl dvsurvey`), `felResidualEnabled` (`aetherctl play --cycle-el`), and, in `DEBUG` builds only, `armDolbyVisionPinTest` / `dolbyVisionPinIsArmed` / `dolbyVisionPinIsActive` (`aetherctl play --dv-pin`). Hosts import none of them; the host surface of the FEL route is `LoadOptions.preferDualLayerDolbyVision` and, in `SessionReloadRefusal`, the new case `.dualLayerRouteNeedsFreshLoad`. See [Dolby Vision FEL](dolby-vision-fel.md) and [CLI](cli.md).
+- **Dolby Vision Profile 7 FEL tooling** (`@_spi(Diagnostics)`): `FelProbeResult` / `felDecodeProbe` (`aetherctl feltest`) and `felResidualEnabled` (`aetherctl play --cycle-el`), which exist only with the `DualLayerDolbyVision` trait, `DoviRpuSurvey` / `DoviRpuSurveyResult` / `DoviRpuFrameSurvey` / `doviRpuSurvey` (`aetherctl dvsurvey`), and, in `DEBUG` builds only, `armDolbyVisionPinTest` / `dolbyVisionPinIsArmed` / `dolbyVisionPinIsActive` (`aetherctl play --dv-pin`). Hosts import none of them; the host surface of the FEL route is `LoadOptions.preferDualLayerDolbyVision` and, in `SessionReloadRefusal`, the new case `.dualLayerRouteNeedsFreshLoad`. See [Dolby Vision FEL](dolby-vision-fel.md) and [CLI](cli.md).
 - **`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.
diff --git a/docs/architecture.md b/docs/architecture.md
index 8c901eca4..0dabdc297 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -427,8 +427,8 @@ Sources/AetherEngine/
 ├── Decoder/
 │   ├── A53ReorderBuffer.swift               Decode-to-presentation reorder for SEI caption groups (#131)
 │   ├── A53SEIParser.swift                   A53/GA94 cc_data extraction from H.264/HEVC SEI NALs (#131)
-│   ├── DualLayerPictureAlignment.swift      SW FEL path (not routed yet): pairs each EL picture with the base picture of the same display slot (POC), falling back to access-unit pairing (#702)
-│   ├── FrameSideDataRing.swift              SW FEL path (not routed yet): fixed ring of per-frame RPU parameters and display metadata keyed by timestamp (#702)
+│   ├── DualLayerPictureAlignment.swift      SW FEL path (`DualLayerDolbyVision` trait): pairs each EL picture with the base picture of the same display slot (POC), falling back to access-unit pairing (#702)
+│   ├── FrameSideDataRing.swift              SW FEL path (`DualLayerDolbyVision` trait): fixed ring of per-frame RPU parameters and display metadata keyed by timestamp (#702)
 │   ├── OrderedDelivery.swift                SW FEL path (not routed yet): hands composed frames from the Metal completion queue to the renderer in decode order, with an epoch for seeks and a stall guard (#702)
 │   ├── CCDataParser.swift                   Parses the bare cc_data triplet stream from a demuxable CEA-608 caption track (#77)
 │   ├── CEA608Decoder.swift                  In-house CEA-608 line-21 decoder (field-1 / CC1), validated against FFmpeg ccaption_dec.c (#77)
@@ -437,7 +437,7 @@ Sources/AetherEngine/
 │   ├── InterlaceProbe.swift                 Decodes a sample and applies the deinterlacer's own engagement predicate, so a declared field order that no frame backs up (PsF) stops costing a SW decode (#232)
 │   ├── VideoRoutingPolicy.swift             Pure codec-and-field-order dispatch rule: AV1 gated on HW, VP9/VP8/MPEG4/MPEG2/VC1 always SW, interlaced H.264 SW so bwdif can deinterlace (#107, verified against decoded frames on VOD, #232), plus a second-stage gate routing H.264 High 4:2:2/4:4:4/10 + HEVC Rext to SW where VideoToolbox has no HW decoder (#2)
 │   ├── HardwareVideoDecoder.swift           SW path: VideoToolbox HW HEVC / AV1 decoder for sources routed away from AVPlayer
-│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL. Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame; see [dolby-vision-fel.md](dolby-vision-fel.md)
+│   ├── DualLayerVideoDecoder.swift          SW path: Dolby Vision Profile 7 FEL (`DualLayerDolbyVision` trait). Two HardwareVideoDecoders (a base layer, typically 4K, and an enhancement layer, typically 1080p) paired by HEVC picture order with the packet's RPU, composed on Metal by `DoviFelComposer`, delivered in decode order with the Profile 8.1 RPU attached per frame; see [dolby-vision-fel.md](dolby-vision-fel.md)
 │   ├── SoftwareVideoDecoder.swift           SW path: libavcodec/dav1d → CVPixelBuffer (NV12 / P010), HDR10+ side data
 │   ├── SubtitleDecoder.swift                Sidecar URL one-shot decode (text only); decodes several streams of one container in a single pass (#266)
 │   ├── VideoDecoderTypes.swift              DecodedFrameHandler typealias + VideoDecoderError
@@ -570,9 +570,9 @@ Sources/AetherEngine/
 │   ├── DoviDisplayMetadata.swift            SW FEL path: sets `DolbyVisionRPUData` (the Profile 8.1 RPU minus its NAL header) and `DolbyCompatibilityID` (the CFString "1", never a number) on every emitted buffer, or clears both; tvOS consumes them in backboardd
 │   ├── DoviDisplayMetadataDebug.swift       DEBUG-only pin test: substitutes a captured RPU on a duty cycle, the on-device consumption test
 │   ├── DoviRpuSurvey.swift                  L1 / L2 display-metadata survey over a title's RPUs (no decode, no GPU); backs `aetherctl dvsurvey`
-│   ├── AetherEngine+FelProbe.swift          FEL decode probe backing `aetherctl feltest`, and the `--cycle-el` residual switch
+│   ├── AetherEngine+FelProbe.swift          `DualLayerDolbyVision` trait: FEL decode probe backing `aetherctl feltest`, and the `--cycle-el` residual switch
 │   ├── AetherEngine+DolbyVisionTest.swift   DEBUG-only `@_spi(Diagnostics)` hook (not host API) that arms the pin test from a debug menu or `aetherctl play --dv-pin`
-│   ├── Metal/
+│   ├── Metal/                               `DualLayerDolbyVision` trait only
 │   │   ├── DoviFelComposer.swift            BL + EL + RPU composition: runtime-compiled pipelines, pooled P010 output, `composeAsync` bounded at `maxFramesInFlight` with completions on its own serial queue; RPU → `DoviMetalParams` parsing
 │   │   ├── DoviShaderSource.swift           Luma / chroma compose kernels (reshaping, inverse NLQ, bilinear EL upsampling, ordered dither) and the ABI layout probe, compiled at runtime
 │   │   └── DoviMetalParams.swift            Swift mirror of the kernel parameter structs and their byte-exact serializer
diff --git a/docs/cli.md b/docs/cli.md
index 977c3926e..349844f16 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,6 @@
 # aetherctl
 
-A standalone macOS CLI shipped alongside the library for repro work without going through TestFlight + Apple TV. Most subcommands operate on a media source URL (`file://` or `http(s)://`); `live`, `dvr`, `hlsfixture`, and `hlslive` run against built-in synthetic fixtures.
+A standalone macOS CLI shipped alongside the library for repro work without going through TestFlight + Apple TV. It builds with the package's traits, so the optional components ([README › Optional components](../README.md#optional-components)) are in it only when it is built with them: `swift run --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision aetherctl …` for `--atmos-bed`, `play --fel`, `--cycle-el` and `feltest`. Most subcommands operate on a media source URL (`file://` or `http(s)://`); `live`, `dvr`, `hlsfixture`, and `hlslive` run against built-in synthetic fixtures.
 
 ```bash
 swift run aetherctl probe <url>          # dump container + streams + duration, exit
@@ -75,7 +75,7 @@ open 'http://127.0.0.1:<port>/<token>/master.m3u8'   # macOS QuickTime
 
 `--start-position S` starts the session at S seconds, the resume anchor a host passes to `load(url:startPosition:)`. Also available on `play`.
 
-`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744): a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: objects rendered into …` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`.
+`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: objects rendered into …` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`.
 
 `--audio-delay <ms>` parks the server with the AE#464 audio offset already in its muxer, which is how the DELIVERED offset is measured rather than argued about: fetch the media playlist and walk its segments, then read the first audio and video packet timestamps out of `init.mp4` + a segment with `ffprobe -show_entries packet=stream_index,pts_time`. On a 30 fps H.264 + AAC fixture the source's own alignment is +21.8 ms, `--audio-delay 200` reads +221.8 ms and `--audio-delay -150` reads -128.2 ms, i.e. exactly the offset asked for, with the video timestamp unchanged in every arm.
 
@@ -260,7 +260,7 @@ live-only session took a rebuild that rejoins at the edge.
 
 `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.
 
-`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route. It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` (at least 0.1) flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` (a release build refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
+`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route, which a build without the `DualLayerDolbyVision` trait accepts and ignores (`--cycle-el` exits 64 there). It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` (at least 0.1) flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` (a release build refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
 
 `--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.
 
@@ -486,7 +486,7 @@ dovi_tool info -i out.rpu -f 0   # expect dovi_profile 8, disable_residual_flag
 
 ## feltest
 
-Runs the Dolby Vision Profile 7 FEL dual-layer pipeline over a real clip: demuxes, splits each packet into the base layer, the enhancement layer (typically 1080p) and the RPU, decodes both layers in hardware `VTDecompressionSession`s, composes each frame with `DoviFelComposer` on Metal, and audits the output twice. The pixel audit reports mean and standard deviation of Y / Cb / Cr, so a black picture or collapsed chroma fails. The metadata audit checks that every delivered frame carries a `DolbyVisionRPUData` attachment, and warns (without failing) when the payload never changes, since a static-metadata clip is valid. The verdict also requires at least one frame the composer actually reconstructed: a bypassed frame comes out as its base layer and counts as output but not as composed. Exit codes: `0` verified, `1` probe error, `2` no frames output, `3` chroma collapsed to a flat 64, `4` frames emitted without per-frame Dolby Vision metadata, `5` no frame was composed. See [dolby-vision-fel.md](dolby-vision-fel.md).
+Needs the `DualLayerDolbyVision` trait; without it the subcommand exits 64 and says so. Runs the Dolby Vision Profile 7 FEL dual-layer pipeline over a real clip: demuxes, splits each packet into the base layer, the enhancement layer (typically 1080p) and the RPU, decodes both layers in hardware `VTDecompressionSession`s, composes each frame with `DoviFelComposer` on Metal, and audits the output twice. The pixel audit reports mean and standard deviation of Y / Cb / Cr, so a black picture or collapsed chroma fails. The metadata audit checks that every delivered frame carries a `DolbyVisionRPUData` attachment, and warns (without failing) when the payload never changes, since a static-metadata clip is valid. The verdict also requires at least one frame the composer actually reconstructed: a bypassed frame comes out as its base layer and counts as output but not as composed. Exit codes: `0` verified, `1` probe error, `2` no frames output, `3` chroma collapsed to a flat 64, `4` frames emitted without per-frame Dolby Vision metadata, `5` no frame was composed. See [dolby-vision-fel.md](dolby-vision-fel.md).
 
 ```bash
 swift run aetherctl feltest [--frames N] <p7-source>
diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index 0ddfa26e3..78881896e 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -4,6 +4,13 @@ How AetherEngine plays a Profile 7 dual-layer source (base layer + enhancement l
 Dolby Vision, what has been proven on device, and the design that does it with bounded CPU, GPU and
 memory while staying correct.
 
+**Optional component.** The route and the composer are compiled only with the `DualLayerDolbyVision`
+package trait, which is off by default ([README › Optional components](../README.md#optional-components)).
+Built without it, `preferDualLayerDolbyVision` is accepted and changes nothing: the route decision
+reports `not taken (built without the DualLayerDolbyVision trait)` and every Profile 7 source takes the
+native route. Everything below describes a build with the trait; `aetherctl play --fel`, `--cycle-el` and
+`aetherctl feltest` need it too.
+
 **Platforms.** Nothing in the route or the composer is tvOS-specific: the two VideoToolbox decoders and
 the Metal kernels are the same on iOS, iPadOS and macOS, the route has no platform gate, and
 `aetherctl play --fel --surface` runs it on a Mac. What is measured per platform is the display half:
@@ -256,7 +263,7 @@ passes it into `VideoRoutingPolicy`:
 | Source | `dolbyVisionHandling` | `preferDualLayerDolbyVision` | Device | Route |
 |---|---|---|---|---|
 | P7, `el_type` FEL | `.automatic` | true (opt-in; the default is false) | VideoToolbox HEVC hardware + Metal | software host, `DualLayerVideoDecoder` |
-| P7, `el_type` FEL | `.automatic` | false (the default), or no VideoToolbox HEVC hardware decode | — | native (8.1 conversion where the display takes Dolby Vision, otherwise the HDR10 base layer) |
+| P7, `el_type` FEL | `.automatic` | false (the default), a build without the `DualLayerDolbyVision` trait, or no VideoToolbox HEVC hardware decode | — | native (8.1 conversion where the display takes Dolby Vision, otherwise the HDR10 base layer) |
 | P7, `el_type` MEL | `.automatic` | any | — | native (as above; the conversion loses nothing for MEL) |
 | P7, any | `.baseLayerOnly` | any | — | HDR10 base layer |
 
@@ -267,11 +274,11 @@ onto the software path by any other combination gets a plain `HardwareVideoDecod
 
 The route is FEL only and capability gated (`DualLayerRouteDecision`, pure and unit-tested). Everything
 else keeps the native route, which plays single-layer 8.1 where the display takes Dolby Vision and the
-HDR10 base layer where it does not: the preference is off, `dolbyVisionHandling` is not `.automatic`, a
+HDR10 base layer where it does not: the preference is off, the build lacks the `DualLayerDolbyVision` trait, `dolbyVisionHandling` is not `.automatic`, a
 live or non-seekable source, a box with no hardware HEVC decoder for the stream, a MEL source (nothing
 to compose), an enhancement layer the probe could not classify, a base layer of unknown size, and a
 stream the box could not decode twice in real time. The checks run in that order (the code's order:
-preference, handling, live/seekable, hardware, `el_type`, geometry, budget). The `el_type` probe (a packet
+preference, trait, handling, live/seekable, hardware, `el_type`, geometry, budget). The `el_type` probe (a packet
 scan and a seek) runs once nothing up to and including the hardware check has ruled the route out, so it
 also runs for a stream that the geometry or the budget then refuses: the MEL / unknown answer outranks
 the size reasons in the log line, and that precedence needs the probe's answer.
@@ -295,6 +302,7 @@ A Profile 7 load logs exactly one line, whichever way it goes (other sources log
 [AetherEngine] DV P7 dual-layer route: taken (el_type=FEL, 3840x2160@23.976, budget 80%)
 [AetherEngine] DV P7 dual-layer route: not taken (el_type=MEL, nothing to compose), keeps the native route (8.1 where the display takes Dolby Vision)
 [AetherEngine] DV P7 dual-layer route: not taken (preferDualLayerDolbyVision is off), keeps the native route (8.1 where the display takes Dolby Vision)
+[AetherEngine] DV P7 dual-layer route: not taken (built without the DualLayerDolbyVision trait), keeps the native route (8.1 where the display takes Dolby Vision)
 [AetherEngine] DV P7 dual-layer route: not taken (over the real-time budget, 3840x2160@60 needs 200% of it), keeps the native route (8.1 where the display takes Dolby Vision)
 [AetherEngine] DV P7 dual-layer route: not taken (base-layer size unknown), keeps the native route (8.1 where the display takes Dolby Vision)
 ```
diff --git a/docs/formats.md b/docs/formats.md
index c69172161..70aef2d19 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -226,9 +226,9 @@ For DV streams the demuxer surfaces the source's `AVDOVIDecoderConfigurationReco
 
 AV1+DV emits a bare `dav1.10.<dvLevel>` primary for Profile 10.0 (DV-only, no base layer to fall back to), and an `av01...` primary plus a supplemental entry for the two cross-compatible profiles: `dav1.10.<dvLevel>/db1p` with `VIDEO-RANGE=PQ` for Profile 10.1 (HDR10-compat base) and `dav1.10.<dvLevel>/db4h` with `VIDEO-RANGE=HLG` for Profile 10.4 (HLG-compat base), on hardware-AV1 hosts. Same split as HEVC: the `dav1` sample entry belongs to the profile without a base layer the way `dvh1` belongs to Profile 5, and a cross-compatible profile carries its base layer's own sample entry so a client that cannot read Dolby Vision still plays it.
 
-**Profile 7** (dual-layer, the common UHD-Blu-ray remux profile) is handled according to `LoadOptions.preferDualLayerDolbyVision` (default `false`: dual-layer composition is opt-in) and `LoadOptions.dolbyVisionHandling`:
-- **Dual-layer composition (`preferDualLayerDolbyVision = true`, `dolbyVisionHandling` `.automatic`, `el_type` FEL, VideoToolbox HEVC hardware decode)**: Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`. Each packet is split into the 4K base layer (BL), the enhancement layer (EL, typically 1080p, carried in `unspec63` NAL units) and the RPU (`unspec62`). Both layers decode in their own `VTDecompressionSession`; `DoviFelComposer` applies the RPU's reshaping (polynomial luma, MMR chroma) and the inverse-NLQ residual from the upsampled EL at 12-bit precision, then an ordered 8×8 Bayer dither (inverted on odd frames) takes the result to 10-bit P010 for `AVSampleBufferDisplayLayer`. The composed frame also carries the RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, with `DolbyCompatibilityID` set to the string `"1"`; tvOS 27 reads it on every frame and applies Dolby Vision display management, so L1 / L2 dynamic metadata reaches the panel. A MEL source never reaches the dual-layer decoder: the route is FEL only, and MEL (nothing to compose) keeps the native route below. The route needs a seekable VOD and is logged once per Profile 7 load (`DV P7 dual-layer route: taken` / `not taken (<reason>)`). It does not consult the display: on a display that does not take Dolby Vision the route is still taken and the composed picture is presented with its attached metadata, tvOS deciding how; the native route would have played the converted Profile 8.1 there. The software host also plays an E-AC-3 Atmos track as its channel-bed core (no objects). The stream is classified by `el_type` alone; an RPU that sets `disable_residual_flag` only switches the residual off for that frame and never changes the classification. See [dolby-vision-fel.md](dolby-vision-fel.md) for the design.
-- **Single-layer conversion (the default: `preferDualLayerDolbyVision = false`, or no VideoToolbox HEVC hardware decode)**: No Apple platform has a Profile 7 decoder, so the engine converts the stream to single-layer **Profile 8.1** live during muxing: the RPU of each video packet is rewritten with [libdovi](https://github.com/superuser404notfound/LibDovi) (`dovi_convert_rpu_with_mode`, mode 2, the same transform as `dovi_tool -m 2`), the enhancement-layer NALs are dropped, and the container `dvvC` is set to Profile 8.1. The conversion runs on every display and the result is served exactly as a Profile 8.1 is: on a DV-capable display this means real Dolby Vision (`dvh1.08/db1p` supplemental) instead of the plain HDR10 base, and on a display without Dolby Vision the kept `dvvC` lets AVPlayer tone-map from the RPU rather than from the base layer's static metadata, the way mpv plays Profile 7 without an EL decoder. It used to skip the conversion and strip the record there, which cost every Mac (no per-mode table) and every HDR10 / SDR panel the RPU and shipped the enhancement layer into segments nothing decodes. The conversion is loss-free relative to what Apple could show before (the enhancement layer was never decodable on Apple hardware). MEL and FEL sources are both handled; a Full Enhancement Layer (FEL) source is logged, since its enhancement layer, which a native Profile 7 player would fold in, is discarded on this route (the dual-layer route above keeps it) while a Minimal (MEL) source loses nothing. Any per-packet conversion failure drops that RPU so the frame degrades to the clean HDR10 base, rather than shipping a Profile 7 RPU inside a container already declared 8.1. A session that converts publishes `dolbyVisionConversion = .profile7ToProfile81`, so a host label can name the profile actually served next to `sourceDVProfile`.
+**Profile 7** (dual-layer, the common UHD-Blu-ray remux profile) is handled according to `LoadOptions.preferDualLayerDolbyVision` (default `false`: dual-layer composition is opt-in) and `LoadOptions.dolbyVisionHandling`. The dual-layer composer is an optional component, compiled only with the `DualLayerDolbyVision` package trait (off by default, [README › Optional components](../README.md#optional-components)); built without it, `preferDualLayerDolbyVision` changes nothing and every Profile 7 source takes the single-layer conversion:
+- **Dual-layer composition (`DualLayerDolbyVision` trait, `preferDualLayerDolbyVision = true`, `dolbyVisionHandling` `.automatic`, `el_type` FEL, VideoToolbox HEVC hardware decode)**: Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`. Each packet is split into the 4K base layer (BL), the enhancement layer (EL, typically 1080p, carried in `unspec63` NAL units) and the RPU (`unspec62`). Both layers decode in their own `VTDecompressionSession`; `DoviFelComposer` applies the RPU's reshaping (polynomial luma, MMR chroma) and the inverse-NLQ residual from the upsampled EL at 12-bit precision, then an ordered 8×8 Bayer dither (inverted on odd frames) takes the result to 10-bit P010 for `AVSampleBufferDisplayLayer`. The composed frame also carries the RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, with `DolbyCompatibilityID` set to the string `"1"`; tvOS 27 reads it on every frame and applies Dolby Vision display management, so L1 / L2 dynamic metadata reaches the panel. A MEL source never reaches the dual-layer decoder: the route is FEL only, and MEL (nothing to compose) keeps the native route below. The route needs a seekable VOD and is logged once per Profile 7 load (`DV P7 dual-layer route: taken` / `not taken (<reason>)`). It does not consult the display: on a display that does not take Dolby Vision the route is still taken and the composed picture is presented with its attached metadata, tvOS deciding how; the native route would have played the converted Profile 8.1 there. The software host also plays an E-AC-3 Atmos track as its channel-bed core (no objects). The stream is classified by `el_type` alone; an RPU that sets `disable_residual_flag` only switches the residual off for that frame and never changes the classification. See [dolby-vision-fel.md](dolby-vision-fel.md) for the design.
+- **Single-layer conversion (the default: `preferDualLayerDolbyVision = false`, a build without the `DualLayerDolbyVision` trait, or no VideoToolbox HEVC hardware decode)**: No Apple platform has a Profile 7 decoder, so the engine converts the stream to single-layer **Profile 8.1** live during muxing: the RPU of each video packet is rewritten with [libdovi](https://github.com/superuser404notfound/LibDovi) (`dovi_convert_rpu_with_mode`, mode 2, the same transform as `dovi_tool -m 2`), the enhancement-layer NALs are dropped, and the container `dvvC` is set to Profile 8.1. The conversion runs on every display and the result is served exactly as a Profile 8.1 is: on a DV-capable display this means real Dolby Vision (`dvh1.08/db1p` supplemental) instead of the plain HDR10 base, and on a display without Dolby Vision the kept `dvvC` lets AVPlayer tone-map from the RPU rather than from the base layer's static metadata, the way mpv plays Profile 7 without an EL decoder. It used to skip the conversion and strip the record there, which cost every Mac (no per-mode table) and every HDR10 / SDR panel the RPU and shipped the enhancement layer into segments nothing decodes. The conversion is loss-free relative to what Apple could show before (the enhancement layer was never decodable on Apple hardware). MEL and FEL sources are both handled; a Full Enhancement Layer (FEL) source is logged, since its enhancement layer, which a native Profile 7 player would fold in, is discarded on this route (the dual-layer route above keeps it) while a Minimal (MEL) source loses nothing. Any per-packet conversion failure drops that RPU so the frame degrades to the clean HDR10 base, rather than shipping a Profile 7 RPU inside a container already declared 8.1. A session that converts publishes `dolbyVisionConversion = .profile7ToProfile81`, so a host label can name the profile actually served next to `sourceDVProfile`.
 
 **SDR-compatible-base profiles** (HEVC **Profile 8.2**, AV1 **Profile 10.2**) carry a Rec.709 base layer that no Apple platform has a DV decoder for. The engine strips the `dvcC` / DV config and plays the base as plain `hvc1` / `av01` (logging `not DV-routable, playing Rec.709 base`); there is no Dolby Vision on any display for these, on DV panels and SDR panels alike.
 
@@ -354,7 +354,7 @@ The renderer is allocentric, the model Atmos metadata is authored in: the room i
 
 **Track choice.** With the option on, the automatic audio pick prefers a TrueHD Atmos track over the other tracks of the same language: of the `preferredAudioLanguages` match, or of the session's default track when no preference decides it. It never crosses a language or a dub (a region or script both tags state and disagree on), never picks a commentary for it, applies only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later), and an explicit `audioSourceStreamIndexOverride` still wins. Without that, a film carrying DTS-HD and TrueHD Atmos in one language usually opened on whichever the container listed first.
 
-It is opt-in because it is a trade: APAC is lossy, at several Mbit/s, in place of the lossless 7.1 the channel bridge delivers. It applies only to TrueHD that FFmpeg marks as Atmos, at 48 kHz, on OS 26 or later where the APAC encoder exists; anything else, and any failure to start, keeps `audioBridgeMode` with the audio intact. Silo built the first implementation in its fork and offered it as the reference this one is ported from. The decoder comes with the `TrueHDObjectAudio` package trait, on by default; built without it, TrueHD Atmos keeps the channel bridge and the session log says so ([README › Package traits](../README.md#package-traits)).
+It is opt-in because it is a trade: APAC is lossy, at several Mbit/s, in place of the lossless 7.1 the channel bridge delivers. It applies only to TrueHD that FFmpeg marks as Atmos, at 48 kHz, on OS 26 or later where the APAC encoder exists; anything else, and any failure to start, keeps `audioBridgeMode` with the audio intact. Silo built the first implementation in its fork and offered it as the reference this one is ported from. The decoder and the renderer are an optional component, compiled only with the `TrueHDObjectAudio` package trait, off by default; built without it, TrueHD Atmos keeps the channel bridge whatever the option asks, and the session log says so ([README › Optional components](../README.md#optional-components)).
 
 **Atmos on the receiver (tvOS).** tvOS sends APAC over HDMI as Dolby MAT, and some sinks show Dolby Atmos for it on their own, but not all: a Samsung HW-Q990C soundbar fed by an Apple TV 4K (tvOS 27.2) played APAC without ever showing Atmos, although `AVAudioSession` reported a MAT format throughout. While an APAC session plays, the engine therefore loops a silent E-AC-3 stream signalled as Dolby Atmos on a second, unmuted player (`AtmosOutputActivator`). On the same setup that brought the soundbar to Atmos before the first frame and kept it there across a seek. Nothing the app can read (`AVAudioSession`'s output format or channel count) tracked the indicator, so only the sink can confirm it. The stream is 2 s of digital silence written bit by bit from the E-AC-3 and object audio specifications (`Scripts/make-silent-atmos.swift`), plays only while the engine's player plays or waits to play an APAC item, and is released otherwise. iOS and macOS do not run it.
 
@@ -366,7 +366,7 @@ A linked peak limiter sits between the renderer and the encoder: the APAC encode
 
 ### DTS\:X with heights
 
-DTS:X reaches the bridge the same way TrueHD Atmos does: Apple TV cannot bitstream DTS-HD, so `audioBridgeMode` decodes the lossless 7.1, and on a DTS:X track that 7.1 is a compatible downmix into which the encoder folded the four height channels and any objects. `objectAudioRendering = .apac(layout)` keeps them: a DTS-HD Master Audio track goes through [LibDTSX](https://github.com/superuser404notfound/LibDTSX) (the `dca` crate from harletty-bridge behind a C API, packaged like LibTrueHD) into the same renderer, limiter and APAC encoder. LibDTSX does the DTS-specific work, so the engine side is a speaker mapping (`DTSXObjectAudioDecoder`): it subtracts every fold the frame states (or that `dca`'s fold renderer recomputes for an object the encoder panned into the bed) from the bed, so the bed, the heights and the objects play side by side without anything playing twice, and it places DTS:X's angular object positions in LibTrueHD's room coordinates. The reference sphere is projected onto the room's boundary through the speakers' angles (centre 0°, front ±30°, wide ±60°, side ±90°, rear ±145°), the ceiling reached at the 45° of a height speaker and its centre straight overhead, so the dual-balance panner places a sound between two speakers in the same proportion an angular panner would. LibDTSX comes with the `DTSXObjectAudio` package trait, on by default, in the same way.
+DTS:X reaches the bridge the same way TrueHD Atmos does: Apple TV cannot bitstream DTS-HD, so `audioBridgeMode` decodes the lossless 7.1, and on a DTS:X track that 7.1 is a compatible downmix into which the encoder folded the four height channels and any objects. `objectAudioRendering = .apac(layout)` keeps them in a build with the `DTSXObjectAudio` package trait (off by default; without it DTS-HD keeps the channel bridge whatever the option asks, [README › Optional components](../README.md#optional-components)): a DTS-HD Master Audio track goes through [LibDTSX](https://github.com/superuser404notfound/LibDTSX) (the `dca` crate from harletty-bridge behind a C API, packaged like LibTrueHD) into the same renderer, limiter and APAC encoder. LibDTSX does the DTS-specific work, so the engine side is a speaker mapping (`DTSXObjectAudioDecoder`): it subtracts every fold the frame states (or that `dca`'s fold renderer recomputes for an object the encoder panned into the bed) from the bed, so the bed, the heights and the objects play side by side without anything playing twice, and it places DTS:X's angular object positions in LibTrueHD's room coordinates. The reference sphere is projected onto the room's boundary through the speakers' angles (centre 0°, front ±30°, wide ±60°, side ±90°, rear ±145°), the ceiling reached at the 45° of a height speaker and its centre straight overhead, so the dual-balance panner places a sound between two speakers in the same proportion an angular panner would. LibDTSX comes with the `DTSXObjectAudio` package trait, off by default, in the same way.
 
 The standard presentation, which every DTS:X film in SpatialAudioBridge's library census used in every frame, is a 7.1 bed and four fixed heights (top front and top back pairs), all routed discretely: rendered into 7.1.4, *8 Mile*, *The Bourne Identity* and the DTS:X Object Emulator demo give each speaker exactly its channel, bit for bit what SpatialAudioBridge's DTS:X renderer gives. The alternate presentations add one to five objects; `dca` classifies them from a corpus and calls them experimental. *Independence Day* (FFmpeg: "DTS-HD MA + DTS:X IMAX") is one: two static objects at ±34.5° and 12° up, which pan mostly into the front pair, a little into the sides and the front heights. Against SpatialAudioBridge's renderer, which pans DTS:X by angle over a bed ring and a height ring, the 7.1.4 render of a minute of it points the sound the same way within 0.07° (median of 200 ms windows, energy-weighted; 90th percentile 0.39°), and of the D4 trailer's five moving objects within 0.23° (2.3°); the floor channels correlate at 1.0000, and the ceiling's share of the energy is 0.1 to 0.2 points lower. These figures were taken against the panner before #742 moved its top speakers from the room's corners a quarter in, so the object renders now differ from them slightly; the standard presentation routes discretely and is unaffected.
 

From bd54b415660262131cbef87b1269fab36f9008af Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 09:44:55 +0200
Subject: [PATCH 108/132] ci: build and test with every optional component
 enabled

The default build now has the optional components off, so the former
"traits off" build step is what `swift build` already does. In its place
the macOS job builds and runs the suite with --enable-all-traits, which
keeps the opt-in object renderer and FEL composer compiling and their
tests running. Steps in the existing job rather than a new one, to stay
within the concurrent macOS runners; its timeout goes to 50 minutes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/ci.yml | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7078fc2d3..49519b345 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -25,7 +25,7 @@ jobs:
   test-macos:
     name: swift test (macOS)
     runs-on: xcode-27
-    timeout-minutes: 30
+    timeout-minutes: 50
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
@@ -37,10 +37,6 @@ jobs:
       - name: swift build
         run: swift build
 
-      # The object-audio decoder libraries are traits a host can turn off; keep that build compiling.
-      - name: swift build (traits off)
-        run: swift build --disable-default-traits --build-tests --scratch-path .build-notraits
-
       # 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
@@ -59,6 +55,16 @@ jobs:
           LIBDISPATCH_COOPERATIVE_POOL_STRICT: "1"
         run: swift test --skip-build --disable-xctest
 
+      # The optional components (TrueHDObjectAudio, DTSXObjectAudio, DualLayerDolbyVision) are off by
+      # default, so every step above builds and tests without them. This build and run keep the opt-in
+      # code compiling and its tests running. Steps in this job rather than a job of their own, to stay
+      # within the account's concurrent macOS runners.
+      - name: swift build (all traits)
+        run: swift build --enable-all-traits --build-tests --scratch-path .build-alltraits
+
+      - name: swift test (all traits)
+        run: swift test --enable-all-traits --skip-build --scratch-path .build-alltraits
+
       - name: Software VOD packet-cache regressions
         run: |
           bash Scripts/test-software-packet-coverage.sh

From 3672c4c57669b62c21992d1629325b0d861e8d64 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 11:09:24 +0200
Subject: [PATCH 109/132] feat: Dolby Vision still reshaping is the opt-in
 DolbyVisionStillReshaping trait

DolbyVisionStillConverter (the RPU reshaping that turns a Profile 5 /
AV1 Profile 10.0 frame into a still) is compiled only with the new
DolbyVisionStillReshaping trait, off by default. Without it such a frame
yields no still instead of falling through to the standard path, which
would read its IPT planes as YCbCr: FrameDecodeContext returns nil before
reading or decoding anything, the native session reports
`yieldsStills == false`, so scrubThumbnail, scrubPreviewFrame and the live
stills return nil at once and supportsCacheBackedStills is false, the
I-frame rendition is absent (`dolbyVisionStillsNotBuiltIn`), and an audio
switch skips the held picture with its reason. The session logs this once.
Profile 8.x, HDR10, HLG and SDR stills are unaffected.

AetherEngine.OptionalComponent is the public runtime query for all four
components (`isBuiltIn`, `traitName`), so a host can hide a setting its
build would ignore. The internal trait checks now read it.

dualLayerRouteRefusal no longer refuses a preferDualLayerDolbyVision or
dolbyVisionHandling correction in a build without DualLayerDolbyVision,
where it moves nothing. LoadOptions.objectAudioRendering,
preferDualLayerDolbyVision and ObjectAudioRendering say in their doc
comments that they are no-ops without their trait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Package.resolved                              |  2 +-
 Package.swift                                 | 11 ++-
 .../AetherEngine+HeldPicture.swift            | 10 ++-
 Sources/AetherEngine/AetherEngine+Live.swift  |  1 +
 .../AetherEngine+OptionalComponents.swift     | 54 +++++++++++
 Sources/AetherEngine/AetherEngine+Probe.swift | 16 +---
 .../AetherEngine+ReloadWithOptions.swift      |  5 +-
 .../AetherEngine+ScrubThumbnail.swift         |  8 +-
 .../Audio/Spatial/ObjectAudioRendering.swift  |  4 +
 .../Decoder/DualLayerRouteDecision.swift      |  6 +-
 .../DolbyVisionStillConverter.swift           |  3 +
 .../FrameExtractor/FrameDecodeContext.swift   | 11 +++
 Sources/AetherEngine/PlayerState.swift        |  7 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   | 14 ++-
 .../Video/IFrameRenditionEligibility.swift    |  6 ++
 .../DolbyVisionColorTests.swift               |  3 +
 .../DoviGpuCurveSweepTests.swift              |  3 +
 .../FrameDecodeContextHardwareTests.swift     |  5 ++
 .../IFrameRenditionEligibilityTests.swift     |  4 +-
 .../IFrameSessionTests.swift                  | 16 ++++
 .../ItemSwapStillTests.swift                  | 30 +++++++
 .../OptionalComponentFallbackTests.swift      | 89 ++++++++++++++++++-
 22 files changed, 273 insertions(+), 35 deletions(-)
 create mode 100644 Sources/AetherEngine/AetherEngine+OptionalComponents.swift

diff --git a/Package.resolved b/Package.resolved
index 69765087e..fd0a9b6c9 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "36e04bcc609a78f08b50a1d52363ff6d088a26a672a10b7ff9f948ae3a221929",
+  "originHash" : "856dc654c740b018d3c4a31d0d78988b4c57927f83aa3d4d22ee9c48b424e1b6",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
diff --git a/Package.swift b/Package.swift
index a8d5d147e..67945ff2f 100644
--- a/Package.swift
+++ b/Package.swift
@@ -25,12 +25,13 @@ let package = Package(
         // platforms. The target is preserved below so `swift build` on
         // macOS still produces the CLI for upstream development.
     ],
-    // Three optional components, all off by default. A host that wants one enables its trait
+    // Four optional components, all off by default. A host that wants one enables its trait
     // (`.package(url:..., traits: [...])`, or the package's traits in Xcode); without it the code is not
     // compiled and the library behind it is not linked. These components may be subject to third-party
     // patent licensing; an integrator that enables one is responsible for its own licensing. Off, the
-    // matching LoadOptions are accepted and change nothing: object audio keeps the channel bridge, and a
-    // Profile 7 source keeps the native route. LibDovi, FFmpeg and everything else are unaffected.
+    // matching LoadOptions are accepted and change nothing: object audio keeps the channel bridge, a
+    // Profile 7 source keeps the native route, and a Dolby Vision Profile 5 / 10.0 source yields no
+    // scrub still or held picture. LibDovi, FFmpeg and everything else are unaffected.
     traits: [
         .trait(
             name: "TrueHDObjectAudio",
@@ -44,6 +45,10 @@ let package = Package(
             name: "DualLayerDolbyVision",
             description: "Compile the Dolby Vision Profile 7 FEL dual-layer composer, so preferDualLayerDolbyVision can take that route."
         ),
+        .trait(
+            name: "DolbyVisionStillReshaping",
+            description: "Compile the CPU reshaping that turns a Dolby Vision Profile 5 / 10.0 frame into a still (scrub thumbnails, I-frame stills, held pictures)."
+        ),
         .default(enabledTraits: []),
     ],
     dependencies: [
diff --git a/Sources/AetherEngine/AetherEngine+HeldPicture.swift b/Sources/AetherEngine/AetherEngine+HeldPicture.swift
index 30ec6263a..e023ca5ea 100644
--- a/Sources/AetherEngine/AetherEngine+HeldPicture.swift
+++ b/Sources/AetherEngine/AetherEngine+HeldPicture.swift
@@ -26,7 +26,8 @@ extension AetherEngine {
     /// fresh output sees anything, which is why the caller pauses first). Dolby Vision without a
     /// displayable base layer (Profile 5, AV1 Profile 10) cannot be taken from that output, which
     /// vends the base layer; it is decoded from the resident segment instead, frame-accurately and
-    /// through the same RPU reshaping the scrub stills use (`DolbyVisionStillConverter`).
+    /// through the same RPU reshaping the scrub stills use (`DolbyVisionStillConverter`), which only a
+    /// build with the `DolbyVisionStillReshaping` trait has; without it the hold is skipped.
     ///
     /// Software: the rebuild replaces host and layer, and the old host's `stop()` flushes its layer to
     /// black for the whole startup of the new one. The frame is read back from the renderer.
@@ -57,6 +58,13 @@ extension AetherEngine {
         let held: (frame: CVPixelBuffer, isHDR: Bool, route: String)?
         if let host = nativeSource {
             if Self.heldPictureNeedsReshaping(videoFormat: videoFormat, dolbyVisionProfile: sourceDVProfile) {
+                // Without the reshaping there is no correct picture to hold, so nothing is decoded.
+                guard OptionalComponent.dolbyVisionStillReshaping.isBuiltIn else {
+                    heldPictureLastSkip = "Dolby Vision still reshaping not built in"
+                    EngineLog.emit("[AetherEngine] held picture: skipped (Dolby Vision still reshaping not built in, "
+                                   + "DolbyVisionStillReshaping trait off)", category: .engine)
+                    return
+                }
                 held = await reshapedDolbyVisionStill(itemSeconds: host.avPlayer.currentTime().seconds)
                     .map { ($0, false, "Dolby Vision reshaped") }
             } else {
diff --git a/Sources/AetherEngine/AetherEngine+Live.swift b/Sources/AetherEngine/AetherEngine+Live.swift
index f5dff916f..6c400d758 100644
--- a/Sources/AetherEngine/AetherEngine+Live.swift
+++ b/Sources/AetherEngine/AetherEngine+Live.swift
@@ -21,6 +21,7 @@ extension AetherEngine {
             // A zap between the request and the frame would hand the new channel the old one's picture.
             return loadGeneration == gen ? image : nil
         }
+        guard session.yieldsStills else { return nil }
         // Segment table and tfdt use continuous output time, including across source PTS rebases.
         let outputSeconds = seconds - liveSessionShiftSeconds
         let gen = loadGeneration
diff --git a/Sources/AetherEngine/AetherEngine+OptionalComponents.swift b/Sources/AetherEngine/AetherEngine+OptionalComponents.swift
new file mode 100644
index 000000000..e929fdd75
--- /dev/null
+++ b/Sources/AetherEngine/AetherEngine+OptionalComponents.swift
@@ -0,0 +1,54 @@
+import Foundation
+
+extension AetherEngine {
+
+    /// The parts of the engine that are compiled only when a host enables their package trait, all off
+    /// by default (README, "Optional components"). Without its trait a component is not in the binary
+    /// and the option that asks for it changes nothing, so a host reads `isBuiltIn` to hide a setting
+    /// that would do nothing in its build.
+    public enum OptionalComponent: String, CaseIterable, Sendable {
+        /// TrueHD Atmos object rendering for `LoadOptions.objectAudioRendering` (trait `TrueHDObjectAudio`).
+        case trueHDObjectAudio = "TrueHDObjectAudio"
+        /// DTS:X height and object rendering for `LoadOptions.objectAudioRendering` (trait `DTSXObjectAudio`).
+        case dtsxObjectAudio = "DTSXObjectAudio"
+        /// Profile 7 FEL dual-layer composition for `LoadOptions.preferDualLayerDolbyVision`
+        /// (trait `DualLayerDolbyVision`).
+        case dualLayerDolbyVision = "DualLayerDolbyVision"
+        /// Stills (scrub thumbnails, I-frame stills, held pictures) of Dolby Vision Profile 5 / 10.0
+        /// sources, which have no base layer to show (trait `DolbyVisionStillReshaping`).
+        case dolbyVisionStillReshaping = "DolbyVisionStillReshaping"
+
+        /// The package trait that compiles the component.
+        public var traitName: String { rawValue }
+
+        /// Whether this build carries the component.
+        public var isBuiltIn: Bool {
+            switch self {
+            case .trueHDObjectAudio:
+                #if TrueHDObjectAudio
+                return true
+                #else
+                return false
+                #endif
+            case .dtsxObjectAudio:
+                #if DTSXObjectAudio
+                return true
+                #else
+                return false
+                #endif
+            case .dualLayerDolbyVision:
+                #if DualLayerDolbyVision
+                return true
+                #else
+                return false
+                #endif
+            case .dolbyVisionStillReshaping:
+                #if DolbyVisionStillReshaping
+                return true
+                #else
+                return false
+                #endif
+            }
+        }
+    }
+}
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index 727c97dde..ee9c5df16 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -703,21 +703,9 @@ extension AetherEngine {
 
     /// Whether the build links the codec's object decoder (#777: its package trait). Without it the codec
     /// keeps the channel bridge, so the pick has no heights to prefer it for.
-    nonisolated static let linksTrueHDObjectDecoder: Bool = {
-        #if TrueHDObjectAudio
-        return true
-        #else
-        return false
-        #endif
-    }()
+    nonisolated static let linksTrueHDObjectDecoder = OptionalComponent.trueHDObjectAudio.isBuiltIn
 
-    nonisolated static let linksDTSXObjectDecoder: Bool = {
-        #if DTSXObjectAudio
-        return true
-        #else
-        return false
-        #endif
-    }()
+    nonisolated static let linksDTSXObjectDecoder = OptionalComponent.dtsxObjectAudio.isBuiltIn
 
     /// The tracks object rendering keeps the heights of.
     nonisolated static func isRenderableObjectAudio(_ track: TrackInfo) -> Bool {
diff --git a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
index 2a6b213c9..aaa5ba4e5 100644
--- a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
+++ b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
@@ -398,14 +398,15 @@ enum SessionOptionCorrection {
     /// handling refuses when the preference is on, where it can turn the route on or off. With the
     /// preference off the handling cannot move the route. Only a Profile 7 source can route
     /// differently, so any other source is not refused: the change there moves nothing, which is also
-    /// what the rebuild does.
+    /// what the rebuild does. A build without the `DualLayerDolbyVision` trait has no such route, so
+    /// nothing is refused there.
     static func dualLayerRouteRefusal(
         isCustomSource: Bool,
         current: LoadOptions,
         proposed: LoadOptions,
         dvProfile: Int?
     ) -> SessionReloadRefusal? {
-        guard isCustomSource, dvProfile == 7 else { return nil }
+        guard DualLayerRouteDecision.isBuiltIn, isCustomSource, dvProfile == 7 else { return nil }
         let preferenceChanged = proposed.preferDualLayerDolbyVision != current.preferDualLayerDolbyVision
         let handlingMovesRoute = proposed.dolbyVisionHandling != current.dolbyVisionHandling
             && proposed.preferDualLayerDolbyVision
diff --git a/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift b/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
index b135e7620..5005c2bf8 100644
--- a/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
+++ b/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
@@ -26,6 +26,7 @@ extension AetherEngine {
                                                      maxWidth: maxWidth, isCancelled: isCancelled)
             return gen == loadGeneration && !Task.isCancelled && !isCancelled() ? result : nil
         }
+        guard session.yieldsStills else { return nil }
         // Freeze both axes. VOD segment indices use the plan's keyframe origin;
         // the segment's bytes retain their own epoch normalization after restart.
         let origin = sourcePresentationOrigin
@@ -108,6 +109,7 @@ extension AetherEngine {
             let image = await host.vodScrubStill(atSessionSeconds: seconds, maxWidth: maxWidth)
             return loadGeneration == gen ? image : nil
         }
+        guard session.yieldsStills else { return nil }
         let gen = loadGeneration
         let source = await BlockingWork.detached(priority: .userInitiated) { [session] in
             session.scrubThumbnailSource(atSeconds: seconds)
@@ -146,9 +148,11 @@ extension AetherEngine {
     /// 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.
+    /// nils from `scrubThumbnail` while a segment is still being produced are expected. False as well
+    /// on a Dolby Vision Profile 5 / 10.0 session in a build without the `DolbyVisionStillReshaping`
+    /// trait, where no frame can become a correct still.
     public var supportsCacheBackedStills: Bool {
-        if nativeVideoSession != nil { return true }
+        if let session = nativeVideoSession { return session.yieldsStills }
         guard let softwareHost else { return false }
         return isLive || softwareHost.servesPacketCacheStills
     }
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioRendering.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioRendering.swift
index dcce8a794..11b6b7447 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectAudioRendering.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioRendering.swift
@@ -12,6 +12,10 @@ import Foundation
 /// Applies to TrueHD sources FFmpeg identifies as Atmos (profile 30) and to DTS-HD Master Audio that
 /// LibDTSX confirms as DTS:X on its first frames, at 48 kHz, and only on OS 26 and later, where the
 /// APAC encoder API exists. Everything else keeps `audioBridgeMode`.
+///
+/// The renderer is an optional component: TrueHD needs the `TrueHDObjectAudio` package trait and DTS:X
+/// the `DTSXObjectAudio` trait, both off by default. Without a codec's trait `.apac` is a no-op for it
+/// (`AetherEngine.OptionalComponent.isBuiltIn` answers which are in a build).
 public enum ObjectAudioRendering: Equatable, Sendable {
     case off
     /// Render into `layout`, which should match the speakers the receiver actually drives.
diff --git a/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift b/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
index 997391dfa..b28eea458 100644
--- a/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
+++ b/Sources/AetherEngine/Decoder/DualLayerRouteDecision.swift
@@ -54,11 +54,7 @@ enum DualLayerRouteDecision: Equatable {
     }
 
     /// Whether the composer is compiled in (the `DualLayerDolbyVision` package trait, off by default).
-    #if DualLayerDolbyVision
-    static let isBuiltIn = true
-    #else
-    static let isBuiltIn = false
-    #endif
+    static let isBuiltIn = AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn
 
     /// The most pixels per second, base layer plus enhancement layer, the route is willing to decode in
     /// real time: UHD 3840x2160 at 30 fps (248.8 Mpx/s) plus a 1920x1080 enhancement layer at 30 fps
diff --git a/Sources/AetherEngine/FrameExtractor/DolbyVisionStillConverter.swift b/Sources/AetherEngine/FrameExtractor/DolbyVisionStillConverter.swift
index 25c906462..278af26b6 100644
--- a/Sources/AetherEngine/FrameExtractor/DolbyVisionStillConverter.swift
+++ b/Sources/AetherEngine/FrameExtractor/DolbyVisionStillConverter.swift
@@ -1,3 +1,5 @@
+// Only with the DolbyVisionStillReshaping trait (off by default).
+#if DolbyVisionStillReshaping
 import Foundation
 import CoreGraphics
 import AetherLibavutil
@@ -415,3 +417,4 @@ enum DolbyVisionStillConverter {
         UInt8(min(max(x, 0), 1) * 255.0 + 0.5)
     }
 }
+#endif
diff --git a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
index 4f56a8e4b..67e33ae76 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
@@ -90,6 +90,12 @@ final class FrameDecodeContext: @unchecked Sendable {
         return false
     }
 
+    /// Whether a source's frames can become a still in this build. A Dolby Vision Profile 5 / 10.0
+    /// frame needs `DolbyVisionStillConverter`, which only the `DolbyVisionStillReshaping` trait compiles.
+    static func yieldsStill(dolbyVisionNoBaseLayer: Bool) -> Bool {
+        !dolbyVisionNoBaseLayer || AetherEngine.OptionalComponent.dolbyVisionStillReshaping.isBuiltIn
+    }
+
     /// 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
@@ -435,6 +441,9 @@ final class FrameDecodeContext: @unchecked Sendable {
         reportDecodedTime: ((Double?) -> Void)? = nil
     ) -> CGImage? {
         guard isOpen, let ctx = codecContext, let demuxer else { return nil }
+        // Without the reshaping these planes are IPT, which the standard path would read as YCbCr
+        // (the green / magenta still of #103): no still at all, and nothing read or decoded for it.
+        guard Self.yieldsStill(dolbyVisionNoBaseLayer: isDolbyVisionNoBaseLayer) else { return nil }
 
         // Bound this decode's HTTP reads so a stalled remote source can't park the
         // serial decode queue and freeze the scrub preview (issue #27). No-op for
@@ -531,6 +540,7 @@ final class FrameDecodeContext: @unchecked Sendable {
             let width = mode == .thumbnail
                 ? targetWidth
                 : Self.clampedWidth(frame: f, maxSize: maxSize)
+            #if DolbyVisionStillReshaping
             if isDolbyVisionNoBaseLayer {
                 let sar = resolvedSAR(frame: f)
                 if let img = DolbyVisionStillConverter.makeImage(frame: f, targetWidth: width, sar: sar) {
@@ -538,6 +548,7 @@ final class FrameDecodeContext: @unchecked Sendable {
                 }
                 // No DV metadata on this frame / unsupported layout: fall through to the standard path.
             }
+            #endif
             if isHDR {
                 var toned = HDRToneMapper.toneMap(frame: f, targetWidth: width, timeBase: timeBase)
                 if toned != nil {
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 00803a040..2e059c4ed 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -481,6 +481,9 @@ public struct LoadOptions: Sendable, Equatable {
     /// layer where it does not); the load logs one line saying which route it took and why. The source
     /// must be a seekable VOD: live and non-seekable sources keep the native route. Default false.
     ///
+    /// Needs the `DualLayerDolbyVision` package trait (off by default): without it this is a no-op and
+    /// every Profile 7 source keeps the native route (`AetherEngine.OptionalComponent.dualLayerDolbyVision`).
+    ///
     /// The route does not consult the display. With this on and a display that does not take Dolby
     /// Vision, the route is still taken: the composed full-FEL picture is presented with its attached
     /// metadata, and how tvOS presents it is up to the platform. The audio trade-off below applies there
@@ -574,7 +577,9 @@ public struct LoadOptions: Sendable, Equatable {
     /// TrueHD Atmos and DTS:X delivery (#731). `.off` (default) keeps `audioBridgeMode`'s 7.1 channel
     /// decode; `.apac(layout)` renders the objects and heights into `layout` and delivers Apple
     /// Positional Audio, which reaches an Atmos receiver as Dolby MAT with its heights. See
-    /// `ObjectAudioRendering`.
+    /// `ObjectAudioRendering`. Needs the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by
+    /// default): without a codec's trait this is a no-op for that codec, which keeps `audioBridgeMode`
+    /// (`AetherEngine.OptionalComponent`).
     public var objectAudioRendering: ObjectAudioRendering
 
     /// Treat the source as a live stream. `seek(to:)` becomes a no-op; `isLive` surface reflects this for host UIs. Set explicitly: auto-detection from `probe.durationSeconds == 0` is too noisy (VOD MKVs with broken duration headers). Default `false`.
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 2f2e3c553..f60b2ccae 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -254,6 +254,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// 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)
+    /// False for a Dolby Vision Profile 5 / 10.0 source in a build without the
+    /// `DolbyVisionStillReshaping` trait: none of its frames can become a correct still.
+    private(set) var yieldsStills = true
     /// AE#682: the server withheld the JPEG I-frame playlist because AVPlayer never asked for a media
     /// segment, which is how a refused HDR variant looks next to an SDR I-frame rendition.
     var iFrameRenditionWithheld: Bool { server?.iFrameRenditionWithheld ?? false }
@@ -2233,6 +2236,14 @@ 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.
+        let stillsAvailable = FrameDecodeContext.yieldsStill(
+            dolbyVisionNoBaseLayer: FrameDecodeContext.isDVNoBaseLayer(codecpar: codecpar))
+        yieldsStills = stillsAvailable
+        if !stillsAvailable {
+            EngineLog.emit("[HLSVideoEngine] Dolby Vision Profile 5 / 10.0 stills are not built in "
+                           + "(DolbyVisionStillReshaping trait off): no scrub thumbnails, I-frame stills "
+                           + "or held pictures for this source", category: .session)
+        }
         // 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(
@@ -2244,7 +2255,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             originIsSerial: sourceReopenableByURL
                 && OriginRequestBudget.shared.requiresSerialRequests(sourceURL),
             isDiscSource: dem.isDiscSource,
-            secondReaderAvailable: sourceReopenableByURL || customIFrameReader != nil))
+            secondReaderAvailable: sourceReopenableByURL || customIFrameReader != nil,
+            stillsUnavailable: !stillsAvailable))
         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
diff --git a/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift b/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
index 58b2feec4..1e702adda 100644
--- a/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
+++ b/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
@@ -8,6 +8,9 @@ enum IFrameRenditionEligibility {
     enum AbsentReason: String, Equatable {
         case notRequested, live, planNotKeyframeAligned, sequentialOrigin, heldSourceConnection
         case serialOrigin, discSource, noSecondReader, mediaPlaylistRouting
+        /// A Dolby Vision Profile 5 / 10.0 source in a build without the `DolbyVisionStillReshaping`
+        /// trait: no entry could be answered with a correct picture.
+        case dolbyVisionStillsNotBuiltIn
     }
 
     enum Verdict: Equatable {
@@ -24,6 +27,8 @@ enum IFrameRenditionEligibility {
         var originIsSerial: Bool
         var isDiscSource: Bool
         var secondReaderAvailable: Bool
+        /// The source's frames cannot become a still in this build (`FrameDecodeContext.yieldsStill`).
+        var stillsUnavailable = false
     }
 
     /// Everything except the master decision, which needs this verdict as one of its inputs.
@@ -36,6 +41,7 @@ enum IFrameRenditionEligibility {
         if i.originIsSerial { return .absent(.serialOrigin) }
         if i.isDiscSource { return .absent(.discSource) }
         guard i.secondReaderAvailable else { return .absent(.noSecondReader) }
+        if i.stillsUnavailable { return .absent(.dolbyVisionStillsNotBuiltIn) }
         return .served
     }
 
diff --git a/Tests/AetherEngineTests/DolbyVisionColorTests.swift b/Tests/AetherEngineTests/DolbyVisionColorTests.swift
index 70aeba3e5..f701e1e7b 100644
--- a/Tests/AetherEngineTests/DolbyVisionColorTests.swift
+++ b/Tests/AetherEngineTests/DolbyVisionColorTests.swift
@@ -1,3 +1,5 @@
+// Only with the DolbyVisionStillReshaping trait: the still converter is not built without it.
+#if DolbyVisionStillReshaping
 import Testing
 import AetherLibavutil
 @testable import AetherEngine
@@ -171,3 +173,4 @@ struct DolbyVisionColorTests {
         #expect(abs(ord2.map(0, (0.3, 0.2, 0.1)) - 0.39) < 1e-12)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
index 2966d226f..c7ac64eda 100644
--- a/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
+++ b/Tests/AetherEngineTests/DoviGpuCurveSweepTests.swift
@@ -120,6 +120,8 @@ struct DoviGpuCurveSweepTests {
 
     // MARK: - Luma: multi-piece polynomial
 
+    // The reference curve is the still converter's, compiled only with DolbyVisionStillReshaping.
+    #if DolbyVisionStillReshaping
     @Test("GPU luma sweep: a 3-piece polynomial with per-piece order and denominator matches the reference curve")
     func lumaMultiPiecePolynomialSweep() throws {
         guard let composer = DoviFelComposer() else {
@@ -352,6 +354,7 @@ struct DoviGpuCurveSweepTests {
     }
 
     // MARK: - Identity is bit-exact
+    #endif
 
     @Test("GPU identity curve is bit-exact: every base-layer code survives the round trip")
     func identityCurveIsBitExact() throws {
diff --git a/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift b/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift
index 5b724d2c9..980f27f3c 100644
--- a/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift
+++ b/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift
@@ -90,6 +90,11 @@ struct FrameDecodeContextHardwareTests {
 
         #expect(context.isDolbyVisionNoBaseLayer)
         #expect(context.hardwareDecoderName == "none")
+        #if !DolbyVisionStillReshaping
+        // Without the reshaping the IPT planes would be read as YCbCr: no still at all instead.
+        #expect(context.decodeFrame(at: 1, mode: .thumbnail, targetWidth: 320, maxSize: nil,
+                                    isCancelled: { false }) == nil)
+        #endif
     }
 
     /// One 64x64 MPEG-4 Part 2 frame. VideoToolbox does not offer that legacy codec, while
diff --git a/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift b/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift
index 61c1457b4..c8348da7c 100644
--- a/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift
+++ b/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift
@@ -20,7 +20,8 @@ struct IFrameRenditionEligibilityTests {
 
     @Test("each failed requirement names its own reason",
           arguments: ["notRequested", "live", "planNotKeyframeAligned", "sequentialOrigin",
-                      "heldSourceConnection", "serialOrigin", "discSource", "noSecondReader"])
+                      "heldSourceConnection", "serialOrigin", "discSource", "noSecondReader",
+                      "dolbyVisionStillsNotBuiltIn"])
     func eachReason(reason: String) throws {
         let expected = try #require(IFrameRenditionEligibility.AbsentReason(rawValue: reason))
         let verdict = IFrameRenditionEligibility.candidate(inputs { i in
@@ -33,6 +34,7 @@ struct IFrameRenditionEligibilityTests {
             case .serialOrigin: i.originIsSerial = true
             case .discSource: i.isDiscSource = true
             case .noSecondReader: i.secondReaderAvailable = false
+            case .dolbyVisionStillsNotBuiltIn: i.stillsUnavailable = true
             case .mediaPlaylistRouting: break
             }
         })
diff --git a/Tests/AetherEngineTests/IFrameSessionTests.swift b/Tests/AetherEngineTests/IFrameSessionTests.swift
index 137fea431..b07e9b4fb 100644
--- a/Tests/AetherEngineTests/IFrameSessionTests.swift
+++ b/Tests/AetherEngineTests/IFrameSessionTests.swift
@@ -84,6 +84,8 @@ struct IFrameSessionTests {
 
     private static let dolbyVisionFixture = "user/Patterns_Of_Nature_DoVi_24_P5_UHD_HEVC-10mbps_DD+JOC-768kbps_iOS.mp4"
 
+    // Profile 5 stills need the DolbyVisionStillReshaping trait (README, "Optional components").
+    #if DolbyVisionStillReshaping
     @Test("a Dolby Vision session serves SDR JPEG stills on the plan's timeline",
           .enabled(if: fixtureExists(dolbyVisionFixture)), .timeLimit(.minutes(2)))
     func dolbyVisionServesJPEG() throws {
@@ -131,6 +133,20 @@ struct IFrameSessionTests {
         let playlist = try String(contentsOf: playlistURL, encoding: .utf8)
         #expect(playlist.contains("iframe1.mp4"))
     }
+    #else
+    @Test("without the reshaping trait a Profile 5 session lists no I-frame rendition",
+          .enabled(if: fixtureExists(dolbyVisionFixture)), .timeLimit(.minutes(2)))
+    func dolbyVisionWithoutReshapingHasNoRendition() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.dolbyVisionFixture), dvModeAvailable: true)
+        engine.requestIFramePlaylist()
+        _ = try engine.start()
+        defer { engine.stop() }
+        #expect(engine.iFrameRenditionVerdict == .absent(.dolbyVisionStillsNotBuiltIn))
+        #expect(!engine.yieldsStills)
+        let prov = try #require(engine.provider)
+        #expect(!prov.iFrameRenditionServed)
+    }
+    #endif
 
     @Test("the loopback server answers the three new paths",
           .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
diff --git a/Tests/AetherEngineTests/ItemSwapStillTests.swift b/Tests/AetherEngineTests/ItemSwapStillTests.swift
index 2147daafc..4e5d1164d 100644
--- a/Tests/AetherEngineTests/ItemSwapStillTests.swift
+++ b/Tests/AetherEngineTests/ItemSwapStillTests.swift
@@ -360,6 +360,7 @@ struct ItemSwapStillTests {
     nonisolated static let profile81URL = userFixtures
         .appendingPathComponent("Patterns_Of_Nature_HDR10-P8.1_UHD_24_H265-10Mbps_DD+JOC-768Kbps.mp4")
 
+    #if DolbyVisionStillReshaping
     /// Dolby's own Profile 5 signal, which cannot be committed: the base layer is IPTPQc2 and only
     /// the RPU makes it a picture, so the hold must come from the reshaping path.
     @Test("a Profile 5 title holds a reshaped still",
@@ -381,6 +382,35 @@ struct ItemSwapStillTests {
         #expect(engine.heldPictureLastRoute == "Dolby Vision reshaped")
         #expect(view.isHoldingStill)
     }
+    #else
+    /// Without the reshaping a Profile 5 picture cannot be made from the segment, so where the hold
+    /// would need it (the output presents Dolby Vision) it is skipped with its reason rather than
+    /// showing the planes read as YCbCr. Where AVPlayer presents the source as HDR10 (a Mac without a
+    /// Dolby Vision display), the output's own picture is correct and is held as before.
+    @Test("without the reshaping trait a Profile 5 title never holds a reshaped still",
+          .enabled(if: FileManager.default.fileExists(atPath: ItemSwapStillTests.profile5URL.path)))
+    func profile5WithoutReshapingHoldsNothingReshaped() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let view = AetherPlayerView(frame: CGRect(x: 0, y: 0, width: 320, height: 180))
+        engine.bind(view: view)
+        _ = try await engine.load(url: Self.profile5URL)
+        let host = try #require(engine.nativeHost)
+        try await waitFor { host.isVideoReadyForDisplay }
+        engine.pause()
+        // No scrub still either, and the capability says so up front so a host hides the preview.
+        #expect(!engine.supportsCacheBackedStills)
+        #expect(await engine.scrubThumbnail(atSeconds: 0.5, maxWidth: 160) == nil)
+        await engine.holdPictureAcrossItemSwap()
+        if AetherEngine.heldPictureNeedsReshaping(videoFormat: engine.videoFormat, dolbyVisionProfile: engine.sourceDVProfile) {
+            #expect(engine.heldPictureLastSkip == "Dolby Vision still reshaping not built in")
+            #expect(!view.isHoldingStill)
+        } else {
+            #expect(engine.heldPictureLastRoute == "native output")
+        }
+        #expect(engine.heldPictureLastRoute != "Dolby Vision reshaped")
+    }
+    #endif
 
     @Test("a Profile 8.1 title holds its HDR10 base layer from the output",
           .enabled(if: FileManager.default.fileExists(atPath: ItemSwapStillTests.profile81URL.path)))
diff --git a/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift b/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift
index b3b5359f9..a4647d287 100644
--- a/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift
+++ b/Tests/AetherEngineTests/OptionalComponentFallbackTests.swift
@@ -1,15 +1,46 @@
+import Foundation
+import CoreGraphics
 import Testing
 import AetherLibavcodec
 import AetherLibavutil
 @testable import AetherEngine
 
-/// The object renderer and the dual-layer composer are compiled only with their package traits, all off
-/// by default. A build without one still accepts the option that asks for it, and the option changes
-/// nothing: object audio keeps the channel bridge, a Profile 7 source keeps the native route. The track
-/// pick is pinned the same way in `AudioLanguageSelectionTests.withoutTraitNothingIsPreferred`.
+/// The object renderer, the dual-layer composer and the Dolby Vision still reshaping are compiled only
+/// with their package traits, all off by default. A build without one still accepts the option that asks
+/// for it, and the option changes nothing: object audio keeps the channel bridge, a Profile 7 source keeps
+/// the native route, a Profile 5 source yields no still. The track pick is pinned the same way in
+/// `AudioLanguageSelectionTests.withoutTraitNothingIsPreferred`.
 @Suite("Optional components fall back when their trait is off")
 struct OptionalComponentFallbackTests {
 
+    @Test("the runtime query reports each component as this build was compiled")
+    func runtimeQueryMatchesTheBuild() {
+        #expect(AetherEngine.OptionalComponent.allCases.map(\.traitName)
+                == ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision", "DolbyVisionStillReshaping"])
+        #if TrueHDObjectAudio
+        #expect(AetherEngine.OptionalComponent.trueHDObjectAudio.isBuiltIn)
+        #else
+        #expect(!AetherEngine.OptionalComponent.trueHDObjectAudio.isBuiltIn)
+        #endif
+        #if DTSXObjectAudio
+        #expect(AetherEngine.OptionalComponent.dtsxObjectAudio.isBuiltIn)
+        #else
+        #expect(!AetherEngine.OptionalComponent.dtsxObjectAudio.isBuiltIn)
+        #endif
+        #if DualLayerDolbyVision
+        #expect(AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn)
+        #else
+        #expect(!AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn)
+        #endif
+        #if DolbyVisionStillReshaping
+        #expect(AetherEngine.OptionalComponent.dolbyVisionStillReshaping.isBuiltIn)
+        #else
+        #expect(!AetherEngine.OptionalComponent.dolbyVisionStillReshaping.isBuiltIn)
+        #endif
+        #expect(AetherEngine.linksTrueHDObjectDecoder == AetherEngine.OptionalComponent.trueHDObjectAudio.isBuiltIn)
+        #expect(DualLayerRouteDecision.isBuiltIn == AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn)
+    }
+
     #if !DualLayerDolbyVision
     private static let uhd24 = DualLayerRouteDecision.Geometry(width: 3840, height: 2160, frameRate: 24)
 
@@ -38,6 +69,56 @@ struct OptionalComponentFallbackTests {
                 dvProfile: 7, preferDualLayerDolbyVision: prefer, canHardwareDecode: { true }, elType: "FEL"))
         }
     }
+
+    @Test("flipping preferDualLayerDolbyVision on a custom Profile 7 session is not refused: it moves nothing")
+    func dualLayerCorrectionIsNotRefused() {
+        var off = LoadOptions()
+        off.preferDualLayerDolbyVision = false
+        var on = off
+        on.preferDualLayerDolbyVision = true
+        var baseOnly = on
+        baseOnly.dolbyVisionHandling = .baseLayerOnly
+        for (from, to) in [(off, on), (on, off), (on, baseOnly)] {
+            #expect(SessionOptionCorrection.dualLayerRouteRefusal(
+                isCustomSource: true, current: from, proposed: to, dvProfile: 7) == nil)
+        }
+    }
+    #endif
+
+    #if !DolbyVisionStillReshaping
+    /// The 64x64 HDR10 fixture with a Profile 5 record: its frames are what a Profile 5 decode hands
+    /// the still path. Read as YCbCr, real Profile 5 planes are the green / magenta still of #103, so
+    /// without the reshaping the answer is no still at all, while the same frames without the record
+    /// still make one.
+    @MainActor
+    @Test("a Dolby Vision Profile 5 frame yields no still; the same frames without the record do")
+    func profile5YieldsNoStill() throws {
+        func still(_ data: Data) throws -> (image: CGImage?, isDolbyVision: Bool) {
+            let context = FrameDecodeContext(reader: DataIOReader(data: data), formatHint: "mp4")
+            defer { context.close() }
+            try context.ensureOpen()
+            let image = context.decodeFrame(at: 0, mode: .thumbnail, targetWidth: 64, maxSize: nil,
+                                            isCancelled: { false })
+            return (image, context.isDolbyVisionNoBaseLayer)
+        }
+        let profile5 = try still(SupersededProbeGeometryTests.dolbyVisionProfile5OverHDR10())
+        #expect(profile5.isDolbyVision)
+        #expect(profile5.image == nil)
+        let hdr10 = try still(ProbeTestFixtures.hdr10Plus())
+        #expect(!hdr10.isDolbyVision)
+        #expect(hdr10.image != nil)
+        #expect(!FrameDecodeContext.yieldsStill(dolbyVisionNoBaseLayer: true))
+        #expect(FrameDecodeContext.yieldsStill(dolbyVisionNoBaseLayer: false))
+    }
+
+    @Test("an I-frame rendition is not served for a source whose stills cannot be made")
+    func iFrameRenditionIsAbsent() {
+        let verdict = IFrameRenditionEligibility.candidate(.init(
+            requested: true, isLive: false, planBoundariesClaimRandomAccess: true, sequentialOrigin: false,
+            heldSourceConnection: false, originIsSerial: false, isDiscSource: false, secondReaderAvailable: true,
+            stillsUnavailable: !FrameDecodeContext.yieldsStill(dolbyVisionNoBaseLayer: true)))
+        #expect(verdict == .absent(.dolbyVisionStillsNotBuiltIn))
+    }
     #endif
 
     #if !TrueHDObjectAudio

From c290e03778af89540455ca22fd55223335e5c7da Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 11:09:24 +0200
Subject: [PATCH 110/132] refactor(video): compile the dual-layer delivery and
 display metadata only with DualLayerDolbyVision

OrderedDelivery, DoviDisplayMetadata and DoviDisplayMetadataDebug are
reached only from the dual-layer decoder, so they move behind the
DualLayerDolbyVision trait, as does the DEBUG pin test SPI
(armDolbyVisionPinTest, dolbyVisionPinIsArmed, dolbyVisionPinIsActive).
`aetherctl play --dv-pin` exits 64 without the trait, like --cycle-el.
The tests that drive them are gated the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift      | 2 +-
 Sources/AetherEngine/Decoder/OrderedDelivery.swift           | 3 +++
 .../AetherEngine/Video/AetherEngine+DolbyVisionTest.swift    | 3 ++-
 Sources/AetherEngine/Video/DoviDisplayMetadata.swift         | 3 +++
 Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift    | 3 +++
 Sources/aetherctl/main.swift                                 | 5 ++++-
 Tests/AetherEngineTests/DoviDisplayMetadataTests.swift       | 3 +++
 Tests/AetherEngineTests/DoviPinTestTests.swift               | 2 +-
 Tests/AetherEngineTests/OrderedDeliveryTests.swift           | 3 +++
 Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift   | 2 ++
 10 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 115a30b28..086526c16 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -798,4 +798,4 @@ protocol VideoSessionRebuilding: AnyObject {
     @discardableResult func rebuildSession() -> Bool
 }
 
-extension HardwareVideoDecoder: VideoSessionRebuilding {}
\ No newline at end of file
+extension HardwareVideoDecoder: VideoSessionRebuilding {}
diff --git a/Sources/AetherEngine/Decoder/OrderedDelivery.swift b/Sources/AetherEngine/Decoder/OrderedDelivery.swift
index 3e0009a86..d50fa9996 100644
--- a/Sources/AetherEngine/Decoder/OrderedDelivery.swift
+++ b/Sources/AetherEngine/Decoder/OrderedDelivery.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 import CoreMedia
 import CoreVideo
@@ -330,3 +332,4 @@ final class OrderedDelivery: @unchecked Sendable {
     var hasOnFrameForTesting: Bool { queue.sync { onFrame != nil } }
     var currentOnFrame: DecodedFrameHandler? { queue.sync { onFrame } }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift b/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
index 20ab6064a..9faa7e280 100644
--- a/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
+++ b/Sources/AetherEngine/Video/AetherEngine+DolbyVisionTest.swift
@@ -1,4 +1,5 @@
-#if DEBUG
+// Only in DEBUG builds with the DualLayerDolbyVision trait: it pins metadata on composed frames.
+#if DEBUG && DualLayerDolbyVision
 import Foundation
 
 /// Diagnostic controls (SPI, not host API) for the on-device Dolby Vision consumption test.
diff --git a/Sources/AetherEngine/Video/DoviDisplayMetadata.swift b/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
index 546bab9da..dcc0cf9db 100644
--- a/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
+++ b/Sources/AetherEngine/Video/DoviDisplayMetadata.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 import Foundation
 import CoreVideo
 
@@ -125,3 +127,4 @@ enum DoviDisplayMetadata {
         return nil
     }
 }
+#endif
diff --git a/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift b/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
index d37aeae71..f60b7ec5c 100644
--- a/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
+++ b/Sources/AetherEngine/Video/DoviDisplayMetadataDebug.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait (off by default).
+#if DualLayerDolbyVision
 #if DEBUG
 import Foundation
 import Dovi
@@ -311,3 +313,4 @@ enum DoviDisplayMetadataDebug {
     static func parse(spec: String) -> DoviPinTest.Config? { DoviPinTest.parse(spec: spec) }
 }
 #endif
+#endif
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 6e64e515b..1693bce4b 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -751,7 +751,10 @@ if first == "play" {
     }
     // `--dv-pin <spec>`: arm the Dolby Vision pin test (DEBUG builds), same grammar `dvsurvey` prints.
     if let spec = takeStringFlag("--dv-pin", from: &rest) {
-        #if DEBUG
+        #if !DualLayerDolbyVision
+        print("ERROR: --dv-pin needs the DualLayerDolbyVision trait (swift build --traits DualLayerDolbyVision)")
+        exit(64)
+        #elseif DEBUG
         guard AetherEngine.armDolbyVisionPinTest(spec) else {
             print("ERROR: --dv-pin '\(spec)' carries no capture rule (e.g. 'darkest:240,period:2')")
             exit(64)
diff --git a/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift b/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift
index 30b447c4d..97be4241d 100644
--- a/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift
+++ b/Tests/AetherEngineTests/DoviDisplayMetadataTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the dual-layer route is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import Foundation
 import CoreVideo
@@ -97,3 +99,4 @@ struct DoviDisplayMetadataTests {
         #expect(Self.surfaceValue(b, DoviDisplayMetadata.rpuDataKey) == nil)
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/DoviPinTestTests.swift b/Tests/AetherEngineTests/DoviPinTestTests.swift
index 4ef30943d..7d76bc205 100644
--- a/Tests/AetherEngineTests/DoviPinTestTests.swift
+++ b/Tests/AetherEngineTests/DoviPinTestTests.swift
@@ -1,4 +1,4 @@
-#if DEBUG
+#if DEBUG && DualLayerDolbyVision
 import Testing
 import Foundation
 @testable import AetherEngine
diff --git a/Tests/AetherEngineTests/OrderedDeliveryTests.swift b/Tests/AetherEngineTests/OrderedDeliveryTests.swift
index 03958ebc5..3d24a4193 100644
--- a/Tests/AetherEngineTests/OrderedDeliveryTests.swift
+++ b/Tests/AetherEngineTests/OrderedDeliveryTests.swift
@@ -1,3 +1,5 @@
+// Only with the DualLayerDolbyVision trait: the dual-layer route is not built without it.
+#if DualLayerDolbyVision
 import Testing
 import CoreMedia
 import CoreVideo
@@ -245,3 +247,4 @@ struct OrderedDeliveryTests {
         #expect(recorder.snapshot == [0])
     }
 }
+#endif
diff --git a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
index f2f3ae95f..5e0ce6868 100644
--- a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
+++ b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
@@ -203,6 +203,7 @@ struct SubtitleFrameCompositorTests {
         }
     }
 
+    #if DualLayerDolbyVision
     /// The Profile 7 FEL route hands the renderer composed P010 frames carrying the Dolby Vision RPU
     /// and compatibility ID. In PiP with a cue up, the frame the layer receives is the compositor's
     /// copy: it has to carry the source frame's attachments (the CFString "1" among them, which the
@@ -235,6 +236,7 @@ struct SubtitleFrameCompositorTests {
             #expect(attachment(out, DoviDisplayMetadata.compatibilityIDKey as CFString) == nil)
         }
     }
+    #endif
 
     @Test("an untagged source renders through BT.709")
     func untaggedSourceFallsBackTo709() throws {

From 6b97fe920c6cb4d99f3e4092c46642ecdd8d1d05 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 11:09:24 +0200
Subject: [PATCH 111/132] ci: build the opt-in components for the device SDKs
 and the strict pool

xcodebuild has no flag for a package's traits, so Probes/AllTraits is a
consumer package that enables all four, the way a host does, and CI
builds it for tvOS and iOS. The macOS job also runs the all-traits suite
on a one-thread cooperative pool, and the iOS job builds a release
aetherctl with every trait.

The Dolby Vision pulse host links the engine through PulseEngine/, a
local package that sets DualLayerDolbyVision (XcodeGen cannot set traits),
and refuses its engine and soak arms with a slate, an ERROR line and exit
70 when the trait is not built in, instead of filming the native route.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/ci.yml                      | 36 +++++++++++++++++--
 Probes/AllTraits/Package.swift                | 32 +++++++++++++++++
 .../AetherEngineAllTraits/AllTraits.swift     |  4 +++
 .../project.pbxproj                           | 20 +++++------
 .../Device/Host/DolbyVisionPulseHostApp.swift | 10 ++++++
 .../Device/PulseEngine/Package.swift          | 20 +++++++++++
 .../Sources/PulseEngine/PulseEngine.swift     |  1 +
 Probes/DolbyVisionPulse/Device/project.yml    | 16 ++++-----
 Probes/DolbyVisionPulse/README.md             |  8 +++++
 9 files changed, 125 insertions(+), 22 deletions(-)
 create mode 100644 Probes/AllTraits/Package.swift
 create mode 100644 Probes/AllTraits/Sources/AetherEngineAllTraits/AllTraits.swift
 create mode 100644 Probes/DolbyVisionPulse/Device/PulseEngine/Package.swift
 create mode 100644 Probes/DolbyVisionPulse/Device/PulseEngine/Sources/PulseEngine/PulseEngine.swift

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 49519b345..d3587caea 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -65,6 +65,11 @@ jobs:
       - name: swift test (all traits)
         run: swift test --enable-all-traits --skip-build --scratch-path .build-alltraits
 
+      - name: swift test (all traits, one-thread cooperative pool)
+        env:
+          LIBDISPATCH_COOPERATIVE_POOL_STRICT: "1"
+        run: swift test --enable-all-traits --skip-build --disable-xctest --scratch-path .build-alltraits
+
       - name: Software VOD packet-cache regressions
         run: |
           bash Scripts/test-software-packet-coverage.sh
@@ -96,7 +101,7 @@ jobs:
   build-tvos:
     name: xcodebuild (tvOS + visionOS Simulator)
     runs-on: xcode-27
-    timeout-minutes: 30
+    timeout-minutes: 45
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
@@ -137,7 +142,8 @@ jobs:
       # The Dolby Vision pulse host is the other device harness, and the one that links the engine
       # itself, so it is also the one that breaks when a public API it uses moves. It plays clips on an
       # Apple TV that someone films, runs nowhere in CI, and would otherwise be found out by the person
-      # who needed a measurement that evening. EXCLUDED_ARCHS for the reason given above: an app cannot
+      # who needed a measurement that evening. It links the engine through PulseEngine/, which enables the
+      # DualLayerDolbyVision trait the host measures. EXCLUDED_ARCHS for the reason given above: an app cannot
       # link the x86_64 slice.
       - name: Build the Dolby Vision pulse host (Probes/DolbyVisionPulse)
         run: |
@@ -149,6 +155,17 @@ jobs:
             EXCLUDED_ARCHS=x86_64 \
             CODE_SIGNING_ALLOWED=NO
 
+      # xcodebuild has no flag for a package's traits, so the opt-in components reach the device SDKs
+      # through Probes/AllTraits, a consumer package that enables all of them the way a host does.
+      - name: Build with every optional component for tvOS
+        working-directory: Probes/AllTraits
+        run: |
+          xcodebuild build \
+            -scheme AetherEngineAllTraits \
+            -destination 'generic/platform=tvOS' \
+            -derivedDataPath ../../.build/xcode-alltraits-tvos \
+            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
@@ -166,7 +183,7 @@ jobs:
   build-ios:
     name: xcodebuild (iOS Simulator) + release aetherctl
     runs-on: xcode-27
-    timeout-minutes: 30
+    timeout-minutes: 45
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
@@ -187,6 +204,19 @@ jobs:
       - name: swift build -c release (aetherctl)
         run: swift build -c release --product aetherctl
 
+      - name: swift build -c release (aetherctl, all traits)
+        run: swift build -c release --enable-all-traits --product aetherctl --scratch-path .build-release-alltraits
+
+      # See the tvOS job: the opt-in components for the iOS device SDK, through a consumer package.
+      - name: Build with every optional component for iOS
+        working-directory: Probes/AllTraits
+        run: |
+          xcodebuild build \
+            -scheme AetherEngineAllTraits \
+            -destination 'generic/platform=iOS' \
+            -derivedDataPath ../../.build/xcode-alltraits-ios \
+            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/Probes/AllTraits/Package.swift b/Probes/AllTraits/Package.swift
new file mode 100644
index 000000000..67e16f50e
--- /dev/null
+++ b/Probes/AllTraits/Package.swift
@@ -0,0 +1,32 @@
+// swift-tools-version: 6.1
+
+import PackageDescription
+
+// A consumer of the engine with every optional component enabled, the way a host enables them. `swift
+// build` on the engine compiles its own traits, but xcodebuild has no flag for a package's traits, so CI
+// builds this package for tvOS and iOS to keep the opt-in code compiling for the device SDKs.
+let package = Package(
+    name: "AetherEngineAllTraits",
+    platforms: [
+        .iOS(.v18),
+        .tvOS(.v18),
+        .macOS(.v15),
+        .visionOS(.v1),
+    ],
+    products: [
+        .library(name: "AetherEngineAllTraits", targets: ["AetherEngineAllTraits"]),
+    ],
+    dependencies: [
+        .package(
+            name: "AetherEngine",
+            path: "../..",
+            traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision", "DolbyVisionStillReshaping"]
+        ),
+    ],
+    targets: [
+        .target(
+            name: "AetherEngineAllTraits",
+            dependencies: [.product(name: "AetherEngine", package: "AetherEngine")]
+        ),
+    ]
+)
diff --git a/Probes/AllTraits/Sources/AetherEngineAllTraits/AllTraits.swift b/Probes/AllTraits/Sources/AetherEngineAllTraits/AllTraits.swift
new file mode 100644
index 000000000..d2b8582e1
--- /dev/null
+++ b/Probes/AllTraits/Sources/AetherEngineAllTraits/AllTraits.swift
@@ -0,0 +1,4 @@
+@_exported import AetherEngine
+
+/// Every optional component this consumer enabled, as the engine reports them at run time.
+public let enabledOptionalComponents = AetherEngine.OptionalComponent.allCases.filter(\.isBuiltIn)
diff --git a/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj
index a24a0aded..3586b5e14 100644
--- a/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj
+++ b/Probes/DolbyVisionPulse/Device/DolbyVisionPulse.xcodeproj/project.pbxproj
@@ -9,12 +9,12 @@
 /* Begin PBXBuildFile section */
 		1CC1EA98D9C5F77AAC72F7CC /* PulseVideoToolbox.swift in Sources */ = {isa = PBXBuildFile; fileRef = B9672B7938DDC09AAB435BC6 /* PulseVideoToolbox.swift */; };
 		77CB08AE958747D4126970C6 /* DolbyVisionPulseHostApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 7BCA97A8853B09B4E7B4B99A /* DolbyVisionPulseHostApp.swift */; };
-		C3F88D052478C6D03F65C74C /* AetherEngine in Frameworks */ = {isa = PBXBuildFile; productRef = 5DDCF6DD2D95C3E73D4B2B5C /* AetherEngine */; };
+		C3F88D052478C6D03F65C74C /* PulseEngine in Frameworks */ = {isa = PBXBuildFile; productRef = 5DDCF6DD2D95C3E73D4B2B5C /* PulseEngine */; };
 		FB3139445F0E0031753BB397 /* PulseLog.swift in Sources */ = {isa = PBXBuildFile; fileRef = DCACA2DF252349E564F73EAC /* PulseLog.swift */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
-		6EC0C4402B0A4CFAB2376CAB /* AetherEngine */ = {isa = PBXFileReference; lastKnownFileType = folder; name = AetherEngine; path = ../../..; sourceTree = SOURCE_ROOT; };
+		6EC0C4402B0A4CFAB2376CAB /* PulseEngine */ = {isa = PBXFileReference; lastKnownFileType = folder; path = PulseEngine; sourceTree = SOURCE_ROOT; };
 		7BCA97A8853B09B4E7B4B99A /* DolbyVisionPulseHostApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DolbyVisionPulseHostApp.swift; sourceTree = "<group>"; };
 		81B68F565101F4AD4C23902A /* DolbyVisionPulseHost.app */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.application; path = DolbyVisionPulseHost.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		B9672B7938DDC09AAB435BC6 /* PulseVideoToolbox.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PulseVideoToolbox.swift; sourceTree = "<group>"; };
@@ -26,7 +26,7 @@
 			isa = PBXFrameworksBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
-				C3F88D052478C6D03F65C74C /* AetherEngine in Frameworks */,
+				C3F88D052478C6D03F65C74C /* PulseEngine in Frameworks */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -36,7 +36,7 @@
 		877A8AC0E76ED624DD6E3BF6 /* Packages */ = {
 			isa = PBXGroup;
 			children = (
-				6EC0C4402B0A4CFAB2376CAB /* AetherEngine */,
+				6EC0C4402B0A4CFAB2376CAB /* PulseEngine */,
 			);
 			name = Packages;
 			sourceTree = "<group>";
@@ -84,7 +84,7 @@
 			);
 			name = DolbyVisionPulseHost;
 			packageProductDependencies = (
-				5DDCF6DD2D95C3E73D4B2B5C /* AetherEngine */,
+				5DDCF6DD2D95C3E73D4B2B5C /* PulseEngine */,
 			);
 			productName = DolbyVisionPulseHost;
 			productReference = 81B68F565101F4AD4C23902A /* DolbyVisionPulseHost.app */;
@@ -114,7 +114,7 @@
 			mainGroup = 91F1FECFC9FBC63638DFB9F0;
 			minimizedProjectReferenceProxies = 1;
 			packageReferences = (
-				A1D5E5D261EA7A828134329D /* XCLocalSwiftPackageReference "../../.." */,
+				A1D5E5D261EA7A828134329D /* XCLocalSwiftPackageReference "PulseEngine" */,
 			);
 			preferredProjectObjectVersion = 77;
 			productRefGroup = A0369D737D33D357FE77916A /* Products */;
@@ -325,16 +325,16 @@
 /* End XCConfigurationList section */
 
 /* Begin XCLocalSwiftPackageReference section */
-		A1D5E5D261EA7A828134329D /* XCLocalSwiftPackageReference "../../.." */ = {
+		A1D5E5D261EA7A828134329D /* XCLocalSwiftPackageReference "PulseEngine" */ = {
 			isa = XCLocalSwiftPackageReference;
-			relativePath = ../../..;
+			relativePath = PulseEngine;
 		};
 /* End XCLocalSwiftPackageReference section */
 
 /* Begin XCSwiftPackageProductDependency section */
-		5DDCF6DD2D95C3E73D4B2B5C /* AetherEngine */ = {
+		5DDCF6DD2D95C3E73D4B2B5C /* PulseEngine */ = {
 			isa = XCSwiftPackageProductDependency;
-			productName = AetherEngine;
+			productName = PulseEngine;
 		};
 /* End XCSwiftPackageProductDependency section */
 	};
diff --git a/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift b/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
index a53374bf2..0de3ebef6 100644
--- a/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
+++ b/Probes/DolbyVisionPulse/Device/Host/DolbyVisionPulseHostApp.swift
@@ -157,6 +157,16 @@ struct PulseHarnessView: View {
             PulseLog.shared.note(line)
         }
         say("sequence: " + arms.map { "\($0.label)(\($0.mode))" }.joined(separator: " "))
+        // Without the trait the engine accepts preferDualLayerDolbyVision and plays the native route, so
+        // every `engine` and `soak` arm would film the wrong thing. Refuse the whole sequence instead.
+        if arms.contains(where: { $0.mode == "engine" || $0.mode == "soak" }),
+           !AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn {
+            slate = "AetherEngine was built without the DualLayerDolbyVision trait"
+            say("ERROR: the engine and soak arms need AetherEngine's DualLayerDolbyVision trait, which this "
+                + "build lacks (PulseEngine/Package.swift sets it); refusing the sequence")
+            try? await Task.sleep(nanoseconds: 10_000_000_000)
+            exit(70)
+        }
         for (n, arm) in arms.enumerated() {
             slate = "\(n + 1)/\(arms.count)  \(arm.label)"
             host.window?.avDisplayManager.preferredDisplayCriteria = nil
diff --git a/Probes/DolbyVisionPulse/Device/PulseEngine/Package.swift b/Probes/DolbyVisionPulse/Device/PulseEngine/Package.swift
new file mode 100644
index 000000000..332e58249
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/PulseEngine/Package.swift
@@ -0,0 +1,20 @@
+// swift-tools-version: 6.1
+
+import PackageDescription
+
+// The engine as the pulse host needs it: with the DualLayerDolbyVision trait, without which every
+// `engine` and `soak` arm would measure the native route. XcodeGen cannot set a package's traits, so
+// the host depends on this package and this package sets them.
+let package = Package(
+    name: "PulseEngine",
+    platforms: [.tvOS(.v18)],
+    products: [
+        .library(name: "PulseEngine", targets: ["PulseEngine"]),
+    ],
+    dependencies: [
+        .package(name: "AetherEngine", path: "../../../..", traits: ["DualLayerDolbyVision"]),
+    ],
+    targets: [
+        .target(name: "PulseEngine", dependencies: [.product(name: "AetherEngine", package: "AetherEngine")]),
+    ]
+)
diff --git a/Probes/DolbyVisionPulse/Device/PulseEngine/Sources/PulseEngine/PulseEngine.swift b/Probes/DolbyVisionPulse/Device/PulseEngine/Sources/PulseEngine/PulseEngine.swift
new file mode 100644
index 000000000..9b8b0fc73
--- /dev/null
+++ b/Probes/DolbyVisionPulse/Device/PulseEngine/Sources/PulseEngine/PulseEngine.swift
@@ -0,0 +1 @@
+@_exported import AetherEngine
diff --git a/Probes/DolbyVisionPulse/Device/project.yml b/Probes/DolbyVisionPulse/Device/project.yml
index bd5197724..994dc80f4 100644
--- a/Probes/DolbyVisionPulse/Device/project.yml
+++ b/Probes/DolbyVisionPulse/Device/project.yml
@@ -1,14 +1,12 @@
 # Device harness for the Dolby Vision pulse test (Probes/DolbyVisionPulse/README.md): a tvOS app
 # that plays the clips from Scripts/build.sh, arm by arm, so a camera pointed at the television can
 # see whether the Dolby Vision metadata reaches the panel. It depends on the engine as a local Swift
-# package (the repository root, three levels up).
+# package (the repository root, three levels up), through `PulseEngine/`, a local package that enables
+# the engine's DualLayerDolbyVision trait: XcodeGen cannot set a package's traits, and without that
+# trait the `engine` and `soak` arms would measure the native route (the app refuses to run them).
 #
 # Regenerate with `xcodegen generate --spec project.yml` from this directory. The generated project
 # is committed so that running the probe needs Xcode and nothing else.
-#
-# XcodeGen names the local-package folder reference after the checkout directory it ran in, which
-# would commit a developer's folder name. After regenerating, change that name in project.pbxproj
-# (the `PBXFileReference` with `path = ../../..`, and its group entry) back to `AetherEngine`.
 name: DolbyVisionPulse
 options:
   bundleIdPrefix: de.superuser404.dolbyvisionpulse
@@ -27,8 +25,8 @@ settings:
     ENABLE_USER_SCRIPT_SANDBOXING: YES
 
 packages:
-  AetherEngine:
-    path: ../../..
+  PulseEngine:
+    path: PulseEngine
 
 targets:
   DolbyVisionPulseHost:
@@ -39,8 +37,8 @@ targets:
         excludes:
           - Info.plist
     dependencies:
-      - package: AetherEngine
-        product: AetherEngine
+      - package: PulseEngine
+        product: PulseEngine
     info:
       path: Host/Info.plist
       properties:
diff --git a/Probes/DolbyVisionPulse/README.md b/Probes/DolbyVisionPulse/README.md
index c49e3bb65..e8a70028b 100644
--- a/Probes/DolbyVisionPulse/README.md
+++ b/Probes/DolbyVisionPulse/README.md
@@ -35,6 +35,7 @@ Apple TV and a phone on a tripod.
 | `Scripts/dump_attachments.swift` | prints what VideoToolbox attaches to a decoded Dolby Vision frame, with a hash of the RPU |
 | `Scripts/sim_recording.py` | a fake phone recording, to prove the analysis before trusting a real one |
 | `Device/` | the tvOS host app (xcodegen project, committed generated project) |
+| `Device/PulseEngine/` | the local package the host links the engine through; it enables the engine's `DualLayerDolbyVision` trait |
 
 ## Tools
 
@@ -128,6 +129,13 @@ for the wrong reason.
 
 ## Run on an Apple TV
 
+The dual-layer route is an optional component of the engine, compiled only with its
+`DualLayerDolbyVision` package trait. The host gets it through `Device/PulseEngine/Package.swift`, which
+depends on the engine with that trait set, because XcodeGen cannot set a package's traits itself. Without
+the trait every `engine` and `soak` arm would play the native route, so the host checks
+`AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn` before the first arm, shows a slate
+saying the trait is missing, logs an `ERROR` line and exits with status 70.
+
 The host app takes its arms from the environment variable `PULSE_ARMS`:
 
 ```

From 1703abe0b7cbe89ee5404a958b99d65d553d1114 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 11:09:24 +0200
Subject: [PATCH 112/132] docs: optional components, the still reshaping trait
 and how to enable traits

README's Optional components section lists all four traits, names the
runtime query, corrects the XcodeGen claim (traits are set in Xcode's
package dependency editor; XcodeGen cannot express them, so a pbxproj
patch or a small wrapper package does) and pins the example to 7.39.0.
docs/ state the trait each feature needs, including Profile 5 / 10.0
stills, the dv-pin SPI and the stale "not routed yet" entries; the
CHANGELOG opens with what is no longer built by default and how to turn
it back on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md             | 55 ++++++++++++++++++++++++++++++----------
 README.md                | 13 +++++-----
 docs/api.md              | 29 +++++++++++++++++----
 docs/architecture.md     | 11 ++++----
 docs/cli.md              |  4 +--
 docs/dolby-vision-fel.md |  7 ++---
 docs/formats.md          |  2 +-
 7 files changed, 85 insertions(+), 36 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8239c69a..aaf6407b8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,22 +10,49 @@ the public-API contract.
 
 ## [Unreleased]
 
+**Not built by default any more: TrueHD Atmos and DTS:X object rendering, Profile 7 FEL dual-layer
+composition, and Dolby Vision Profile 5 / 10.0 stills.** Each is now an optional component behind a
+package trait that is off by default (`TrueHDObjectAudio`, `DTSXObjectAudio`, `DualLayerDolbyVision`,
+`DolbyVisionStillReshaping`). A host that used any of them re-enables it on its package dependency:
+
+```swift
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.39.0",
+         traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision", "DolbyVisionStillReshaping"])
+```
+
+or in Xcode's package dependency editor (XcodeGen cannot set traits; see
+[README › Optional components](README.md#optional-components)). These components may be subject to
+third-party patent licensing; integrators who enable them are responsible for their own licensing.
+
 ### Changed
 
-- **TrueHD Atmos and DTS:X object rendering, and Profile 7 FEL dual-layer composition, are optional
-  components, off by default.** Each is compiled only with its package trait: `TrueHDObjectAudio`
-  (LibTrueHD and the object renderer), `DTSXObjectAudio` (LibDTSX and the object renderer) and the new
-  `DualLayerDolbyVision` (`DualLayerVideoDecoder`, the Metal composer and the FEL diagnostics). The two
-  audio traits used to be on by default. Without a trait the component is not in the binary, and the
-  option that asks for it stays in the API and changes nothing: `objectAudioRendering` keeps the codec on
-  the channel bridge, `preferDualLayerDolbyVision` keeps a Profile 7 source on the native route (the
-  route line reads `not taken (built without the DualLayerDolbyVision trait)`). These components may be
-  subject to third-party patent licensing; integrators who enable them are responsible for their own
-  licensing. **A host that relied on TrueHD Atmos or DTS:X rendering enables the traits** on its package
-  dependency (`traits: ["TrueHDObjectAudio", "DTSXObjectAudio"]`, [README › Optional
-  components](README.md#optional-components)). The `@_spi(Diagnostics)` FEL tooling (`felDecodeProbe`,
-  `FelProbeResult`, `felResidualEnabled`) exists only with `DualLayerDolbyVision`, as do `aetherctl
-  feltest` and `play --cycle-el`. CI builds and tests the default and the all-traits configuration.
+- **Optional components, off by default.** Without its trait a component is not compiled, and a library
+  behind it is neither linked nor resolved. The public API is unchanged and the options become no-ops:
+  `objectAudioRendering` keeps the codec on the channel bridge, and `preferDualLayerDolbyVision` keeps a
+  Profile 7 source on the native route (the route line reads `not taken (built without the
+  DualLayerDolbyVision trait)`, and `reloadAtCurrentPosition(applying:)` no longer refuses flipping it on a
+  custom-reader session, since nothing would move). The two audio traits used to be on by default; the
+  dual-layer path (`DualLayerVideoDecoder`, the Metal composer, `OrderedDelivery`, the per-frame display
+  metadata and the FEL diagnostics) and the still reshaping (`DolbyVisionStillConverter`) were always
+  compiled.
+- **A Dolby Vision Profile 5 / 10.0 source has no stills without `DolbyVisionStillReshaping`.** Its planes
+  are IPT, which the standard still path would read as YCbCr (the green / magenta picture of #103), so it
+  yields none: `scrubThumbnail` and `scrubPreviewFrame` return nil without decoding anything,
+  `supportsCacheBackedStills` is false, the I-frame rendition is absent (`dolbyVisionStillsNotBuiltIn`),
+  an audio switch holds no picture, and the session log says so once. Playback is unaffected, as are
+  Profile 8.x, HDR10, HLG and SDR stills.
+
+### Added
+
+- **`AetherEngine.OptionalComponent`**, with `isBuiltIn` and `traitName` per component, so a host can
+  hide a setting its build would ignore.
+- **`Probes/AllTraits`**, a consumer package that enables every trait; CI builds it for tvOS and iOS, runs
+  the suite with all traits (including on a one-thread cooperative pool) and builds a release `aetherctl`
+  with them. The Dolby Vision pulse probe links the engine through `PulseEngine/` with
+  `DualLayerDolbyVision` and refuses to run its FEL arms without it.
+- `aetherctl feltest`, `play --cycle-el` and `play --dv-pin` need `DualLayerDolbyVision` and exit 64
+  without it; the `@_spi(Diagnostics)` FEL tooling (`felDecodeProbe`, `FelProbeResult`,
+  `felResidualEnabled`, `armDolbyVisionPinTest` and the pin queries) exists only with it.
 
 ## [7.38.1] - 2026-10-16
 
diff --git a/README.md b/README.md
index ec0ed81ca..dfc82651e 100644
--- a/README.md
+++ b/README.md
@@ -656,26 +656,27 @@ The 7.x line raised the floor from iOS 16, tvOS 17 and macOS 14. A project that
 
 ### Optional components
 
-Three components are compiled only when a host asks for them, each behind a package trait that is **off by default**:
+Four components are compiled only when a host asks for them, each behind a package trait that is **off by default**:
 
 | Trait | Compiles and links | Without it |
 | --- | --- | --- |
 | `TrueHDObjectAudio` | [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD) and the object renderer | TrueHD Atmos keeps the channel bridge whatever `objectAudioRendering` asks |
 | `DTSXObjectAudio` | [LibDTSX](https://github.com/superuser404notfound/LibDTSX) and the object renderer | DTS:X keeps the channel bridge whatever `objectAudioRendering` asks |
-| `DualLayerDolbyVision` | the Profile 7 FEL dual-layer composer (`DualLayerVideoDecoder` and its Metal composer) | a Profile 7 source keeps the native route whatever `preferDualLayerDolbyVision` asks |
+| `DualLayerDolbyVision` | the Profile 7 FEL dual-layer composer (`DualLayerVideoDecoder`, its Metal composer and the per-frame display metadata) | a Profile 7 source keeps the native route whatever `preferDualLayerDolbyVision` asks |
+| `DolbyVisionStillReshaping` | the reshaping that turns a Dolby Vision Profile 5 / AV1 Profile 10.0 frame into a still | such a source has no scrub stills, I-frame stills or held picture (`supportsCacheBackedStills` is false); playback is unaffected |
 
-Without its trait a component is not in the binary: its code is not compiled, and a library behind it is neither linked nor resolved (it drops out of the host's `Package.resolved`). The options that ask for it stay in the API, so a host compiles the same either way; they change nothing, and the session log says why (`TrueHD Atmos rendering requested but not built in (TrueHDObjectAudio trait off)`, `DV P7 dual-layer route: not taken (built without the DualLayerDolbyVision trait)`).
+Without its trait a component is not in the binary: its code is not compiled, and a library behind it is neither linked nor resolved (it drops out of the host's `Package.resolved`). The options that ask for it stay in the API, so a host compiles the same either way; they change nothing, and the session log says why (`TrueHD Atmos rendering requested but not built in (TrueHDObjectAudio trait off)`, `DV P7 dual-layer route: not taken (built without the DualLayerDolbyVision trait)`). A host that wants to hide a setting its build cannot honour asks `AetherEngine.OptionalComponent`, for example `AetherEngine.OptionalComponent.dualLayerDolbyVision.isBuiltIn`.
 
 These components may be subject to third-party patent licensing. Integrators who enable them are responsible for their own licensing.
 
 To enable them, list the traits on the package dependency:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.38.1",
-         traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision"])
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.39.0",
+         traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision", "DolbyVisionStillReshaping"])
 ```
 
-In an Xcode project, the package's traits are set where the package dependency is listed (XcodeGen: `traits: [...]` on the package). The engine itself builds with them through `swift build --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision` (or `--enable-all-traits`); CI builds and tests both the default and the all-traits configuration.
+In an Xcode project, a remote package's traits are set in the package dependency editor (Project › Package Dependencies), and Xcode stores them in the `.pbxproj`. XcodeGen cannot express them yet (2.45.4 drops a `traits:` key on a package without a word), so an XcodeGen project either patches the generated `.pbxproj` after each generate, or depends on a small local package that depends on AetherEngine with the traits set and re-exports it (`@_exported import AetherEngine`). [Probes/AllTraits](Probes/AllTraits/Package.swift) is that package with every trait on, and `Probes/DolbyVisionPulse/Device/PulseEngine` one with `DualLayerDolbyVision` alone. The engine itself builds with them through `swift build --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision,DolbyVisionStillReshaping` (or `--enable-all-traits`); CI builds and tests both the default and the all-traits configuration, and builds the all-traits engine for tvOS and iOS through `Probes/AllTraits`.
 
 ## Support
 
diff --git a/docs/api.md b/docs/api.md
index 01c778926..6f62be1ae 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1139,7 +1139,7 @@ say so on the tracker rather than working around it.
 | Symbol | Notes |
 | --- | --- |
 | `videoGravity` | Fill mode of whichever layer is mounted (`AVPlayerLayer` or the software display layer). Settable; this is the aspect-fit / aspect-fill control. |
-| `AetherStillView`, `bindStillView(_:)`, `unbindStillView(_:)` | For a host that renders the native path through AVKit rather than `AetherPlayerView`. An audio-track switch swaps the item in place, and `replaceCurrentItem` blanks the player layer until the new item's first frame; the engine holds the outgoing picture over that gap on the bound still view (or, without one, on the bound `AetherPlayerView`). Transparent and input-free; place it above the video and below the host's chrome, e.g. at the top of `AVPlayerViewController.contentOverlayView`, and set its `videoGravity` to the host player's fill. The software path holds its renderer's last picture across the rebuild the same way. Dolby Vision without a displayable base layer (Profile 5, AV1 Profile 10) is held as a 960-wide still decoded from the resident segment through the scrub stills' RPU reshaping, which the switch waits for (up to 3 s, the outgoing picture paused meanwhile); other profiles hold their base layer. Nothing is held in PiP or on external playback. |
+| `AetherStillView`, `bindStillView(_:)`, `unbindStillView(_:)` | For a host that renders the native path through AVKit rather than `AetherPlayerView`. An audio-track switch swaps the item in place, and `replaceCurrentItem` blanks the player layer until the new item's first frame; the engine holds the outgoing picture over that gap on the bound still view (or, without one, on the bound `AetherPlayerView`). Transparent and input-free; place it above the video and below the host's chrome, e.g. at the top of `AVPlayerViewController.contentOverlayView`, and set its `videoGravity` to the host player's fill. The software path holds its renderer's last picture across the rebuild the same way. Dolby Vision without a displayable base layer (Profile 5, AV1 Profile 10) is held as a 960-wide still decoded from the resident segment through the scrub stills' RPU reshaping (only with the `DolbyVisionStillReshaping` trait; without it the hold is skipped and the outgoing picture is not held), which the switch waits for (up to 3 s, the outgoing picture paused meanwhile); other profiles hold their base layer. Nothing is held in PiP or on external playback. |
 | `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. |
@@ -1257,6 +1257,25 @@ PiP/foreground eligibility and repair/resumption separately from optional decode
 | `activeProducerShiftSeconds`, `frameAhead`, `clockLeadSeconds` | Divergence diagnostics for tracing a clock that disagrees with the picture. Not for production playback logic. |
 | `nativeItemReading()` -> `NativeItemReading?` | AE#509. The native item's own account of itself: `playhead` (`AVPlayerItem.currentTime()`, on the ITEM axis), `loadedRangeCount` (0 = nothing has been PLACED, which no buffer depth can say) and `status` (0 unknown, 1 ready, 2 failed). Async, read off the main actor. nil when no native item is mounted. The engine's published clock is `item + playlistShiftSeconds`, so on a live source hours into an encoder clock the two are thousands of seconds apart in a healthy session: quote both or neither. |
 
+## Optional components
+
+Four parts of the engine are compiled only with their package trait, all off by default
+([README › Optional components](../README.md#optional-components)). The options that ask for them stay
+in the API and are no-ops without the trait, so a host compiles the same either way and asks at run time
+whether a setting would do anything:
+
+| Symbol | Notes |
+| --- | --- |
+| `AetherEngine.OptionalComponent` | `.trueHDObjectAudio`, `.dtsxObjectAudio` (`objectAudioRendering` per codec), `.dualLayerDolbyVision` (`preferDualLayerDolbyVision`), `.dolbyVisionStillReshaping` (stills of Dolby Vision Profile 5 / AV1 Profile 10.0 sources). `CaseIterable`. |
+| `OptionalComponent.isBuiltIn` | Whether this build carries the component. Fixed for the process; hide a toggle whose component reads false. |
+| `OptionalComponent.traitName` | The package trait that compiles it, for a diagnostics screen. |
+
+Without `DolbyVisionStillReshaping`, a Profile 5 / 10.0 source yields no still rather than a wrong one
+(its planes are IPT, which the standard path would read as YCbCr): `scrubThumbnail`,
+`scrubPreviewFrame` and the extractor's stills return nil, `supportsCacheBackedStills` is false, the
+I-frame rendition is absent (`dolbyVisionStillsNotBuiltIn`) and an audio switch holds no picture. The
+session log says so once per session. Playback itself is unaffected.
+
 ## LoadOptions
 
 All flags default to safe values; the table is the full set. Depth for the media-shaped ones is in [formats.md](formats.md).
@@ -1279,14 +1298,14 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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. |
-| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731), in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default, [README › Optional components](../README.md#optional-components)); without a codec's trait the option is accepted and that codec keeps `audioBridgeMode`. `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Each codec needs its package trait (`TrueHDObjectAudio`, `DTSXObjectAudio`, both on by default); with one turned off, that codec keeps the channel bridge and the automatic audio pick no longer prefers it. |
+| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731), in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default, [README › Optional components](../README.md#optional-components)); without a codec's trait the option is accepted and that codec keeps `audioBridgeMode`. `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Without a codec's trait that codec keeps the channel bridge and the automatic audio pick does not prefer it; `AetherEngine.OptionalComponent` tells a host which codecs a build renders. |
 | `confirmAtmos` | false | Background per-track JOC confirmation, republishing `audioTracks` as tracks confirm. Never on the start path; skipped for live and forward-only readers. |
 | `preferredAudioLanguages` | empty | First-frame audio pick from the engine's single probe. Ordered BCP-47 / ISO 639 tags; region and script are normalized and rank within one preference (#590). An explicit `audioSourceStreamIndex` still wins. |
 | `preferredSubtitleLanguages` | empty | Post-load subtitle activation on the host-overlay path. Ranks language specificity (an explicitly opposite script is rejected, not demoted) before the descriptor axis. Pure convenience: no reload and no pre-probe, unlike the audio equivalent. |
 | `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 still per segment: an SDR source gets its own keyframes at full resolution, an HDR10, HLG or Dolby Vision source gets tone-mapped 640-pixel Motion JPEG stills (AVKit shows no scrub thumbnail from a PQ or Dolby Vision keyframe). 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`. |
+| `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 still per segment: an SDR source gets its own keyframes at full resolution, an HDR10, HLG or Dolby Vision source gets tone-mapped 640-pixel Motion JPEG stills (AVKit shows no scrub thumbnail from a PQ or Dolby Vision keyframe). 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, media-playlist routing, and a Dolby Vision Profile 5 / 10.0 source in a build without the `DolbyVisionStillReshaping` trait. 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. |
@@ -1300,7 +1319,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). |
-| `preferDualLayerDolbyVision` | false | Opt in to composing Profile 7 FEL sources on the GPU instead of taking the native route (the single-layer 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where it does not). Needs the `DualLayerDolbyVision` package trait (off by default, [README › Optional components](../README.md#optional-components)); without it the option is accepted and changes nothing. When true, `dolbyVisionHandling` is `.automatic`, the source is a seekable VOD, the first RPU says `el_type` FEL, VideoToolbox decodes HEVC in hardware and the stream fits the real-time budget (UHD at 30 fps for the base layer plus a 1080p enhancement layer; a 24p UHD master uses 80% of it), Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`: both layers decode in VideoToolbox, `DoviFelComposer` reconstructs the picture in Metal and delivers 10-bit P010, and every frame carries its RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, which tvOS applies as Dolby Vision display management. A Profile 7 MEL source, and anything the device cannot decode twice in real time, keeps the native route (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not; the conversion is lossless only for MEL); the load logs one `DV P7 dual-layer route: taken` / `not taken (<reason>)` line either way. What the route gives up against the native one (Picture in Picture, scrub thumbnails, subtitles, AirPlay) is listed in [dolby-vision-fel.md](dolby-vision-fel.md#523-what-the-route-gives-up-against-the-native-route). Known trade-off, audio: the route runs on the software host, whose audio is decoded by FFmpeg and played through the sample-buffer audio renderer, and on tvOS only AVPlayer emits Atmos objects, so an E-AC-3 (JOC) track plays as its channel-bed core (5.1 or 7.1) without the objects; TrueHD behaves as on the native route. The route does not consult the display: with the flag on and a display that does not take Dolby Vision, the route is still taken, the composed full-FEL picture is presented with its attached metadata, and how tvOS presents it is up to the platform (the native route would have played the HDR10 base layer there). The E-AC-3 Atmos trade-off above applies there too. A tuning field, correctable through `reloadAtCurrentPosition(applying:)` on a URL source (which re-runs `load()` and re-decides the route); on a custom `IOReader` source a Profile 7 session refuses a change of this option, or a change of `dolbyVisionHandling` while this option is on, with `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, because the in-place rebuild keeps the route the session was loaded with: call `load()` again with the new option. See [dolby-vision-fel.md](dolby-vision-fel.md). |
+| `preferDualLayerDolbyVision` | false | Opt in to composing Profile 7 FEL sources on the GPU instead of taking the native route (the single-layer 8.1 conversion where the display takes Dolby Vision, the HDR10 base layer where it does not). Needs the `DualLayerDolbyVision` package trait (off by default, [README › Optional components](../README.md#optional-components)); without it the option is accepted and changes nothing, and a `reloadAtCurrentPosition(applying:)` that flips it is not refused. When true, `dolbyVisionHandling` is `.automatic`, the source is a seekable VOD, the first RPU says `el_type` FEL, VideoToolbox decodes HEVC in hardware and the stream fits the real-time budget (UHD at 30 fps for the base layer plus a 1080p enhancement layer; a 24p UHD master uses 80% of it), Profile 7 routes through `SoftwarePlaybackHost` + `DualLayerVideoDecoder`: both layers decode in VideoToolbox, `DoviFelComposer` reconstructs the picture in Metal and delivers 10-bit P010, and every frame carries its RPU converted to Profile 8.1 as a `DolbyVisionRPUData` attachment, which tvOS applies as Dolby Vision display management. A Profile 7 MEL source, and anything the device cannot decode twice in real time, keeps the native route (8.1 where the display takes Dolby Vision, the HDR10 base layer where it does not; the conversion is lossless only for MEL); the load logs one `DV P7 dual-layer route: taken` / `not taken (<reason>)` line either way. What the route gives up against the native one (Picture in Picture, scrub thumbnails, subtitles, AirPlay) is listed in [dolby-vision-fel.md](dolby-vision-fel.md#523-what-the-route-gives-up-against-the-native-route). Known trade-off, audio: the route runs on the software host, whose audio is decoded by FFmpeg and played through the sample-buffer audio renderer, and on tvOS only AVPlayer emits Atmos objects, so an E-AC-3 (JOC) track plays as its channel-bed core (5.1 or 7.1) without the objects; TrueHD behaves as on the native route. The route does not consult the display: with the flag on and a display that does not take Dolby Vision, the route is still taken, the composed full-FEL picture is presented with its attached metadata, and how tvOS presents it is up to the platform (the native route would have played the HDR10 base layer there). The E-AC-3 Atmos trade-off above applies there too. A tuning field, correctable through `reloadAtCurrentPosition(applying:)` on a URL source (which re-runs `load()` and re-decides the route); on a custom `IOReader` source a Profile 7 session refuses a change of this option, or a change of `dolbyVisionHandling` while this option is on, with `SessionReloadRefusal.dualLayerRouteNeedsFreshLoad`, because the in-place rebuild keeps the route the session was loaded with: call `load()` again with the new option. See [dolby-vision-fel.md](dolby-vision-fel.md). |
 | `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). |
 | `hostRetriesExhaustedLiveReplay` | `false` | The host owns the retry after a verified live replay exhausts the in-engine reopen: the engine publishes `liveSourceReplayExhausted` and holds production until `retryLiveSourceRecovery()`. `false` publishes `liveSourceReset` for the same exhaustion. |
 | `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. |
@@ -1354,6 +1373,6 @@ Public for the CLI, the test suite, or a diagnostic overlay, and outside the sha
 - **`playbackBackend`**: the internal rendering backend, exposed read-only for overlays. Hosts must not branch on it; `videoRoute` is the surface that answers the same question honestly.
 - **`HLSVideoEngine`** and its `DiagnosticStats`: the loopback session's own machinery, public because `aetherctl` drives it directly.
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
-- **Dolby Vision Profile 7 FEL tooling** (`@_spi(Diagnostics)`): `FelProbeResult` / `felDecodeProbe` (`aetherctl feltest`) and `felResidualEnabled` (`aetherctl play --cycle-el`), which exist only with the `DualLayerDolbyVision` trait, `DoviRpuSurvey` / `DoviRpuSurveyResult` / `DoviRpuFrameSurvey` / `doviRpuSurvey` (`aetherctl dvsurvey`), and, in `DEBUG` builds only, `armDolbyVisionPinTest` / `dolbyVisionPinIsArmed` / `dolbyVisionPinIsActive` (`aetherctl play --dv-pin`). Hosts import none of them; the host surface of the FEL route is `LoadOptions.preferDualLayerDolbyVision` and, in `SessionReloadRefusal`, the new case `.dualLayerRouteNeedsFreshLoad`. See [Dolby Vision FEL](dolby-vision-fel.md) and [CLI](cli.md).
+- **Dolby Vision Profile 7 FEL tooling** (`@_spi(Diagnostics)`): `FelProbeResult` / `felDecodeProbe` (`aetherctl feltest`) and `felResidualEnabled` (`aetherctl play --cycle-el`), which exist only with the `DualLayerDolbyVision` trait, `DoviRpuSurvey` / `DoviRpuSurveyResult` / `DoviRpuFrameSurvey` / `doviRpuSurvey` (`aetherctl dvsurvey`), and, in `DEBUG` builds with the `DualLayerDolbyVision` trait only, `armDolbyVisionPinTest` / `dolbyVisionPinIsArmed` / `dolbyVisionPinIsActive` (`aetherctl play --dv-pin`). Hosts import none of them; the host surface of the FEL route is `LoadOptions.preferDualLayerDolbyVision` and, in `SessionReloadRefusal`, the new case `.dualLayerRouteNeedsFreshLoad`. See [Dolby Vision FEL](dolby-vision-fel.md) and [CLI](cli.md).
 - **`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.
diff --git a/docs/architecture.md b/docs/architecture.md
index 0dabdc297..45d8c0ab3 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -377,6 +377,7 @@ Sources/AetherEngine/
 ├── AetherEngine+Probe.swift Static probe machinery: probe(url:/source:), shared HDR10+/Atmos detail orchestration, swDecodeProbe, format / frame-rate / codec-label detection
 ├── ProbeControl.swift Opt-in whole-probe input/packet/deadline accounting and caller cancellation; native callbacks retain their control until synchronous work returns
 ├── AetherEngine+Loading.swift               The per-backend loaders (remote-HLS, native, software, audio, audio-native) + reload
+├── AetherEngine+OptionalComponents.swift   `AetherEngine.OptionalComponent`: which trait-gated components (object audio, dual-layer DV, DV still reshaping) this build carries
 ├── AetherEngine+Subtitles.swift             Embedded + external subtitle pipeline (packet-store drainer, cue apply / prune, `closeOpenEndedCues` taking a placeholder end from the next stored packet, or retiring it at the reconstruction window when the store has none, external track registry + unified selection routing, #88). Every embedded stream is tapped off the session demuxer into `SubtitlePacketStore`; a playhead-paced drainer decodes the selected stream (both channels, text and bitmap, VOD and live) into the overlay, riding producer seeks/restarts by construction, which replaced the side-demuxer reader and its recovery machinery outright (#112 rework); a VOD-only forward prefetcher extends store coverage past the producer park to the 60 s drain lead for host advance sync offsets (#151), plus a margin so the harvest leads the decode and the set at the window's edge can take its authored end from the store (#362); side readers yield the source link to the video path while it is fetching or seeking (#240, `SideReaderLinkPolicy`); the drain tick states how far display-state determination has advanced on the absolute source axis, fenced by load + seek generation, so a host or conformance harness can tell "determined, and empty" from "not read yet" (#250, `AetherEngine+SubtitleResolution.swift`)
 ├── AetherEngine+ClosedCaptions.swift        In-band CEA-608 closed captions + A53/SEI extraction: ClosedCaptionTap (read-only producer observer) + cue mirroring (#77, #131)
 ├── AetherEngine+Live.swift                  Live window publishing, edge snap, resume clamp, scrub thumbnails
@@ -429,7 +430,7 @@ Sources/AetherEngine/
 │   ├── A53SEIParser.swift                   A53/GA94 cc_data extraction from H.264/HEVC SEI NALs (#131)
 │   ├── DualLayerPictureAlignment.swift      SW FEL path (`DualLayerDolbyVision` trait): pairs each EL picture with the base picture of the same display slot (POC), falling back to access-unit pairing (#702)
 │   ├── FrameSideDataRing.swift              SW FEL path (`DualLayerDolbyVision` trait): fixed ring of per-frame RPU parameters and display metadata keyed by timestamp (#702)
-│   ├── OrderedDelivery.swift                SW FEL path (not routed yet): hands composed frames from the Metal completion queue to the renderer in decode order, with an epoch for seeks and a stall guard (#702)
+│   ├── OrderedDelivery.swift                SW FEL path (`DualLayerDolbyVision` trait): hands composed frames from the Metal completion queue to the renderer in decode order, with an epoch for seeks and a stall guard (#702)
 │   ├── CCDataParser.swift                   Parses the bare cc_data triplet stream from a demuxable CEA-608 caption track (#77)
 │   ├── CEA608Decoder.swift                  In-house CEA-608 line-21 decoder (field-1 / CC1), validated against FFmpeg ccaption_dec.c (#77)
 │   ├── DeinterlaceFilter.swift              SW path: persistent bwdif / yadif libavfilter graph, engages on the first interlaced frame
@@ -489,7 +490,7 @@ Sources/AetherEngine/
 │   └── FrameRateSnap.swift                  Snap to standard rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60)
 ├── FrameExtractor/
 │   ├── AetherEngine+FrameExtractor.swift    makeFrameExtractor() convenience for the currently loaded URL
-│   ├── DolbyVisionStillConverter.swift      Applies the RPU-carried DV colour transform to a DV P5 / P10.0 base-layer frame (IPT-PQ-C2, not YCbCr) so scrub stills lose the green + magenta cast (#103)
+│   ├── DolbyVisionStillConverter.swift      `DolbyVisionStillReshaping` trait. Applies the RPU-carried DV colour transform to a DV P5 / P10.0 base-layer frame (IPT-PQ-C2, not YCbCr) so scrub stills lose the green + magenta cast (#103)
 │   ├── FrameExtractor.swift                 Off-playback still extraction actor: serial decode queue, cancel-supersede, idle-close
 │   ├── FrameDecodeContext.swift             Isolated FFmpeg demux + decode + sws_scale → CGImage (thumbnail / snapshot)
 │   ├── FrameCache.swift                     Bounded LRU: mode-isolated stores, second-bucketed thumbnails
@@ -567,11 +568,11 @@ Sources/AetherEngine/
 │   ├── DoviRpuConverter.swift               libdovi RPU surgery for both routes. Native path: per-packet Profile 7 → 8.1 rewrite (convert type-62 RPU, drop type-63 EL). SW FEL path: `separateDualLayers` also lifts the EL into its own packet and returns the composer's reshaping parameters plus the 8.1 RPU attached as display metadata
 │   ├── DoviRpuConverter+Probe.swift         Diagnostic DV-conversion probe (`doviConvertProbe` / `DoviConvertProbeResult`), backs `aetherctl dovitest`
 │   ├── HEVCPictureOrderCount.swift          H.265 picture order count (8.3.1) of one layer from parameter sets and first slice headers, no decoding; nil for anything it cannot follow (#702)
-│   ├── DoviDisplayMetadata.swift            SW FEL path: sets `DolbyVisionRPUData` (the Profile 8.1 RPU minus its NAL header) and `DolbyCompatibilityID` (the CFString "1", never a number) on every emitted buffer, or clears both; tvOS consumes them in backboardd
-│   ├── DoviDisplayMetadataDebug.swift       DEBUG-only pin test: substitutes a captured RPU on a duty cycle, the on-device consumption test
+│   ├── DoviDisplayMetadata.swift            SW FEL path (`DualLayerDolbyVision` trait): sets `DolbyVisionRPUData` (the Profile 8.1 RPU minus its NAL header) and `DolbyCompatibilityID` (the CFString "1", never a number) on every emitted buffer, or clears both; tvOS consumes them in backboardd
+│   ├── DoviDisplayMetadataDebug.swift       DEBUG-only pin test (`DualLayerDolbyVision` trait): substitutes a captured RPU on a duty cycle, the on-device consumption test
 │   ├── DoviRpuSurvey.swift                  L1 / L2 display-metadata survey over a title's RPUs (no decode, no GPU); backs `aetherctl dvsurvey`
 │   ├── AetherEngine+FelProbe.swift          `DualLayerDolbyVision` trait: FEL decode probe backing `aetherctl feltest`, and the `--cycle-el` residual switch
-│   ├── AetherEngine+DolbyVisionTest.swift   DEBUG-only `@_spi(Diagnostics)` hook (not host API) that arms the pin test from a debug menu or `aetherctl play --dv-pin`
+│   ├── AetherEngine+DolbyVisionTest.swift   DEBUG-only, `DualLayerDolbyVision` trait: `@_spi(Diagnostics)` hook (not host API) that arms the pin test from a debug menu or `aetherctl play --dv-pin`
 │   ├── Metal/                               `DualLayerDolbyVision` trait only
 │   │   ├── DoviFelComposer.swift            BL + EL + RPU composition: runtime-compiled pipelines, pooled P010 output, `composeAsync` bounded at `maxFramesInFlight` with completions on its own serial queue; RPU → `DoviMetalParams` parsing
 │   │   ├── DoviShaderSource.swift           Luma / chroma compose kernels (reshaping, inverse NLQ, bilinear EL upsampling, ordered dither) and the ABI layout probe, compiled at runtime
diff --git a/docs/cli.md b/docs/cli.md
index 349844f16..856871cd5 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,6 +1,6 @@
 # aetherctl
 
-A standalone macOS CLI shipped alongside the library for repro work without going through TestFlight + Apple TV. It builds with the package's traits, so the optional components ([README › Optional components](../README.md#optional-components)) are in it only when it is built with them: `swift run --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision aetherctl …` for `--atmos-bed`, `play --fel`, `--cycle-el` and `feltest`. Most subcommands operate on a media source URL (`file://` or `http(s)://`); `live`, `dvr`, `hlsfixture`, and `hlslive` run against built-in synthetic fixtures.
+A standalone macOS CLI shipped alongside the library for repro work without going through TestFlight + Apple TV. It builds with the package's traits, so the optional components ([README › Optional components](../README.md#optional-components)) are in it only when it is built with them: `swift run --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision,DolbyVisionStillReshaping aetherctl …` for `--atmos-bed`, `play --fel`, `--cycle-el`, `--dv-pin` and `feltest`, and for Profile 5 / 10.0 stills in `extract` and `play --host-calls` (`DolbyVisionStillReshaping`; without it those stills print as nil). Most subcommands operate on a media source URL (`file://` or `http(s)://`); `live`, `dvr`, `hlsfixture`, and `hlslive` run against built-in synthetic fixtures.
 
 ```bash
 swift run aetherctl probe <url>          # dump container + streams + duration, exit
@@ -260,7 +260,7 @@ live-only session took a rebuild that rejoins at the edge.
 
 `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.
 
-`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route, which a build without the `DualLayerDolbyVision` trait accepts and ignores (`--cycle-el` exits 64 there). It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` (at least 0.1) flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` (a release build refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
+`play --fel` sets `LoadOptions.preferDualLayerDolbyVision = true`, the opt-in to the Profile 7 FEL dual-layer route, which a build without the `DualLayerDolbyVision` trait accepts and ignores (`--cycle-el` exits 64 there). It is off by default, as it is in the engine, so a plain `play` runs the route a host gets; `--no-fel` and `--no-dual-layer` are accepted as no-ops. `--surface` (or `--window`, the same flag) presents into a 1280x720 window, macOS only, so the picture can be looked at. `--cycle-el <seconds>` (at least 0.1) flips the FEL residual off and on every period, starting with the full result, and posts the current mode as a label over the picture and in the window title: the off phase is what a minimal enhancement layer decodes to, so the window is an A/B of the residual on the same frames. It changes only a session on the dual-layer route, so it wants `--fel` (without it `play` prints a note) and a surface to be seen on. `--dv-pin <spec>` arms the on-device consumption test in a DEBUG build of `aetherctl` with the `DualLayerDolbyVision` trait (a release build, or one without the trait, refuses the flag with exit 64): after composition it substitutes a captured frame's Dolby Vision metadata on a duty cycle, leaving the pixels untouched, so a visible pulse can only come from the metadata. The spec is the grammar `dvsurvey` prints, such as `darkest:240,period:2`; a spec with no capture rule is refused with exit 64. See [dolby-vision-fel.md](dolby-vision-fel.md).
 
 `--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.
 
diff --git a/docs/dolby-vision-fel.md b/docs/dolby-vision-fel.md
index 78881896e..085b69ab8 100644
--- a/docs/dolby-vision-fel.md
+++ b/docs/dolby-vision-fel.md
@@ -8,8 +8,9 @@ memory while staying correct.
 package trait, which is off by default ([README › Optional components](../README.md#optional-components)).
 Built without it, `preferDualLayerDolbyVision` is accepted and changes nothing: the route decision
 reports `not taken (built without the DualLayerDolbyVision trait)` and every Profile 7 source takes the
-native route. Everything below describes a build with the trait; `aetherctl play --fel`, `--cycle-el` and
-`aetherctl feltest` need it too.
+native route. Everything below describes a build with the trait; `aetherctl play --fel`, `--cycle-el`,
+`--dv-pin`, `aetherctl feltest` and the DEBUG pin test (`armDolbyVisionPinTest`) need it too, and the
+pulse probe links the engine with it through `Probes/DolbyVisionPulse/Device/PulseEngine`.
 
 **Platforms.** Nothing in the route or the composer is tvOS-specific: the two VideoToolbox decoders and
 the Metal kernels are the same on iOS, iPadOS and macOS, the route has no platform gate, and
@@ -263,7 +264,7 @@ passes it into `VideoRoutingPolicy`:
 | Source | `dolbyVisionHandling` | `preferDualLayerDolbyVision` | Device | Route |
 |---|---|---|---|---|
 | P7, `el_type` FEL | `.automatic` | true (opt-in; the default is false) | VideoToolbox HEVC hardware + Metal | software host, `DualLayerVideoDecoder` |
-| P7, `el_type` FEL | `.automatic` | false (the default), a build without the `DualLayerDolbyVision` trait, or no VideoToolbox HEVC hardware decode | — | native (8.1 conversion where the display takes Dolby Vision, otherwise the HDR10 base layer) |
+| P7, `el_type` FEL | `.automatic` | false (the default), a build without the `DualLayerDolbyVision` trait, or no VideoToolbox HEVC hardware decode | any | native (8.1 conversion where the display takes Dolby Vision, otherwise the HDR10 base layer) |
 | P7, `el_type` MEL | `.automatic` | any | — | native (as above; the conversion loses nothing for MEL) |
 | P7, any | `.baseLayerOnly` | any | — | HDR10 base layer |
 
diff --git a/docs/formats.md b/docs/formats.md
index 70aef2d19..747e6af1c 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -539,7 +539,7 @@ let still   = await frames.snapshot(at: 612.0)     // CGImage?, frame-accurate
 await frames.shutdown()                            // prompt teardown of the decode context
 ```
 
-HDR sources come out looking right: PQ / HLG BT.2020 frames are tone-mapped to SDR BT.709 through a zscale + tonemap libavfilter graph before the `CGImage` is built, so HDR10 / HLG / DV P8.x stills match what the user sees instead of washed-out grey. Dolby Vision Profile 5 and AV1 Profile 10.0 (IPT-PQ base layers with no HDR10 fallback) route through `DolbyVisionStillConverter`, which applies the RPU colour transform (`ycc_to_rgb` + PQ EOTF + the IPT-PQ LMS matrices carried in `AV_FRAME_DATA_DOVI_METADATA`) before tone-mapping, so their stills come out with correct colour instead of the green / magenta cast a plain YCbCr read produces.
+HDR sources come out looking right: PQ / HLG BT.2020 frames are tone-mapped to SDR BT.709 through a zscale + tonemap libavfilter graph before the `CGImage` is built, so HDR10 / HLG / DV P8.x stills match what the user sees instead of washed-out grey. Dolby Vision Profile 5 and AV1 Profile 10.0 (IPT-PQ base layers with no HDR10 fallback) route through `DolbyVisionStillConverter`, an optional component compiled only with the `DolbyVisionStillReshaping` package trait (off by default, [README › Optional components](../README.md#optional-components)); built without it, such a source yields no still at all (nil, `supportsCacheBackedStills` false, no I-frame rendition, no held picture) rather than the planes read as YCbCr. With the trait, the converter applies the RPU colour transform (`ycc_to_rgb` + PQ EOTF + the IPT-PQ LMS matrices carried in `AV_FRAME_DATA_DOVI_METADATA`) before tone-mapping, so their stills come out with correct colour instead of the green / magenta cast a plain YCbCr read produces.
 
 `FrameExtractor` is an `actor`. Blocking FFmpeg work runs on a dedicated serial queue, never on the cooperative thread pool. The decode context opens lazily on first use; a superseded request (the common case during an active scrub) cancels the in-flight decode so the latest position wins. Results land in a bounded LRU cache (snapshots and thumbnails kept in separate stores, thumbnails bucketed by second). After 10 s idle the context closes and the cache drops automatically; the next request reopens lazily. `shutdown()` is the explicit, permanent teardown. The engine does not retain the extractor returned by `makeFrameExtractor()`; the caller owns its lifecycle.
 

From 834f5fd4e15057b8f5a91ecc3c4b2113da5f7261 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 11:23:53 +0200
Subject: [PATCH 113/132] chore(release): prep 7.39.0 - object audio, Profile 7
 FEL and DV P5 stills are opt-in traits

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 aaf6407b8..e869ccc32 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.39.0] - 2026-10-17
+
 **Not built by default any more: TrueHD Atmos and DTS:X object rendering, Profile 7 FEL dual-layer
 composition, and Dolby Vision Profile 5 / 10.0 stills.** Each is now an optional component behind a
 package trait that is off by default (`TrueHDObjectAudio`, `DTSXObjectAudio`, `DualLayerDolbyVision`,
diff --git a/Examples/README.md b/Examples/README.md
index 4f7f7d479..ceacda69c 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.38.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.39.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 dfc82651e..228747877 100644
--- a/README.md
+++ b/README.md
@@ -387,7 +387,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.38.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.39.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -634,10 +634,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.38.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.39.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.38.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.39.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 529484f2a..313b75954 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.38.1"
+    public nonisolated static let version = "7.39.0"
 }

From 9a2cd713245fa70c3a9f97c8a7eed7f6adf66c80 Mon Sep 17 00:00:00 2001
From: Aravindh Sampathkumar <aravindh@fastmail.com>
Date: Sat, 17 Oct 2026 14:17:24 +0200
Subject: [PATCH 114/132] docs(audio): the channel bridge, not the engine,
 drops Atmos objects (#802)

The Known limitations entry, the AudioDelivery.bridged reference and the
channel bridge's notes predate objectAudioRendering (#731) and said
TrueHD Atmos objects and DTS:X heights are always lost. Say the channel
bridge drops them and objectAudioRendering keeps them, as lossy APAC.
---
 CHANGELOG.md                                              | 8 +++++++-
 Sources/AetherEngine/Audio/AudioBridge.swift              | 3 ++-
 Sources/AetherEngine/PlayerState.swift                    | 8 +++++---
 .../AetherEngine/Video/HLSVideoEngine+AudioRoute.swift    | 2 +-
 docs/api.md                                               | 2 +-
 docs/formats.md                                           | 4 ++--
 6 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e869ccc32..4ffb2e87d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,13 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Changed
+
+- **The documentation no longer says TrueHD Atmos objects are always lost.** The Known limitations
+  entry in `docs/formats.md`, the `AudioDelivery.bridged` reference and the channel bridge's notes
+  predate `objectAudioRendering` (#731) and said objects and heights never survive. They now say the
+  channel bridge drops them and `objectAudioRendering = .apac(layout)` keeps them, rendered into a
+  speaker bed as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT. No behaviour change.
 
 ## [7.39.0] - 2026-10-17
 
diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index 278726a3e..2399f2d68 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -14,7 +14,8 @@ import AetherLibswresample
 ///
 /// Atmos object metadata survives neither mode (TrueHD-MAT objects interleaved in the source, FFmpeg's EAC3 encoder
 /// produces no JOC, FLAC has no object channel concept). EAC3+JOC sources stay lossless via the stream-copy path
-/// that bypasses this bridge; only non-stream-copyable sources enter here.
+/// that bypasses this bridge; only non-stream-copyable sources enter here. TrueHD Atmos and DTS:X keep their objects
+/// and heights only under `LoadOptions.objectAudioRendering`, which routes them to `SpatialAudioBridge` instead.
 ///
 /// Encoder choice. Public so LoadOptions / the host pass it through; default `.surroundCompat`, the one mode
 /// that keeps surround on every sink.
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 2e059c4ed..824769291 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -110,9 +110,11 @@ public enum AudioDelivery: String, Sendable, Equatable, CaseIterable {
     /// The source's audio bitstream is muxed into fMP4 unchanged: Atmos, DTS-HD and every other
     /// bitstream reach the renderer exactly as authored.
     case streamCopy
-    /// The audio is decoded and re-encoded (FLAC or E-AC-3) for the fMP4 pipeline, because its codec
-    /// is not fMP4-legal or AVPlayer rejects it there. Lossless for the bed channels; object metadata
-    /// in a TrueHD-MAT or JOC bitstream does not survive the PCM intermediate.
+    /// The audio is decoded and re-encoded for the fMP4 pipeline, because its codec is not fMP4-legal
+    /// or AVPlayer rejects it there. The channel bridge (FLAC or E-AC-3) is lossless for the bed
+    /// channels, and object metadata in a TrueHD-MAT or JOC bitstream does not survive its PCM
+    /// intermediate; under `LoadOptions.objectAudioRendering` TrueHD Atmos and DTS:X are rendered with
+    /// their objects and heights into a speaker bed and encoded as APAC instead.
     case bridged
     /// libavcodec decodes the audio and the engine renders it itself (the software path and the
     /// software audio-only host).
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
index 68f9b5f08..d730bf50b 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
@@ -5,7 +5,7 @@ import AetherLibavutil
 
 extension HLSVideoEngine {
 
-    /// Audio codec routing: stream-copy (fMP4-legal, preserves Atmos/DTS-HD) vs AudioBridge (decode->S16 PCM->FLAC for non-fMP4-legal codecs; TrueHD-MAT Atmos object metadata lost in PCM intermediate).
+    /// Audio codec routing: stream-copy (fMP4-legal, preserves Atmos/DTS-HD) vs AudioBridge (decode to PCM, then FLAC or EAC3, for non-fMP4-legal codecs; TrueHD-MAT Atmos object metadata lost in the PCM intermediate unless `objectAudioRendering` sends it to `SpatialAudioBridge`).
     enum AudioCodecCompat {
         case aac, ac3, eac3, flac, alac, mp3, opus
         case truehd, dts
diff --git a/docs/api.md b/docs/api.md
index 6f62be1ae..6833d0081 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -397,7 +397,7 @@ typed fact rather than as something to reconstruct (AE#462).
 | `.none` | no session |
 | `.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 |
+| `.bridged` | decoded and re-encoded for the fMP4 pipeline: by the channel bridge to FLAC or E-AC-3, lossless for the bed channels with object metadata lost in the PCM intermediate, or under `objectAudioRendering` rendered with its objects and heights into a speaker bed and encoded as APAC (lossy) |
 | `.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, 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 |
diff --git a/docs/formats.md b/docs/formats.md
index 747e6af1c..f3236722b 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -281,7 +281,7 @@ The engine does not pick between the two from the route (AE#794): with tvOS's Co
 
 Either encoder opens at a sample rate it actually has, which is not always the source's (AE#548). E-AC-3 exists at 32 / 44.1 / 48 kHz only, so a 96 kHz TrueHD or DTS-HD master is resampled to 48 kHz on the `.surroundCompat` arm; opening the encoder at the source rate instead made `avcodec_open2` refuse the context and took the whole session to silent video-only. The rates come from `avcodec_get_supported_config`, so an FFmpeg bump that widens them needs no change here, and an encoder that advertises no list (FLAC) keeps the source rate untouched, which is what keeps `.lossless` bit-perfect at 96 and 192 kHz. The resampler is in the path on every bridged packet either way, so the conversion costs nothing that was not already being paid.
 
-`.surroundCompat` is the default because the soundbar / basic-AVR install base is the majority. Object metadata (Atmos / TrueHD-MA) is lost in either mode: FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object-channel concept. If a JOC source ever falls through to the bridge the engine logs a loud `WARNING: Atmos downgrade, ...`.
+`.surroundCompat` is the default because the soundbar / basic-AVR install base is the majority. Object metadata (TrueHD Atmos objects, DTS:X heights) is lost in either mode: FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object-channel concept. `objectAudioRendering` is the route that keeps it, rendered into a speaker bed and delivered as APAC ([TrueHD Atmos with heights](#truehd-atmos-with-heights)). If a JOC source ever falls through to the bridge the engine logs a loud `WARNING: Atmos downgrade, ...`.
 
 Two bridge lifecycle invariants (issue #99): the encoder PTS counter re-bases onto the first fed packet's (gate-shifted) source PTS on every session start and producer restart, so bridged audio always shares the video's output timeline, including a `load(startPosition:)` resume that anchors mid-file (a 0-based bridge timeline puts the audio track a full resume-offset away from video inside the same fragments, which AVPlayer silently discards). And the EOF tail flush leaves the encoder in FFmpeg's terminal draining state, so the bridge latches that and rebuilds the encoder on the next restart; a VOD pump that still dies with `muxerFailed` gets a bounded producer rebuild instead of stranding the session.
 
@@ -613,7 +613,7 @@ Raw live MPEG-TS over HTTP (a tuner, a tuner proxy, or an IPTV panel's continuou
 
 Things that work today but have a documented edge case, or are deferred behind an upstream dependency:
 
-- **TrueHD-MAT Atmos object metadata is not preserved.** TrueHD / MLP sources route through the AudioBridge (FFmpeg's EAC3 encoder doesn't produce JOC). Bed channels and surround layout survive; object metadata is dropped. EAC3+JOC stream-copy from MKV / MP4 sources is intact.
+- **The channel bridge drops TrueHD Atmos objects and DTS:X heights.** TrueHD / MLP and DTS-HD sources route through the AudioBridge (FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object channels): bed channels and surround layout survive, objects and heights do not. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them, rendered into a speaker bed and delivered as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT ([TrueHD Atmos with heights](#truehd-atmos-with-heights), [DTS:X with heights](#dtsx-with-heights)). EAC3+JOC stream-copy from MKV / MP4 sources is intact either way.
 - **`.surroundCompat` audio bridge caps 7.1 sources to 5.1.** FFmpeg's EAC3 encoder currently caps at 6 channels. Once [FFmpeg PR 21668](https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls/21668) lands the cap and the dynamic bitrate auto-scale to 1024 kbps engage without a code change here. Use `.lossless` (FLAC) today if 7.1 matters.
 - **Manual `MPNowPlayingInfoCenter` writes race the HLS-loopback path on tvOS 26.** The combination produces a `libdispatch` race. `AVPlayerViewController` with its standard transport bar surfaces Now Playing on its own, through AVKit's private MediaRemote registration, and needs nothing from the host. A host with a custom transport instead sets `engine.ownsVideoNowPlayingSession = true` before `load()`: the native host then owns an `MPNowPlayingSession` bound to its player (published as `videoNowPlayingSession`), registers transport commands on that session's `remoteCommandCenter`, and stages identity metadata through `setVideoNowPlayingInfo(_:)`, which is replayed onto every fresh `AVPlayerItem`. The session auto-publishes elapsed time, rate and duration from the player, so nothing writes `MPNowPlayingInfoCenter.default().nowPlayingInfo`. The flag is off by default and must stay off under AVKit: two owners produce the half-working state where an empty identity card displaces AVKit's and remote commands route into a session with no handlers.
 - **Audio session is activated per playback, not at process launch.** The engine declares the `AVAudioSession` category (`.playback` / `.moviePlayback`) and multichannel support at init, but does NOT activate the session there. The route-sharing policy is platform-split (#116): tvOS declares `.longFormAudio`, iOS declares `.default`, because `.longFormAudio` marks the process as a long-form audio client and pins `AVPictureInPictureController.isPictureInPicturePossible` to false for any host-built PiP controller around the engine's player layer. Hosts do not need to re-declare the session for PiP. Activating once at launch used to pin the route to whatever the HDMI link reported at that instant: with tvOS Continuous Audio Connection off the link idles at stereo, so the launch-time activation negotiated the route to 2 channels and pinned it, downmixing non-Atmos multichannel for the whole session (AetherEngine#24). The native video path now lets the host's `AVPlayerViewController` activate the session per playback; the renderer paths (software decode, audio-only) activate it themselves, off the main actor and before their host is built (AE#538). Hosts that mount the engine's bare `AVPlayerLayer` instead of an `AVPlayerViewController` should ensure the session is active at playback. A genuine sink-side ch=2 (an AVR caching its HDMI EDID incorrectly after standby) can still force a downmix; power-cycling the sink restores it. Atmos passthrough is unaffected either way because EAC3+JOC ships as MAT 2.0 over a 2-channel carrier.

From f2509d883b79a4f4bd051885cb78feec8da7275d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 14:18:39 +0200
Subject: [PATCH 115/132] docs(audio): object audio keeps objects only in a
 build with its traits

#802 predates 7.39.0, where TrueHD and DTS:X object rendering became the
off-by-default TrueHDObjectAudio / DTSXObjectAudio traits. Without them
objectAudioRendering changes nothing and the channel bridge still drops
objects and heights, so every place #802 touched now names the traits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                               | 6 ++++--
 Sources/AetherEngine/Audio/AudioBridge.swift               | 3 ++-
 Sources/AetherEngine/PlayerState.swift                     | 3 ++-
 Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift | 2 +-
 docs/api.md                                                | 2 +-
 docs/formats.md                                            | 4 ++--
 6 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4ffb2e87d..1dcd79b94 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,10 @@ the public-API contract.
 - **The documentation no longer says TrueHD Atmos objects are always lost.** The Known limitations
   entry in `docs/formats.md`, the `AudioDelivery.bridged` reference and the channel bridge's notes
   predate `objectAudioRendering` (#731) and said objects and heights never survive. They now say the
-  channel bridge drops them and `objectAudioRendering = .apac(layout)` keeps them, rendered into a
-  speaker bed as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT. No behaviour change.
+  channel bridge drops them and `objectAudioRendering = .apac(layout)` keeps them, in a build with the
+  `TrueHDObjectAudio` / `DTSXObjectAudio` traits (off by default since 7.39.0), rendered into a speaker
+  bed as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT. No behaviour change (#802,
+  thanks @aravindhsampath).
 
 ## [7.39.0] - 2026-10-17
 
diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index 2399f2d68..f128f3311 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -15,7 +15,8 @@ import AetherLibswresample
 /// Atmos object metadata survives neither mode (TrueHD-MAT objects interleaved in the source, FFmpeg's EAC3 encoder
 /// produces no JOC, FLAC has no object channel concept). EAC3+JOC sources stay lossless via the stream-copy path
 /// that bypasses this bridge; only non-stream-copyable sources enter here. TrueHD Atmos and DTS:X keep their objects
-/// and heights only under `LoadOptions.objectAudioRendering`, which routes them to `SpatialAudioBridge` instead.
+/// and heights only under `LoadOptions.objectAudioRendering`, in a build with the `TrueHDObjectAudio` /
+/// `DTSXObjectAudio` traits (off by default), which routes them to `SpatialAudioBridge` instead.
 ///
 /// Encoder choice. Public so LoadOptions / the host pass it through; default `.surroundCompat`, the one mode
 /// that keeps surround on every sink.
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 824769291..d2e18e7df 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -113,7 +113,8 @@ public enum AudioDelivery: String, Sendable, Equatable, CaseIterable {
     /// The audio is decoded and re-encoded for the fMP4 pipeline, because its codec is not fMP4-legal
     /// or AVPlayer rejects it there. The channel bridge (FLAC or E-AC-3) is lossless for the bed
     /// channels, and object metadata in a TrueHD-MAT or JOC bitstream does not survive its PCM
-    /// intermediate; under `LoadOptions.objectAudioRendering` TrueHD Atmos and DTS:X are rendered with
+    /// intermediate; under `LoadOptions.objectAudioRendering`, in a build with the `TrueHDObjectAudio` /
+    /// `DTSXObjectAudio` traits (off by default), TrueHD Atmos and DTS:X are rendered with
     /// their objects and heights into a speaker bed and encoded as APAC instead.
     case bridged
     /// libavcodec decodes the audio and the engine renders it itself (the software path and the
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
index d730bf50b..a65e19d97 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
@@ -5,7 +5,7 @@ import AetherLibavutil
 
 extension HLSVideoEngine {
 
-    /// Audio codec routing: stream-copy (fMP4-legal, preserves Atmos/DTS-HD) vs AudioBridge (decode to PCM, then FLAC or EAC3, for non-fMP4-legal codecs; TrueHD-MAT Atmos object metadata lost in the PCM intermediate unless `objectAudioRendering` sends it to `SpatialAudioBridge`).
+    /// Audio codec routing: stream-copy (fMP4-legal, preserves Atmos/DTS-HD) vs AudioBridge (decode to PCM, then FLAC or EAC3, for non-fMP4-legal codecs; TrueHD-MAT Atmos object metadata lost in the PCM intermediate unless `objectAudioRendering`, in a build with the object-audio traits, sends it to `SpatialAudioBridge`).
     enum AudioCodecCompat {
         case aac, ac3, eac3, flac, alac, mp3, opus
         case truehd, dts
diff --git a/docs/api.md b/docs/api.md
index 6833d0081..b4185278c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -397,7 +397,7 @@ typed fact rather than as something to reconstruct (AE#462).
 | `.none` | no session |
 | `.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 for the fMP4 pipeline: by the channel bridge to FLAC or E-AC-3, lossless for the bed channels with object metadata lost in the PCM intermediate, or under `objectAudioRendering` rendered with its objects and heights into a speaker bed and encoded as APAC (lossy) |
+| `.bridged` | decoded and re-encoded for the fMP4 pipeline: by the channel bridge to FLAC or E-AC-3, lossless for the bed channels with object metadata lost in the PCM intermediate, or under `objectAudioRendering` in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default) rendered with its objects and heights into a speaker bed and encoded as APAC (lossy) |
 | `.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, 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 |
diff --git a/docs/formats.md b/docs/formats.md
index f3236722b..8337c94ca 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -281,7 +281,7 @@ The engine does not pick between the two from the route (AE#794): with tvOS's Co
 
 Either encoder opens at a sample rate it actually has, which is not always the source's (AE#548). E-AC-3 exists at 32 / 44.1 / 48 kHz only, so a 96 kHz TrueHD or DTS-HD master is resampled to 48 kHz on the `.surroundCompat` arm; opening the encoder at the source rate instead made `avcodec_open2` refuse the context and took the whole session to silent video-only. The rates come from `avcodec_get_supported_config`, so an FFmpeg bump that widens them needs no change here, and an encoder that advertises no list (FLAC) keeps the source rate untouched, which is what keeps `.lossless` bit-perfect at 96 and 192 kHz. The resampler is in the path on every bridged packet either way, so the conversion costs nothing that was not already being paid.
 
-`.surroundCompat` is the default because the soundbar / basic-AVR install base is the majority. Object metadata (TrueHD Atmos objects, DTS:X heights) is lost in either mode: FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object-channel concept. `objectAudioRendering` is the route that keeps it, rendered into a speaker bed and delivered as APAC ([TrueHD Atmos with heights](#truehd-atmos-with-heights)). If a JOC source ever falls through to the bridge the engine logs a loud `WARNING: Atmos downgrade, ...`.
+`.surroundCompat` is the default because the soundbar / basic-AVR install base is the majority. Object metadata (TrueHD Atmos objects, DTS:X heights) is lost in either mode: FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object-channel concept. `objectAudioRendering` is the route that keeps it in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default), [README › Optional components](../README.md#optional-components)), rendered into a speaker bed and delivered as APAC ([TrueHD Atmos with heights](#truehd-atmos-with-heights)). If a JOC source ever falls through to the bridge the engine logs a loud `WARNING: Atmos downgrade, ...`.
 
 Two bridge lifecycle invariants (issue #99): the encoder PTS counter re-bases onto the first fed packet's (gate-shifted) source PTS on every session start and producer restart, so bridged audio always shares the video's output timeline, including a `load(startPosition:)` resume that anchors mid-file (a 0-based bridge timeline puts the audio track a full resume-offset away from video inside the same fragments, which AVPlayer silently discards). And the EOF tail flush leaves the encoder in FFmpeg's terminal draining state, so the bridge latches that and rebuilds the encoder on the next restart; a VOD pump that still dies with `muxerFailed` gets a bounded producer rebuild instead of stranding the session.
 
@@ -613,7 +613,7 @@ Raw live MPEG-TS over HTTP (a tuner, a tuner proxy, or an IPTV panel's continuou
 
 Things that work today but have a documented edge case, or are deferred behind an upstream dependency:
 
-- **The channel bridge drops TrueHD Atmos objects and DTS:X heights.** TrueHD / MLP and DTS-HD sources route through the AudioBridge (FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object channels): bed channels and surround layout survive, objects and heights do not. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them, rendered into a speaker bed and delivered as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT ([TrueHD Atmos with heights](#truehd-atmos-with-heights), [DTS:X with heights](#dtsx-with-heights)). EAC3+JOC stream-copy from MKV / MP4 sources is intact either way.
+- **The channel bridge drops TrueHD Atmos objects and DTS:X heights.** TrueHD / MLP and DTS-HD sources route through the AudioBridge (FFmpeg's EAC3 encoder doesn't produce JOC, and FLAC has no object channels): bed channels and surround layout survive, objects and heights do not. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default), [README › Optional components](../README.md#optional-components)), rendered into a speaker bed and delivered as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT ([TrueHD Atmos with heights](#truehd-atmos-with-heights), [DTS:X with heights](#dtsx-with-heights)). EAC3+JOC stream-copy from MKV / MP4 sources is intact either way.
 - **`.surroundCompat` audio bridge caps 7.1 sources to 5.1.** FFmpeg's EAC3 encoder currently caps at 6 channels. Once [FFmpeg PR 21668](https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls/21668) lands the cap and the dynamic bitrate auto-scale to 1024 kbps engage without a code change here. Use `.lossless` (FLAC) today if 7.1 matters.
 - **Manual `MPNowPlayingInfoCenter` writes race the HLS-loopback path on tvOS 26.** The combination produces a `libdispatch` race. `AVPlayerViewController` with its standard transport bar surfaces Now Playing on its own, through AVKit's private MediaRemote registration, and needs nothing from the host. A host with a custom transport instead sets `engine.ownsVideoNowPlayingSession = true` before `load()`: the native host then owns an `MPNowPlayingSession` bound to its player (published as `videoNowPlayingSession`), registers transport commands on that session's `remoteCommandCenter`, and stages identity metadata through `setVideoNowPlayingInfo(_:)`, which is replayed onto every fresh `AVPlayerItem`. The session auto-publishes elapsed time, rate and duration from the player, so nothing writes `MPNowPlayingInfoCenter.default().nowPlayingInfo`. The flag is off by default and must stay off under AVKit: two owners produce the half-working state where an empty identity card displaces AVKit's and remote commands route into a session with no handlers.
 - **Audio session is activated per playback, not at process launch.** The engine declares the `AVAudioSession` category (`.playback` / `.moviePlayback`) and multichannel support at init, but does NOT activate the session there. The route-sharing policy is platform-split (#116): tvOS declares `.longFormAudio`, iOS declares `.default`, because `.longFormAudio` marks the process as a long-form audio client and pins `AVPictureInPictureController.isPictureInPicturePossible` to false for any host-built PiP controller around the engine's player layer. Hosts do not need to re-declare the session for PiP. Activating once at launch used to pin the route to whatever the HDMI link reported at that instant: with tvOS Continuous Audio Connection off the link idles at stereo, so the launch-time activation negotiated the route to 2 channels and pinned it, downmixing non-Atmos multichannel for the whole session (AetherEngine#24). The native video path now lets the host's `AVPlayerViewController` activate the session per playback; the renderer paths (software decode, audio-only) activate it themselves, off the main actor and before their host is built (AE#538). Hosts that mount the engine's bare `AVPlayerLayer` instead of an `AVPlayerViewController` should ensure the session is active at playback. A genuine sink-side ch=2 (an AVR caching its HDMI EDID incorrectly after standby) can still force a downmix; power-cycling the sink restores it. Atmos passthrough is unaffected either way because EAC3+JOC ships as MAT 2.0 over a 2-channel carrier.

From 33f1e930cb0ae07d6b21d00dc4194da82a213097 Mon Sep 17 00:00:00 2001
From: Aravindh Sampathkumar <aravindh@fastmail.com>
Date: Sat, 17 Oct 2026 15:04:25 +0200
Subject: [PATCH 116/132] feat(audio): LiveTelemetry.objectAudio reports the
 Atmos objects in play (#803)

* feat(audio): LiveTelemetry.objectAudio reports the Atmos objects in play

While objectAudioRendering plays TrueHD Atmos or DTS:X, the 1 Hz
telemetry carries an ObjectAudioActivity: the bed it renders into, the
objects the presentation declares, how many play and how many sit
overhead, and its bed channels on height speakers (DTS:X's standard
heights). These are the counts the bed levels log line has carried
since #731, for a host's stats panel without reading the log. The
bridge publishes them behind a lock of its own, so the sampler never
waits for a decode holding opLock.

aetherctl play takes --atmos-bed as serve does and prints the counts:
obj=13/13 up=4 bed=7.1.4 on a TrueHD Atmos remux.

* docs(audio): LiveTelemetry.objectAudio is nil without the object-audio traits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS

* style(diagnostics): keep audioBridgeOutputBytesLifetime's doc comment on it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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                                  | 12 +++++++
 .../AetherEngine+Diagnostics.swift            |  3 ++
 .../Audio/AudioTranscodingBridge.swift        |  8 +++++
 .../Audio/Spatial/BedLevelMeter.swift         | 15 +++++++-
 .../Audio/Spatial/ObjectAudioActivity.swift   | 30 ++++++++++++++++
 .../Audio/Spatial/SpatialAudioBridge.swift    |  9 +++++
 .../Diagnostics/LiveTelemetry.swift           |  6 ++++
 .../Diagnostics/LiveTelemetrySampler.swift    |  1 +
 .../AetherEngine/Video/HLSVideoEngine.swift   |  1 +
 Sources/aetherctl/PlaybackCmd.swift           | 12 +++++--
 Sources/aetherctl/main.swift                  | 36 +++++++++++--------
 .../SpatialAudioBridgeTests.swift             | 22 ++++++++++++
 docs/api.md                                   |  2 ++
 docs/cli.md                                   |  1 +
 docs/formats.md                               |  4 ++-
 15 files changed, 142 insertions(+), 20 deletions(-)
 create mode 100644 Sources/AetherEngine/Audio/Spatial/ObjectAudioActivity.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1dcd79b94..3cb82879f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,18 @@ the public-API contract.
   bed as lossy APAC that tvOS sends to an Atmos receiver as Dolby MAT. No behaviour change (#802,
   thanks @aravindhsampath).
 
+### Added
+
+- **`LiveTelemetry.objectAudio`: how many Atmos objects play, and how many overhead.** While
+  `objectAudioRendering` plays TrueHD Atmos or DTS:X (a build with the `TrueHDObjectAudio` /
+  `DTSXObjectAudio` traits; without them it stays nil), the 1 Hz snapshot carries an
+  `ObjectAudioActivity`: the bed it renders into, the objects the presentation declares, how many of
+  them play and how many sit above ear level, and its bed channels on height speakers (DTS:X's standard
+  heights). These are the counts the `bed levels` log line has carried since #731, for a host's stats
+  panel without reading the log; they sit behind a lock of their own, so the sampler never waits for a
+  decode. `aetherctl play` takes `--atmos-bed` as `serve` does and prints them: on a TrueHD Atmos
+  remux, `obj=13/13 up=4 bed=7.1.4`.
+
 ## [7.39.0] - 2026-10-17
 
 **Not built by default any more: TrueHD Atmos and DTS:X object rendering, Profile 7 FEL dual-layer
diff --git a/Sources/AetherEngine/AetherEngine+Diagnostics.swift b/Sources/AetherEngine/AetherEngine+Diagnostics.swift
index 875dde213..e45dc97c4 100644
--- a/Sources/AetherEngine/AetherEngine+Diagnostics.swift
+++ b/Sources/AetherEngine/AetherEngine+Diagnostics.swift
@@ -580,6 +580,9 @@ extension AetherEngine {
         nativeVideoSession?.audioBridgeLiveBytes ?? 0
     }
 
+    /// What the object renderer is doing, for `LiveTelemetry.objectAudio`; nil off `objectAudioRendering`.
+    var objectAudioActivity: ObjectAudioActivity? { nativeVideoSession?.objectAudioActivity }
+
     /// Cumulative encoded-audio bytes the bridge has emitted this session. Zero when bridge is not active
     /// (stream-copy path or video-only source). The telemetry sampler diffs it into a live bridge output bitrate.
     var audioBridgeOutputBytesLifetime: Int64 {
diff --git a/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift b/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift
index 30d9dcf75..affcceaa9 100644
--- a/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioTranscodingBridge.swift
@@ -45,6 +45,10 @@ protocol AudioTranscodingBridge: AnyObject, Sendable {
     var liveBytes: AudioBridge.LiveBytes { get }
     var fifoSampleCount: Int { get }
     var outputBytesLifetime: Int64 { get }
+
+    /// What the object renderer is doing, for `LiveTelemetry.objectAudio`; nil for a bridge without
+    /// one. Read off the pump thread, like `outputBytesLifetime`.
+    var objectAudioActivity: ObjectAudioActivity? { get }
 }
 
 extension AudioBridge: AudioTranscodingBridge {
@@ -67,3 +71,7 @@ extension AudioBridge: AudioTranscodingBridge {
     }
     func settle() -> [UnsafeMutablePointer<AVPacket>] { [] }
 }
+
+extension AudioTranscodingBridge {
+    var objectAudioActivity: ObjectAudioActivity? { nil }
+}
diff --git a/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift b/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift
index 0365858c4..f7cb277d3 100644
--- a/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift
+++ b/Sources/AetherEngine/Audio/Spatial/BedLevelMeter.swift
@@ -3,7 +3,8 @@
 import Accelerate
 import Foundation
 
-/// Per-channel levels of the rendered bed, for the session log.
+/// Per-channel levels of the rendered bed, for the session log, and the object counts behind them,
+/// which `LiveTelemetry.objectAudio` also publishes (`activity`).
 ///
 /// A report that the heights or the LFE are missing can only be placed if the log says what the
 /// engine handed AVPlayer. Level here means the encoder was given that channel's sound, so a height
@@ -38,6 +39,9 @@ struct BedLevelMeter {
     /// at all still reports what is playing.
     private var activeObjects = 0
     private var elevatedObjects = 0
+    /// What the current configuration declares, set when it arrives.
+    private var configuredObjects = 0
+    private var heightBedChannels = 0
     private var maxActiveObjects = 0
     private var maxElevatedObjects = 0
 
@@ -63,6 +67,8 @@ struct BedLevelMeter {
         if configurationChanged || elementStates.count != roles.count {
             elementStates = Array(repeating: nil, count: roles.count)
             lfeIndices = roles.indices.filter { roles[$0] == .lfe }
+            configuredObjects = roles.filter { $0 == .object }.count
+            heightBedChannels = roles.filter { if case .bed(let speaker) = $0 { speaker.isHeight } else { false } }.count
             // A configuration with no objects sends no object metadata; the old counts must not hold.
             activeObjects = 0
             elevatedObjects = 0
@@ -83,6 +89,13 @@ struct BedLevelMeter {
         }
     }
 
+    /// The counts as of the latest update, for `LiveTelemetry.objectAudio`.
+    var activity: ObjectAudioActivity {
+        ObjectAudioActivity(
+            layout: layout, objects: configuredObjects, activeObjects: activeObjects, elevatedObjects: elevatedObjects,
+            heightChannels: heightBedChannels)
+    }
+
     /// Measure the LFE elements' combined input for one decoded block (one plane per role).
     mutating func measureInput(roles: [ObjectAudioRole], planes: [UnsafePointer<Float>], frameCount: Int) {
         let indices = roles.indices.filter { roles[$0] == .lfe && $0 < planes.count }
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioActivity.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioActivity.swift
new file mode 100644
index 000000000..71b2e18bd
--- /dev/null
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioActivity.swift
@@ -0,0 +1,30 @@
+import Foundation
+
+/// What the object renderer is doing while `LoadOptions.objectAudioRendering` plays TrueHD Atmos or
+/// DTS:X, published as `LiveTelemetry.objectAudio`: the bed the presentation is rendered into, how
+/// many objects it declares, how many of them play and how many of those sit overhead.
+///
+/// The counts come from the object metadata, as the session log's `bed levels` line does: an active
+/// object can still be silent, and an elevated one can still snap to a floor speaker. They are what
+/// the renderer was asked to place, which is what a host showing "Atmos with heights" can stand on.
+public struct ObjectAudioActivity: Equatable, Sendable {
+    /// The speaker bed the presentation is rendered into, `objectAudioRendering`'s layout.
+    public let layout: SpatialSpeakerLayout
+    /// Dynamic objects the presentation declares; its bed channels and LFE are not objects.
+    public let objects: Int
+    /// Objects with a gain above zero in the latest metadata update.
+    public let activeObjects: Int
+    /// Active objects above ear level whose height speakers no zone mask excludes.
+    public let elevatedObjects: Int
+    /// Bed channels on height speakers. DTS:X's standard presentation carries its four heights this
+    /// way rather than as objects, so a DTS:X track can read 0 objects and still play overhead.
+    public let heightChannels: Int
+
+    public init(layout: SpatialSpeakerLayout, objects: Int, activeObjects: Int, elevatedObjects: Int, heightChannels: Int) {
+        self.layout = layout
+        self.objects = objects
+        self.activeObjects = activeObjects
+        self.elevatedObjects = elevatedObjects
+        self.heightChannels = heightChannels
+    }
+}
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
index 6b1c99e0e..ba4817a5a 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
@@ -85,6 +85,13 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
     private var stats = AudioBridge.FeedStats()
     private(set) var outputBytesLifetime: Int64 = 0
 
+    /// `LiveTelemetry.objectAudio`: written on the pump thread for every rendered block, read at 1 Hz
+    /// by the telemetry sampler. Behind a lock of its own, so that read never waits for a decode or
+    /// an encode holding `opLock`.
+    private let activityLock = NSLock()
+    private var latestActivity: ObjectAudioActivity?
+    var objectAudioActivity: ObjectAudioActivity? { activityLock.withLock { latestActivity } }
+
     /// AE#641: called once, on the pump thread, when the object decoder has been fed
     /// `silentFeedPacketThreshold` packets in a row without returning a block. The APAC
     /// sample entry is written up front, like FLAC's, so nothing downstream fails on its own and the
@@ -367,6 +374,8 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         }
         levelMeter.observe(roles: block.roles, updates: block.updates, configurationChanged: rebuilt)
         levelMeter.measureInput(roles: block.roles, planes: block.planes, frameCount: block.frameCount)
+        let activity = levelMeter.activity
+        activityLock.withLock { latestActivity = activity }
         // Anchor the encoder on the first block after a reset, and keep the encoder's input
         // contiguous with the source afterwards: a gap the decoder skipped (corrupt access units) is
         // filled with silence so everything after it stays on its timestamp.
diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
index 8c5b89554..e13e19e49 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
@@ -28,6 +28,10 @@ public struct LiveTelemetry: Equatable, Sendable {
     /// AVPlayer-native path) or before the first delta. Measured from the bridge's cumulative output-byte
     /// counter, since the common FLAC bridge is lossless VBR and has no fixed configured rate.
     public let audioBridgeBitrateMbps: Double?
+    /// What the object renderer is doing while `objectAudioRendering` plays TrueHD Atmos or DTS:X:
+    /// the bed it renders into and the objects the track declares, plays and lifts. nil on every
+    /// other audio path, the channel bridge included.
+    public let objectAudio: ObjectAudioActivity?
     public let observedFps: Double?
     /// Frames the display dropped **for the session**: AVPlayer's access log on the native path, the
     /// render synchronizer's own metrics on the software one (#306). Software sessions predating that
@@ -97,6 +101,7 @@ public struct LiveTelemetry: Equatable, Sendable {
         instantBitrateMbps: Double?,
         averageBitrateMbps: Double?,
         audioBridgeBitrateMbps: Double?,
+        objectAudio: ObjectAudioActivity? = nil,
         observedFps: Double?,
         droppedFrameCount: Int?,
         forwardBufferSeconds: Double?,
@@ -121,6 +126,7 @@ public struct LiveTelemetry: Equatable, Sendable {
         self.instantBitrateMbps = instantBitrateMbps
         self.averageBitrateMbps = averageBitrateMbps
         self.audioBridgeBitrateMbps = audioBridgeBitrateMbps
+        self.objectAudio = objectAudio
         self.observedFps = observedFps
         self.droppedFrameCount = droppedFrameCount
         self.forwardBufferSeconds = forwardBufferSeconds
diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
index febc04364..6c24877a2 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
@@ -433,6 +433,7 @@ final class LiveTelemetrySampler {
             instantBitrateMbps: instantBitrateMbps,
             averageBitrateMbps: averageBitrateMbps,
             audioBridgeBitrateMbps: audioBridgeBitrateMbps,
+            objectAudio: engine.objectAudioActivity,
             observedFps: observedFps,
             droppedFrameCount: droppedFrameCount,
             forwardBufferSeconds: forwardBufferSeconds,
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index f60b2ccae..4314ff275 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -2634,6 +2634,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
 
     var audioBridgeLiveBytes: Int { subsystemSnapshot().audioBridge?.liveBytes.totalBytes ?? 0 }
     var audioBridgeOutputBytesLifetime: Int64 { subsystemSnapshot().audioBridge?.outputBytesLifetime ?? 0 }
+    var objectAudioActivity: ObjectAudioActivity? { subsystemSnapshot().audioBridge?.objectAudioActivity }
     var lastAVGapMs: Double { subsystemSnapshot().producer?.lastAVGapMs ?? 0 }
 
     public func diagnosticStats() -> DiagnosticStats {
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index d3953572c..0363f8347 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -111,7 +111,7 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
                     audioDelayMs: Int = 0, audioDelaySwitches: [AudioDelaySwitchRequest] = [],
                     pausedMount: Bool = false,
                     optionCorrection: LoadOptionCorrectionRequest? = nil,
-                    sequentialOrigin: Bool = false, maxConcurrentRequests: Int? = nil, heldConnection: Bool = false, progressiveSegments: Bool = false, declaredDuration: Double? = nil,
+                    sequentialOrigin: Bool = false, maxConcurrentRequests: Int? = nil, heldConnection: Bool = false, progressiveSegments: Bool = false, objectAudioRendering: ObjectAudioRendering = .off, declaredDuration: Double? = nil,
                     httpHeaders: [String: String] = [:],
                     deinterlaceFieldRate: DeinterlaceFieldRate = .field,
                     assertDolbyVision: Bool = false,
@@ -139,7 +139,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, servedURL: servedURL, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, nativeVideoFrameDiagnostics: nativeVideoFrameDiagnostics, nativeVideoFrameRecovery: nativeVideoFrameRecovery, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, progressiveSegments: progressiveSegments, preferDualLayerDolbyVision: preferDualLayerDolbyVision, attachSurface: attachSurface, 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, nativeVideoFrameDiagnostics: nativeVideoFrameDiagnostics, nativeVideoFrameRecovery: nativeVideoFrameRecovery, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, progressiveSegments: progressiveSegments, objectAudioRendering: objectAudioRendering, preferDualLayerDolbyVision: preferDualLayerDolbyVision, attachSurface: attachSurface, declaredDuration: declaredDuration, httpHeaders: httpHeaders, deinterlaceFieldRate: deinterlaceFieldRate, assertDolbyVision: assertDolbyVision, preserveASSMarkup: preserveASSMarkup, dolbyVisionHandling: dolbyVisionHandling, record: record)
         CFRunLoopStop(CFRunLoopGetMain())
     }
     CFRunLoopRun()
@@ -168,6 +168,11 @@ private func networkTelemetryFragment(_ telemetry: LiveTelemetry?) -> String {
     if let ahead = telemetry.readerWindowAheadBytes { out += String(format: " ahead=%.1fMB", Double(ahead) / 1_048_576) }
     if let cushion = telemetry.displayCushionSeconds { out += String(format: " cushion=%.2fs", cushion) }
     if let fwd = telemetry.forwardBufferSeconds { out += String(format: " fwd=%.1fs", fwd) }
+    // `--atmos-bed`: active / declared objects, how many of them overhead, the bed, and any height channels.
+    if let objects = telemetry.objectAudio {
+        out += " obj=\(objects.activeObjects)/\(objects.objects) up=\(objects.elevatedObjects) bed=\(objects.layout.rawValue)"
+        if objects.heightChannels > 0 { out += " hch=\(objects.heightChannels)" }
+    }
     if let dropped = telemetry.droppedFrameCount { out += " drop=\(dropped)" }
     if let delay = telemetry.accumulatedFrameDelaySeconds { out += String(format: " delay=%.2fs", delay) }
     return out
@@ -460,7 +465,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, servedURL: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0, nativeVideoFrameDiagnostics: Bool = false, nativeVideoFrameRecovery: Bool = false, 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, progressiveSegments: Bool = false, preferDualLayerDolbyVision: Bool = false, attachSurface: 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, nativeVideoFrameDiagnostics: Bool = false, nativeVideoFrameRecovery: Bool = false, 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, progressiveSegments: Bool = false, objectAudioRendering: ObjectAudioRendering = .off, preferDualLayerDolbyVision: Bool = false, attachSurface: 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()
@@ -558,6 +563,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         dolbyVisionHandling: dolbyVisionHandling,
         preferDualLayerDolbyVision: preferDualLayerDolbyVision,
         panelPresentsDolbyVision: assertDolbyVision,
+        objectAudioRendering: objectAudioRendering,
         isLive: live,
         dvrWindowSeconds: dvrWindow,
         liveJoinProfile: fastZap ? .fastZap : .standard,
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 1693bce4b..fa3a637eb 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -78,7 +78,7 @@ func printUsage() {
                  [--reload-applying <key>=<value>]... [--reload-applying-at <ms>]
                  [--drop-audio]
                  [--sequential-origin] [--declared-duration S]
-             [--max-concurrent-requests N]
+             [--max-concurrent-requests N] [--atmos-bed 7.1.4]
                      [--audio-stats] [--host-calls play,extractor,setrate,pausestart,reloadlive,seekback,seekfar,pauseseek,pausereload,playreload,extplayreload,reloadnext] <url>
                      (full load+play session smoke test; --fel opts into the Profile 7
                       FEL dual-layer route (off by default, as in the engine, and only in
@@ -310,6 +310,22 @@ func printUsage() {
     """)
 }
 
+// MARK: - Object audio
+
+/// `--atmos-bed 7.1.4`: TrueHD Atmos or DTS:X rendered into that bed and delivered as APAC
+/// (`LoadOptions.objectAudioRendering`, #731). Without it the channel bridge plays them.
+private func objectAudioRendering(_ flag: String?) -> ObjectAudioRendering {
+    guard let flag else { return .off }
+    guard let layout = SpatialSpeakerLayout(rawValue: flag) else {
+        print("ERROR: --atmos-bed expects one of \(SpatialSpeakerLayout.allCases.map(\.rawValue)), got '\(flag)'")
+        exit(64)
+    }
+    #if !(TrueHDObjectAudio || DTSXObjectAudio)
+    print("[aetherctl] note: --atmos-bed renders nothing without the TrueHDObjectAudio / DTSXObjectAudio traits")
+    #endif
+    return .apac(layout)
+}
+
 // MARK: - URL parsing
 
 private func parseSourceURL(_ raw: String) -> URL {
@@ -810,6 +826,8 @@ if first == "play" {
     // LoadOptions.progressiveSegmentDelivery: serve each VOD segment while it is written. Pair it
     // with a throttled origin to see the startup difference; on a fast source nothing changes.
     let progressiveSegments = takeFlag("--progressive-segments", from: &rest)
+    // #731: TrueHD Atmos or DTS:X rendered into a bed as APAC; the 1 Hz line then reports its objects.
+    let playObjectAudio = objectAudioRendering(takeStringFlag("--atmos-bed", from: &rest))
     let declaredDuration = takeDoubleFlag("--declared-duration", from: &rest)
     // #311: install the software frame-time observer and read the presentation timebase, so the
     // per-frame boundaries and the clock a host would pace an overlay against are both observable.
@@ -1016,6 +1034,7 @@ if first == "play" {
                  sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests,
                  heldConnection: heldConnection,
                  progressiveSegments: progressiveSegments,
+                 objectAudioRendering: playObjectAudio,
                  declaredDuration: declaredDuration,
                  httpHeaders: playHeaders,
                  deinterlaceFieldRate: playFieldRate,
@@ -1118,20 +1137,7 @@ if ["probe", "serve", "validate", "swdecode", "extract", "audio", "customio"].co
     // being judged by ear.
     let serveAudioDelayMs = takeIntFlag("--audio-delay", from: &rest) ?? 0
     // #731: TrueHD Atmos or DTS:X rendered into a speaker bed and served as APAC (LoadOptions.objectAudioRendering).
-    let atmosBedFlag = takeStringFlag("--atmos-bed", from: &rest)
-    let serveObjectAudioRendering: ObjectAudioRendering
-    if let atmosBedFlag {
-        guard let layout = SpatialSpeakerLayout(rawValue: atmosBedFlag) else {
-            print("ERROR: --atmos-bed expects one of \(SpatialSpeakerLayout.allCases.map(\.rawValue)), got '\(atmosBedFlag)'")
-            exit(64)
-        }
-        serveObjectAudioRendering = .apac(layout)
-        #if !(TrueHDObjectAudio || DTSXObjectAudio)
-        print("[aetherctl] note: --atmos-bed renders nothing without the TrueHDObjectAudio / DTSXObjectAudio traits")
-        #endif
-    } else {
-        serveObjectAudioRendering = .off
-    }
+    let serveObjectAudioRendering = objectAudioRendering(takeStringFlag("--atmos-bed", from: &rest))
     rejectStrayFlags(rest, subcommand: first)
     guard let urlArg = rest.first else {
         print("ERROR: \(first) requires a <url> argument")
diff --git a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
index 3961f34f3..96722c8a9 100644
--- a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
@@ -640,6 +640,28 @@ struct BedLevelMeterTests {
         #expect(afterSeek.contains("; objects: up to 0 active, 0 elevated;"))
     }
 
+    @Test("the counts reach LiveTelemetry as they stand, with heights carried as bed channels")
+    func activityForTelemetry() {
+        var meter = BedLevelMeter(layout: .l714, sampleRate: 48_000)
+        #expect(meter.activity == ObjectAudioActivity(
+            layout: .l714, objects: 0, activeObjects: 0, elevatedObjects: 0, heightChannels: 0))
+        // DTS:X's standard presentation: its heights are bed channels, not objects.
+        meter.observe(roles: [.bed(.left), .bed(.right), .bed(.topFrontLeft), .bed(.topFrontRight)], updates: [])
+        #expect(meter.activity == ObjectAudioActivity(
+            layout: .l714, objects: 0, activeObjects: 0, elevatedObjects: 0, heightChannels: 2))
+        // TrueHD Atmos: an LFE and objects, one overhead, one at ear level, one muted.
+        meter.observe(roles: [.lfe, .object, .object, .object], updates: [ObjectAudioMetadataUpdate(
+            frameOffset: 0, rampFrames: 0, states: [
+                .init(), .init(position: SIMD3(0.5, 0.5, 1)), .init(position: SIMD3(0.5, 0.5, 0)), .init(gain: 0),
+            ])], configurationChanged: true)
+        #expect(meter.activity == ObjectAudioActivity(
+            layout: .l714, objects: 3, activeObjects: 2, elevatedObjects: 1, heightChannels: 0))
+        // A seek forgets which objects play until the decoder restates them; the configuration stays.
+        _ = meter.restart()
+        #expect(meter.activity.activeObjects == 0)
+        #expect(meter.activity.objects == 3)
+    }
+
     @Test("a configuration without objects does not keep reporting the previous configuration's objects")
     func countsResetOnConfigurationChange() throws {
         var meter = BedLevelMeter(layout: .l714, sampleRate: 48_000)
diff --git a/docs/api.md b/docs/api.md
index b4185278c..f15512449 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1248,6 +1248,7 @@ PiP/foreground eligibility and repair/resumption separately from optional decode
 | `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 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. |
+| `LiveTelemetry.objectAudio` | An `ObjectAudioActivity` while `objectAudioRendering` plays TrueHD Atmos or DTS:X, nil on every other audio path and always nil in a build without the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: the bed the presentation is rendered into (`layout`), the objects it declares (`objects`), how many of them its latest metadata update plays (`activeObjects`) and how many of those sit above ear level with elevation allowed (`elevatedObjects`), and its bed channels on height speakers (`heightChannels`, which is where DTS:X's standard presentation carries its four heights). Counted from the metadata, as the `bed levels` log line is: an active object can be silent, and an elevated one can snap to a floor speaker. A seek zeroes the playing counts until the decoder restates them. |
 | `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`. |
@@ -1357,6 +1358,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `ChapterInfo` | `id`, `name`, `startSeconds`, `durationSeconds`. The two publishers differ in axis: `discChapters` are title-relative and seeked through `selectChapter(id:)`, `mediaChapters` carry content timestamps a host passes straight to `seek(to:)` and `selectChapter` no-ops for them. |
 | `AudioTapBuffer` | `buffer` (`AVAudioPCMBuffer`), `sourceTime`, `discontinuity`. Non-discontinuity buffers are strictly increasing and non-overlapping, which is what SpeechAnalyzer's input timeline requires. |
 | `LiveTelemetry` | The 1 Hz snapshot: bitrates, observed fps, dropped frames, cache and network bytes, A/V gap, RSS. |
+| `ObjectAudioActivity` | `layout`, `objects`, `activeObjects`, `elevatedObjects`, `heightChannels`: what the object renderer is doing, as `LiveTelemetry.objectAudio`. |
 | `PlaybackErrorInfo` | `kind`, `underlyingDomain`, `underlyingCode`, `message`. Published as `$errorInfo` beside a `.error` state. |
 | `PlaybackErrorKind` | The stable token inside it: `.sourceOpenFailed`, `.sourceRefused` (the origin answered an HTTP status other than a rate limit instead of media; `underlyingCode` is the status), `.customSourceProbeFailed`, `.liveSourceUnavailable`, `.hlsPlaylistOnRawLivePath`, `.dolbyVisionRequiresHardware`, `.demuxedAudioLiveUnsupported`, `.nativeItemFailed`, `.noPlayableTrackWithinBudget`, `.masterPlaylistRejected`, `.vodSourceFailed`, `.sourceRateLimited`, `.softwarePipelineFailed`, `.audioSessionFailed`, `.reloadFailed`, `.liveReloadNeverReady`, `.audioTrackSwitchFailed`, `.audioBridgeProducedNoOutput`, `.storageExhausted`, `.sourceCertificateRejected` (the transport was refused over certificate trust; `underlyingCode` is the `NSURLErrorDomain` code, AE#495). `.sourceRateLimited` is the one to branch on separately: the source is being metered, not lost, so the same request is expected to work later and a handoff to a second player will meet the same refusal (AE#377). `.audioBridgeProducedNoOutput` is the other: a source whose audio has to be transcoded into fMP4 (MP3, MP2, DTS, TrueHD, Vorbis, PCM) produced no encoded audio at all, so the mp4 muxer could not build the sample entry it derives from a written packet (AE#396). It used to arrive as `.vodSourceFailed`, which reads as a dead source and ends a fallback ladder; the source is neither gone nor unreadable here, and a second player that decodes the track itself plays the file, so this is a DEMOTE, not a stop. `.storageExhausted` is neither: the volume holding the loopback segment cache (the temporary directory) filled up and no segment could be written (`underlyingCode` is `-28`, `AVERROR(ENOSPC)`), so the source, its audio and every other player are fine, and the same load succeeds once space is freed. It used to arrive as `.vodSourceFailed` or `.audioBridgeProducedNoOutput`. A string-backed struct rather than an enum, so a kind added in a minor release cannot break a host's switch; raw values are API and do not change. |
 | `DisplayCapabilities`, `StartupProgress`, `SeekEvent`, `PresentationAxisMap`, `NativeVideoFrameTime`, `SoftwareVideoFrameTime`, `SoftwarePiPSource`, `SystemCaptionRequest`, `AetherEngineError`, `HLSIngestError` | Covered in their sections above. |
diff --git a/docs/cli.md b/docs/cli.md
index 856871cd5..92a88539f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -107,6 +107,7 @@ swift run aetherctl play --live --dvr-window 1800 --audio-stats <url>
 swift run aetherctl play --live --native-hls <master.m3u8>      # nativeRemoteHLS bypass (carriage watchdog + #293 probe)
 swift run aetherctl play --sidecar de=/tmp/de.srt --subs de <master.m3u8>   # declare a sidecar at load (#316)
 swift run aetherctl play --native-hls --trust-any-certificate <https master.m3u8>  # the AE#495 origin relay
+swift run aetherctl play --atmos-bed 7.1.4 <truehd-atmos.mkv>  # render TrueHD Atmos or DTS:X into a bed as APAC (LoadOptions.objectAudioRendering); the 1 Hz line adds obj=<active>/<declared> up=<overhead> bed=<layout>, and hch=<n> for height channels
 swift run aetherctl play --fel <p7-file.mkv>                    # opt in to the Profile 7 FEL dual-layer route (off by default, like LoadOptions.preferDualLayerDolbyVision; --no-fel / --no-dual-layer are accepted and do nothing)
 swift run aetherctl play --fel --surface --cycle-el 10 <p7-file.mkv>   # flip the residual off and on every 10 s over a visible window (--window is the same flag)
 swift run aetherctl play --fel --surface --dv-pin 'darkest:240,period:2' <url>   # DEBUG: pulse a pinned frame's DV metadata (from dvsurvey)
diff --git a/docs/formats.md b/docs/formats.md
index 8337c94ca..7257a04a9 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -362,7 +362,9 @@ A linked peak limiter sits between the renderer and the encoder: the APAC encode
 
 **Cost.** Decoding the object presentation and encoding APAC each take about one core: on Dolby's Unfold demo (27 s, M1, release build) the TrueHD decode took 1.36 s (0.92 s since LibTrueHD 2.2.0, 0.60 s through its C API since 2.3.0), the APAC encode 1.26 s and rendering plus limiting 0.06 s. Apple's encoder runs on one thread, so the bridge hands each rendered 2048-frame chunk to a serial encode queue and decodes the next one meanwhile (`APACEncodePipeline`), which took the whole sample from 2.73 s to 1.75 s, and with LibTrueHD 2.2.0's faster decode to 1.40 s, 19x real time against 10x in series. The encoder is now the slower half, so the decoder no longer sets the pace. That time is what a seek past the produced range waits for before its first segment, so it is the one place the trade shows. The queue inherits the producer's QoS, a pool of three chunk buffers holds the producer at most two chunks ahead of the encoder, and the producer waits for the queue (`settle()`) before a keyframe advances its segment cutter or a write cuts the open segment, so every packet is routed as the encode in series routed it and every segment carries the same audio, byte for byte. Those waits cost about 0.1 s of the sample's overlap.
 
-**What the session log says.** `[SpatialAudioBridge] object configuration` names the presentation (`LFE + 15 objects` for Dolby's Unfold demo). A `bed levels` line gives each bed channel's RMS and peak with its CoreAudio name, how many objects were active and how many elevated, the LFE element's level and gain, and the limiter's work over the same window when it had any; it comes after the first 5 s of audio (and again after every seek), then every 30 s. The decoder waits for a major sync after a start or seek, so a decoder that returns nothing for 1200 packets in a row, a second of TrueHD, is reported as one that produces nothing, the same failure the channel bridge reports.
+**What the session log says.** `[SpatialAudioBridge] object configuration` names the presentation (`LFE + 15 objects` for Dolby's Unfold demo). A `bed levels` line gives each bed channel's RMS and peak with its CoreAudio name, how many objects were active and how many elevated, the LFE element's level and gain, and the limiter's work over the same window when it had any; it comes after the first 5 s of audio (and again after every seek), then every 30 s. The decoder waits for a major sync after a start or seek, so a decoder that returns nothing for 1200 packets in a row, a second of TrueHD, is reported as one that produces nothing, the same failure the channel bridge reports. The object
+counts reach a host too, once a second, as `LiveTelemetry.objectAudio`, so a stats panel can say how
+many objects play and how many overhead without reading the log.
 
 ### DTS\:X with heights
 

From bb351047bca011d44321d46d7145bcc0d5a6c658 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 15:16:24 +0200
Subject: [PATCH 117/132] fix(relay): admit only http and https origins

A playlist can name any scheme, and URLSession reads file://localhost/...
from the sandbox. The relay's pump already cancelled any answer that is
not an HTTPURLResponse, so such a URI ended as a 502 rather than being
served, but that was a side effect. Admission now refuses every scheme
but http and https, and a request naming one answers 404.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Network/HLSOriginRelay.swift | 10 ++++---
 .../HLSOriginRelayTests.swift                 | 27 +++++++++++++++++++
 2 files changed, 34 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index a559c6185..69f6f1d7e 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -193,10 +193,14 @@ final class HLSOriginRelay: @unchecked Sendable {
     }
 
     /// scheme://host:port for `url`, which is the granularity the allow list works at.
+    ///
+    /// Nil for anything but http and https. A playlist can name any scheme, and URLSession reads
+    /// `file://localhost/...` from the sandbox; the pump's HTTP-only head was the only thing that
+    /// kept such a URI from being served, so admission refuses it outright instead.
     static func originKey(for url: URL) -> String? {
-        guard let scheme = url.scheme?.lowercased(), let host = url.host?.lowercased() else {
-            return nil
-        }
+        guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https",
+            let host = url.host?.lowercased()
+        else { return nil }
         if let port = url.port { return "\(scheme)://\(host):\(port)" }
         return "\(scheme)://\(host)"
     }
diff --git a/Tests/AetherEngineTests/HLSOriginRelayTests.swift b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
index 0f5816147..5d217122f 100644
--- a/Tests/AetherEngineTests/HLSOriginRelayTests.swift
+++ b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
@@ -86,6 +86,33 @@ struct HLSOriginRelayAddressingTests {
         #expect(HLSOriginRelay.originKey(for: URL(string: "https://a.example.com:8920/x")!) == "https://a.example.com:8920")
         #expect(HLSOriginRelay.originKey(for: URL(string: "http://a.example.com/x")!) == "http://a.example.com")
         #expect(HLSOriginRelay.originKey(for: URL(string: "file:///tmp/x")!) == nil)
+        #expect(HLSOriginRelay.originKey(for: URL(string: "file://localhost/tmp/x")!) == nil)
+        #expect(HLSOriginRelay.originKey(for: URL(string: "ftp://a.example.com/x")!) == nil)
+        #expect(HLSOriginRelay.originKey(for: URL(string: "HTTPS://a.example.com/x")!) == "https://a.example.com")
+    }
+
+    @Test("A playlist that names a local file gets no byte of it back")
+    func playlistNamedFileIsRefused() async throws {
+        let file = FileManager.default.temporaryDirectory
+            .appendingPathComponent("relay-file-\(UUID().uuidString).ts")
+        try Data("sandbox bytes".utf8).write(to: file)
+        defer { try? FileManager.default.removeItem(at: file) }
+        let named = try #require(URL(string: "file://localhost\(file.path)"))
+
+        let relay = HLSOriginRelay()
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+        let origin = URL(string: "https://127.0.0.1:9/hls/media.m3u8")!
+        relay.grantCredentials(to: origin)
+
+        _ = relay.rewritePlaylist(
+            "#EXTM3U\n#EXTINF:6.0,\n\(named.absoluteString)\n", relativeTo: origin,
+            port: server.port, token: server.pathToken)
+
+        let local = try #require(relay.localURL(
+            for: named, port: server.port, token: server.pathToken))
+        #expect(try await status(of: local) == 404)
     }
 
     @Test("Sub-resources follow the address the request arrived on")

From c7eedf7e88ef07fc647dcdf5fd5ccd224c73dc78 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 16:04:29 +0200
Subject: [PATCH 118/132] fix(hls): stream segment bodies on the persistent
 HTTP/1.1 ingest, no 45 s exchange ceiling (#732)

Under heldSourceConnection the HEVC-in-MPEG-TS VOD ingest downloaded every
segment whole before the demuxer saw a byte, its carriage probe downloaded
segment 0 whole, and one 45 s deadline covered head and body together. On a
slow origin a large segment could not finish inside it, and the expiry
surfaced as the socket's own POSIX timeout (Code=60), naming neither cause.

- PersistentHTTP1Transport.open returns the response head and a Body read
  piece by piece; get() is open plus collect.
- The 45 s ceiling covers only the wait for a response head. A body ends on
  its size limit or on 30 s without a byte (typed .stalled with
  received/expected bytes and elapsed time).
- One request per origin at a time: checkOut claims the origin and the next
  request waits for the connection to be pooled or closed, so a seek never
  opens a second connection beside a response still in flight.
- An abandoned body with at most 2 MB left drains for up to 3 s and keeps
  its socket; a larger remainder closes it.
- The probe reads the head and hands the open response to the producer.
- With the FIFO full the current segment is read to its end, so a pause
  idles the connection between requests, not mid-body.
- The h2 path's 45 s resource timeout is lifted the same way.

Measured on a loopback keep-alive origin at 200 KB/s with 11.6 MB segments:
before, the probe died at 45.1 s with Code=60 and the session left the
ingest; after, the ingest held and played.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  15 +
 .../IO/HLSIngest/HLSVODIngestReader.swift     | 156 +++-
 .../HLSIngest/PersistentHTTP1Transport.swift  | 670 +++++++++++++-----
 .../Issue732PersistentHTTP1Tests.swift        | 210 +++++-
 docs/api.md                                   |   2 +-
 docs/cli.md                                   |   7 +-
 6 files changed, 845 insertions(+), 215 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3cb82879f..f2fce29b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -82,6 +82,21 @@ third-party patent licensing; integrators who enable them are responsible for th
 
 ### Fixed
 
+- **The HEVC-in-MPEG-TS HLS VOD ingest under `heldSourceConnection` no longer fails on a slow origin.**
+  A segment body now reaches the demuxer as it arrives instead of after its last byte, the carriage
+  probe reads the first segment's head and hands the still open response to the producer instead of
+  downloading it whole, and the 45 s ceiling on a whole exchange is gone: it now covers only the wait
+  for a response head, and a body is limited by its size and by 30 s without a byte, so a large
+  segment that keeps arriving is never cut off. That ceiling surfaced as `NSPOSIXErrorDomain Code=60`,
+  which named neither cause; a stall now says `body stalled, no bytes for 30 s after <received>/<expected>
+  bytes in <elapsed> s`. A seek that abandons a body with at most 2 MB left drains it for up to 3 s and
+  keeps the connection, and the next request waits for that instead of opening a second connection
+  beside it; a larger remainder still closes it. With the FIFO full the current segment is read to its
+  end, so a paused session leaves the connection idle between two requests, not mid-body. Measured on a
+  loopback origin at 200 KB/s with 11.6 MB segments: before, the probe died at 45.1 s with `Code=60` and
+  the session left the ingest; after, the ingest held and played. The h2 path's 45 s resource timeout
+  is lifted the same way (#732, thanks @qoli for the paired device runs).
+
 - **The package compiles in Release with Xcode 26 again.** `FelResidualMeasure` (the
   `AETHER_FEL_MEASURE` diagnostic from 7.37.0) formatted its luma-band line inside the closure it
   hands its queue, as one `+` chain of three `map`/`joined` expressions, and Xcode 26.3's type checker
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index 4c19e3d09..c6ab47c6d 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -32,9 +32,16 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
     /// AE#732: set under `LoadOptions.heldSourceConnection`. Every request of this reader then goes over
     /// one persistent HTTP/1.1 connection per origin, segments one at a time, instead of `session`.
     private let transport: PersistentHTTP1Transport?
-    /// AE#732: the first segment, downloaded whole by the carriage probe on the persistent path (a probe
-    /// that stopped mid-body would cost the connection), handed to the producer that starts there.
-    private var primedSegment: (url: URL, bytes: Data)?
+    /// AE#732: the first segment as the carriage probe left it on the persistent path, its head read and
+    /// the rest of the response still open, so the producer that starts there carries on with the same
+    /// response instead of asking for the segment again.
+    private var primedSegment: PrimedSegment?
+
+    private struct PrimedSegment {
+        let url: URL
+        let head: Data
+        let body: PersistentHTTP1Transport.Body
+    }
     private let condition = NSCondition()
     private let keyCacheLock = NSLock()
     private var keyCache: [String: Data] = [:]
@@ -68,8 +75,10 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
             ownsSession = false
         } else {
             let configuration = URLSessionConfiguration.ephemeral
+            // The request timeout is the idle one, the longest wait for the next byte. No resource
+            // ceiling: a large segment from a slow origin that keeps arriving is never cut off (#732).
             configuration.timeoutIntervalForRequest = 15
-            configuration.timeoutIntervalForResource = 45
+            configuration.timeoutIntervalForResource = .greatestFiniteMagnitude
             configuration.requestCachePolicy = .reloadIgnoringLocalAndRemoteCacheData
             configuration.urlCache = nil
             self.session = URLSession(
@@ -277,11 +286,14 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         closed = true
         let task = producer
         producer = nil
+        let primed = primedSegment
+        primedSegment = nil
         queue.removeAll()
         bufferedBytes = 0
         condition.broadcast()
         condition.unlock()
         task?.cancel()
+        primed?.body.abandon()
         transport?.close()
         if ownsSession {
             session.invalidateAndCancel()
@@ -443,32 +455,117 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
 
     /// AE#732: one segment at a time, so the persistent connection carries them back to back. The FIFO
     /// is the read-ahead; a parallel window would need a connection per in-flight segment, and a second
-    /// connection is what the origins this path exists for refuse.
+    /// connection is what the origins this path exists for refuse. Each body goes into the FIFO as it
+    /// arrives, so a slow segment feeds the demuxer while it downloads.
     private func ingestSequentially(
         _ segments: [(HLSMediaSegment, URL)],
         mediaURL: URL,
         generation: UInt64
     ) async throws {
-        let primed = condition.withLock { () -> (url: URL, bytes: Data)? in
+        var primed = condition.withLock { () -> PrimedSegment? in
             defer { primedSegment = nil }
             return primedSegment
         }
+        defer { primed?.body.abandon() }
         for (offset, (segment, url)) in segments.enumerated() {
             try Task.checkCancellation()
-            var bytes: Data
-            if offset == 0, let primed, primed.url == url {
-                bytes = primed.bytes
-            } else {
-                bytes = try await fetch(url, limit: BoundedFetch.segmentLimit(forDuration: segment.duration))
-            }
             if let crypt = segment.crypt {
-                bytes = try await decrypt(bytes, crypt: crypt, baseURL: mediaURL)
+                let bytes = try await decrypt(
+                    try await fetch(url, limit: BoundedFetch.segmentLimit(forDuration: segment.duration)),
+                    crypt: crypt, baseURL: mediaURL)
+                if offset == 0, LiveSegmentFormat.classify(bytes) != .mpegts {
+                    throw HLSIngestError.unsupportedSegmentFormat
+                }
+                guard append(bytes, generation: generation) else { return }
+                continue
+            }
+            let head: Data
+            let body: PersistentHTTP1Transport.Body
+            if offset == 0, let ready = primed, ready.url == url {
+                (head, body) = (ready.head, ready.body)
+                primed = nil
+            } else {
+                primed?.body.abandon()
+                primed = nil
+                body = try await openSegment(url, limit: BoundedFetch.segmentLimit(forDuration: segment.duration))
+                head = Data()
             }
-            if offset == 0, LiveSegmentFormat.classify(bytes) != .mpegts {
-                throw HLSIngestError.unsupportedSegmentFormat
+            guard try await stream(head: head, body: body, checkCarriage: offset == 0, generation: generation)
+            else { return }
+        }
+    }
+
+    /// Copies one segment body into the FIFO as it arrives. False when the generation was superseded;
+    /// the body is then abandoned, which drains or closes its connection.
+    ///
+    /// The FIFO's backpressure applies between segments, never inside one: with the FIFO full the rest
+    /// of the segment is read on into `pending` (one segment over the ceiling, as a whole-segment fetch
+    /// held), so a paused player leaves the connection idle between two requests, where keep-alive
+    /// expiry costs one retry, rather than mid-body, where an origin's send timeout costs the session.
+    private func stream(
+        head: Data, body: PersistentHTTP1Transport.Body, checkCarriage: Bool, generation: UInt64
+    ) async throws -> Bool {
+        var pending = head
+        var checked = !checkCarriage
+        var total = head.count
+        do {
+            while true {
+                let chunk = try await body.next()
+                if let chunk {
+                    pending.append(chunk)
+                    total += chunk.count
+                }
+                if !checked, chunk == nil || !pending.isEmpty {
+                    guard LiveSegmentFormat.classify(pending) == .mpegts else {
+                        body.abandon()
+                        throw HLSIngestError.unsupportedSegmentFormat
+                    }
+                    checked = true
+                }
+                if chunk == nil { break }
+                guard !pending.isEmpty else { continue }
+                switch offer(pending, generation: generation) {
+                case .taken: pending = Data()
+                case .full: continue
+                case .superseded:
+                    body.abandon()
+                    return false
+                }
             }
-            guard append(bytes, generation: generation) else { return }
+        } catch is BoundedFetch.Exceeded {
+            throw HLSIngestError.playlistInvalid(reason: "segment body over its limit")
         }
+        guard total > 0 else { throw HLSIngestError.playlistUnreachable(status: body.response.statusCode) }
+        return pending.isEmpty || append(pending, generation: generation)
+    }
+
+    private enum Offer { case taken, full, superseded }
+
+    /// `append` without the wait: a full FIFO answers `.full` and leaves the bytes with the caller.
+    private func offer(_ data: Data, generation: UInt64) -> Offer {
+        condition.withLock {
+            guard self.generation == generation, !closed else { return .superseded }
+            guard bufferedBytes < Self.maximumBufferedBytes else { return .full }
+            queue.append(data)
+            bufferedBytes += data.count
+            condition.broadcast()
+            return .taken
+        }
+    }
+
+    /// A segment's response with its status checked; the body is still to be read.
+    private func openSegment(_ url: URL, limit: Int) async throws -> PersistentHTTP1Transport.Body {
+        guard let transport else { throw CancellationError() }
+        let body: PersistentHTTP1Transport.Body
+        do {
+            body = try await transport.open(url, headers: scopedHeaders(url), limit: limit)
+        } catch is BoundedFetch.Exceeded {
+            throw HLSIngestError.playlistInvalid(reason: "body exceeds \(limit) bytes")
+        }
+        guard (200..<300).contains(body.response.statusCode) else {
+            throw HLSIngestError.playlistUnreachable(status: body.response.statusCode)
+        }
+        return body
     }
 
     private func append(_ data: Data, generation: UInt64) -> Bool {
@@ -621,11 +718,30 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         _ url: URL, duration: Double
     ) async throws -> MPEGTransportStreamCodecProbe.Verdict {
         if transport != nil {
-            let bytes = try await fetch(url, limit: BoundedFetch.segmentLimit(forDuration: duration))
-            let verdict = MPEGTransportStreamCodecProbe.classify(
-                bytes.prefix(HLSCarriageProbe.maximumSegmentHeadBytes))
+            // The probe reads the head and leaves the response open: stopping the body here would
+            // cost the connection, and reading it whole delays the start by the whole segment.
+            let body = try await openSegment(url, limit: BoundedFetch.segmentLimit(forDuration: duration))
+            var head = Data()
+            var verdict = MPEGTransportStreamCodecProbe.Verdict.inconclusive
+            do {
+                while head.count < HLSCarriageProbe.maximumSegmentHeadBytes, let chunk = try await body.next() {
+                    head.append(chunk)
+                    verdict = MPEGTransportStreamCodecProbe.classify(head.prefix(HLSCarriageProbe.maximumSegmentHeadBytes))
+                    if verdict != .inconclusive { break }
+                }
+            } catch {
+                body.abandon()
+                throw error
+            }
+            guard !head.isEmpty else { throw HLSIngestError.unsupportedSegmentFormat }
             if verdict == .hevcInMPEGTS {
-                condition.withLock { primedSegment = (url, bytes) }
+                let displaced = condition.withLock { () -> PrimedSegment? in
+                    defer { primedSegment = PrimedSegment(url: url, head: head, body: body) }
+                    return primedSegment
+                }
+                displaced?.body.abandon()
+            } else {
+                body.abandon()
             }
             return verdict
         }
diff --git a/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift b/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift
index b3caa284e..0189b09c9 100644
--- a/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift
@@ -9,153 +9,223 @@ import Foundation
 /// `HeldSourceConnection` (#377) and shares its wire format: HTTP/1.1 written by the engine over a
 /// `URLSessionStreamTask`, TLS through `EngineTLS`, no ALPN and so never h2, no system proxy.
 ///
-/// Requests run one after another over the idle connection of their origin (scheme, host, port). A
-/// connection goes back to the pool only after a complete response it can be reused for: HTTP/1.1,
-/// no `Connection: close`, and a body with a known end. Everything else, an error, a cancellation
-/// mid-body or a body cut off at its limit, closes it, and the next request opens a fresh one.
-/// Concurrent callers each get their own connection; the ingest issues one request at a time on this
-/// path, so that only happens for the moment a seek takes to retire the previous producer.
+/// One request per origin (scheme, host, port) at a time: a request claims its origin's connection
+/// and the next one waits until that connection is back in the pool or closed. A successful body is
+/// handed to the caller as it arrives (`Body`), so a slow segment feeds the demuxer while it
+/// downloads instead of after. A connection goes back to the pool only after a complete response it
+/// can be reused for: HTTP/1.1, no `Connection: close`, and a body with a known end. A body its
+/// caller abandons (a seek) is drained when little of it is left, inside `maxDrainBytes` and
+/// `drainDeadline`, so the next request can still ride the same socket; a larger remainder closes it.
 final class PersistentHTTP1Transport: @unchecked Sendable {
     static let maxRedirects = 3
     /// Idle connections kept, one per origin. A segment redirected to a CDN host keeps both the
     /// playlist origin and the CDN connection warm.
     private static let maxIdleOrigins = 2
+    /// An abandoned body with more than this left closes its connection instead of draining it.
+    static let maxDrainBytes: Int64 = 2 * 1024 * 1024
+    /// How long a drain may hold up the next request before its connection is closed instead.
+    static let drainDeadline: TimeInterval = 3
 
     struct Response {
         let body: Data
         let response: HTTPURLResponse
     }
 
-    private let label: String
+    /// The origin's connection while a request or its body is out, and who waits for it.
+    private struct Claim {
+        var connection: PersistentHTTP1Connection?
+        var waiters: [CheckedContinuation<Void, Never>] = []
+    }
+
+    let label: String
+    private let readTimeout: TimeInterval
     private let lock = NSLock()
     private var idle: [Origin: PersistentHTTP1Connection] = [:]
+    private var claims: [Origin: Claim] = [:]
     private var closed = false
     private var nextConnectionID = 0
 
-    init(label: String) {
+    init(label: String, readTimeout: TimeInterval = PersistentHTTP1Connection.defaultReadTimeout) {
         self.label = label
+        self.readTimeout = readTimeout
     }
 
-    /// GET `url` with `headers`, redirects followed under the #126 header policy. A non-2xx answer
-    /// comes back with its status and whatever body it had, read to its end so the connection stays
-    /// usable. Throws `BoundedFetch.Exceeded` for a 2xx body over `limit`.
+    /// GET `url` with `headers`, redirects followed under the #126 header policy, the whole body
+    /// collected. A non-2xx answer comes back with its status and an empty body. Throws
+    /// `BoundedFetch.Exceeded` for a 2xx body over `limit`.
     func get(_ url: URL, headers: [String: String], limit: Int) async throws -> Response {
+        let body = try await open(url, headers: headers, limit: limit)
+        var data = Data()
+        while let chunk = try await body.next() {
+            data.append(chunk)
+        }
+        return Response(body: data, response: body.response)
+    }
+
+    /// GET `url` and return as soon as the response head is in. A 2xx body is read through the
+    /// returned `Body`, which holds the origin until it ends or is abandoned; every other answer has
+    /// been read to its end already and its `Body` is empty.
+    func open(_ url: URL, headers: [String: String], limit: Int) async throws -> Body {
         var target = url
         var hops = 0
         while true {
             let hopHeaders = RedirectHeaderPolicy.headersToReplay(
                 extraHeaders: headers, originalURL: url, redirectURL: target)
-            let (head, body) = try await exchange(target, headers: hopHeaders, limit: limit)
-            if let location = HeldSourceConnection.redirectLocation(head) {
-                guard hops < Self.maxRedirects else {
-                    throw PersistentHTTP1Connection.ConnectionError.tooManyRedirects
+            let (connection, head, reused) = try await request(target, headers: hopHeaders)
+            let success = (200..<300).contains(head.status)
+            let location = HeldSourceConnection.redirectLocation(head)
+            guard let response = HeldSourceConnection.makeResponse(head, url: target) else {
+                release(connection, refusal: "status \(head.status)")
+                throw PersistentHTTP1Connection.ConnectionError.malformed("status \(head.status)")
+            }
+            if !success || location != nil {
+                let refusal: String?
+                do {
+                    refusal = try await connection.discardBody(head)
+                } catch {
+                    release(connection, refusal: Task.isCancelled ? "cancelled" : EngineLog.summary(of: error))
+                    throw error
                 }
-                guard let next = URL(string: location, relativeTo: target)?.absoluteURL else {
-                    throw PersistentHTTP1Connection.ConnectionError.malformed("unresolvable Location: \(location)")
+                release(connection, refusal: refusal)
+                if let location {
+                    guard hops < Self.maxRedirects else {
+                        throw PersistentHTTP1Connection.ConnectionError.tooManyRedirects
+                    }
+                    guard let next = URL(string: location, relativeTo: target)?.absoluteURL else {
+                        throw PersistentHTTP1Connection.ConnectionError.malformed("unresolvable Location: \(location)")
+                    }
+                    hops += 1
+                    target = next
+                    continue
                 }
-                hops += 1
-                target = next
-                continue
+                return Body(finished: response)
             }
-            guard let response = HeldSourceConnection.makeResponse(head, url: target) else {
-                throw PersistentHTTP1Connection.ConnectionError.malformed("status \(head.status)")
+            let framing = PersistentHTTP1Connection.framing(for: head)
+            if case .identity(let length) = framing, length > Int64(limit) {
+                release(connection, refusal: "body of \(length) bytes over the \(limit) byte limit")
+                throw BoundedFetch.Exceeded(limit: limit)
             }
-            return Response(body: body, response: response)
+            return Body(
+                transport: self, connection: connection, head: head, response: response,
+                framing: framing, limit: limit, reused: reused)
         }
     }
 
-    /// Closes every idle connection and refuses further requests.
+    /// Closes every connection, idle or out, and refuses further requests.
     func close() {
         lock.lock()
         closed = true
-        let connections = Array(idle.values)
+        let connections = Array(idle.values) + claims.values.compactMap(\.connection)
+        let waiters = claims.values.flatMap(\.waiters)
         idle.removeAll()
+        claims.removeAll()
         lock.unlock()
         for connection in connections { connection.retire(reason: "transport closed") }
+        for waiter in waiters { waiter.resume() }
     }
 
-    /// One request and its response on a pooled connection. A REUSED connection that fails before a
-    /// response head is retried once on a fresh one: an origin may close an idle keep-alive connection
-    /// at any time, and the request on it never reached anyone (RFC 9112 9.3.1).
-    private func exchange(
-        _ target: URL, headers: [String: String], limit: Int
-    ) async throws -> (HeldSourceConnection.ResponseHead, Data) {
+    /// Sends one request and reads its response head on a pooled connection. A REUSED connection that
+    /// fails before a response head is retried once on a fresh one: an origin may close an idle
+    /// keep-alive connection at any time, and the request on it never reached anyone (RFC 9112 9.3.1).
+    private func request(
+        _ target: URL, headers: [String: String]
+    ) async throws -> (PersistentHTTP1Connection, HeldSourceConnection.ResponseHead, Bool) {
         guard let origin = Origin(target) else {
             throw PersistentHTTP1Connection.ConnectionError.unsupportedURL(target)
         }
-        var connection = try checkOut(origin)
+        var connection = try await checkOut(origin)
         do {
-            return try await run(connection, target: target, headers: headers, limit: limit)
+            return (connection, try await connection.sendRequest(target: target, headers: headers), connection.requestCount > 1)
         } catch PersistentHTTP1Connection.ConnectionError.staleKeepAlive where connection.requestCount > 1 {
-            try Task.checkCancellation()
-            connection = try openFresh(origin)
-            return try await run(connection, target: target, headers: headers, limit: limit)
-        }
-    }
-
-    private func run(
-        _ connection: PersistentHTTP1Connection,
-        target: URL, headers: [String: String], limit: Int
-    ) async throws -> (HeldSourceConnection.ResponseHead, Data) {
-        let outcome: PersistentHTTP1Connection.Outcome
-        do {
-            outcome = try await connection.send(target: target, headers: headers, limit: limit)
+            connection.retire(reason: "stale keep-alive")
+            do {
+                try Task.checkCancellation()
+                connection = try openFresh(origin)
+                replaceClaim(origin, with: connection)
+                return (connection, try await connection.sendRequest(target: target, headers: headers), false)
+            } catch {
+                release(connection, refusal: Task.isCancelled ? "cancelled" : EngineLog.summary(of: error))
+                throw error
+            }
         } catch {
-            connection.retire(reason: Task.isCancelled ? "cancelled" : EngineLog.summary(of: error))
+            release(connection, refusal: Task.isCancelled ? "cancelled" : EngineLog.summary(of: error))
             throw error
         }
-        if let reason = outcome.notReusableBecause {
-            connection.retire(reason: reason)
-        } else {
-            checkIn(connection)
-        }
-        return (outcome.head, outcome.body)
     }
 
-    private func checkOut(_ origin: Origin) throws -> PersistentHTTP1Connection {
-        lock.lock()
-        if closed {
-            lock.unlock()
-            throw CancellationError()
+    /// Claims `origin` and returns its idle connection or a fresh one. While another request holds the
+    /// origin, waits for it: a second connection beside a response still in flight is the pattern the
+    /// origins this path exists for refuse. A body holds it no longer than its next stall, its drain
+    /// deadline or its end.
+    private func checkOut(_ origin: Origin) async throws -> PersistentHTTP1Connection {
+        while true {
+            if let connection = try claim(origin) { return connection }
+            await withCheckedContinuation { (waiter: CheckedContinuation<Void, Never>) in
+                let parked = lock.withLock { () -> Bool in
+                    guard !closed, claims[origin] != nil else { return false }
+                    claims[origin]?.waiters.append(waiter)
+                    return true
+                }
+                if !parked { waiter.resume() }
+            }
         }
-        if let pooled = idle.removeValue(forKey: origin) {
-            lock.unlock()
-            return pooled
+    }
+
+    /// The claimed connection, nil while another request holds `origin`.
+    private func claim(_ origin: Origin) throws -> PersistentHTTP1Connection? {
+        try lock.withLock { () -> PersistentHTTP1Connection? in
+            if closed { throw CancellationError() }
+            guard claims[origin] == nil else { return nil }
+            let connection = idle.removeValue(forKey: origin) ?? makeConnection(origin)
+            claims[origin] = Claim(connection: connection)
+            return connection
         }
-        lock.unlock()
-        return try openFresh(origin)
     }
 
     private func openFresh(_ origin: Origin) throws -> PersistentHTTP1Connection {
-        lock.lock()
-        if closed {
-            lock.unlock()
-            throw CancellationError()
+        try lock.withLock {
+            if closed { throw CancellationError() }
+            return makeConnection(origin)
         }
+    }
+
+    /// Under `lock`.
+    private func makeConnection(_ origin: Origin) -> PersistentHTTP1Connection {
         nextConnectionID += 1
-        let id = nextConnectionID
-        lock.unlock()
-        return PersistentHTTP1Connection(origin: origin, label: "\(label)#\(id)")
+        return PersistentHTTP1Connection(
+            origin: origin, label: "\(label)#\(nextConnectionID)", readTimeout: readTimeout)
+    }
+
+    private func replaceClaim(_ origin: Origin, with connection: PersistentHTTP1Connection) {
+        lock.withLock { claims[origin]?.connection = connection }
     }
 
-    private func checkIn(_ connection: PersistentHTTP1Connection) {
+    /// Ends the claim `connection` holds: back to the pool when `refusal` is nil, closed otherwise,
+    /// and the next waiting request goes ahead. Idempotent.
+    fileprivate func release(_ connection: PersistentHTTP1Connection, refusal: String?) {
         lock.lock()
-        if closed {
-            lock.unlock()
-            connection.retire(reason: "transport closed")
-            return
+        var waiters: [CheckedContinuation<Void, Never>] = []
+        if let claim = claims[connection.origin], claim.connection === connection {
+            claims.removeValue(forKey: connection.origin)
+            waiters = claim.waiters
         }
         var evicted: [PersistentHTTP1Connection] = []
-        if let previous = idle[connection.origin] { evicted.append(previous) }
-        idle[connection.origin] = connection
-        if idle.count > Self.maxIdleOrigins,
-           let oldest = idle.filter({ $0.key != connection.origin })
-            .min(by: { $0.value.lastUsed < $1.value.lastUsed }) {
-            idle.removeValue(forKey: oldest.key)
-            evicted.append(oldest.value)
+        var pooled = false
+        if refusal == nil, !closed, !connection.isRetired {
+            if let previous = idle[connection.origin], previous !== connection { evicted.append(previous) }
+            idle[connection.origin] = connection
+            pooled = true
+            if idle.count > Self.maxIdleOrigins,
+               let oldest = idle.filter({ $0.key != connection.origin })
+                .min(by: { $0.value.lastUsed < $1.value.lastUsed }) {
+                idle.removeValue(forKey: oldest.key)
+                evicted.append(oldest.value)
+            }
         }
         lock.unlock()
+        if !pooled { connection.retire(reason: refusal ?? "transport closed") }
         for stale in evicted { stale.retire(reason: "origin change") }
+        for waiter in waiters { waiter.resume() }
     }
 
     struct Origin: Hashable, CustomStringConvertible {
@@ -174,15 +244,228 @@ final class PersistentHTTP1Transport: @unchecked Sendable {
 
         var description: String { "\(secure ? "https" : "http")://\(host):\(port)" }
     }
+
+    /// A 2xx body, read in the pieces the socket delivers. One consumer at a time. Its end returns the
+    /// connection to the pool; `abandon()`, or cancelling the task inside `next()`, drains or closes it.
+    final class Body: @unchecked Sendable {
+        let response: HTTPURLResponse
+        /// `Content-Length`, nil for a chunked or close-framed body.
+        let expectedLength: Int64?
+
+        private let transport: PersistentHTTP1Transport?
+        private let connection: PersistentHTTP1Connection?
+        private let head: HeldSourceConnection.ResponseHead?
+        private let limit: Int
+        private let reused: Bool
+        private let started = Date()
+        private let lock = NSLock()
+        private var framing: PersistentHTTP1Connection.Framing
+        private var received: Int64 = 0
+        private var reading = false
+        private var abandoned = false
+        /// Set once the claim is released, by whichever path ends the body first.
+        private var released = false
+
+        fileprivate init(finished response: HTTPURLResponse) {
+            self.response = response
+            expectedLength = 0
+            transport = nil
+            connection = nil
+            head = nil
+            limit = 0
+            reused = false
+            framing = .empty
+            released = true
+        }
+
+        fileprivate init(
+            transport: PersistentHTTP1Transport,
+            connection: PersistentHTTP1Connection,
+            head: HeldSourceConnection.ResponseHead,
+            response: HTTPURLResponse,
+            framing: PersistentHTTP1Connection.Framing,
+            limit: Int,
+            reused: Bool
+        ) {
+            self.transport = transport
+            self.connection = connection
+            self.head = head
+            self.response = response
+            self.framing = framing
+            self.limit = limit
+            self.reused = reused
+            if case .identity(let length) = framing { expectedLength = length } else { expectedLength = nil }
+        }
+
+        deinit {
+            // A body dropped unread must not hold its origin.
+            finish(refusal: "body dropped mid-read")
+        }
+
+        /// The next piece of the body, nil at its end.
+        func next() async throws -> Data? {
+            guard let connection else { return nil }
+            let current = lock.withLock { () -> PersistentHTTP1Connection.Framing? in
+                guard !released, !abandoned else { return nil }
+                reading = true
+                return framing
+            }
+            guard let current else {
+                if lock.withLock({ abandoned }) { throw CancellationError() }
+                return nil
+            }
+            if Task.isCancelled {
+                lock.withLock { reading = false }
+                abandon()
+                throw CancellationError()
+            }
+            let chunk: Data?
+            let advanced: PersistentHTTP1Connection.Framing
+            do {
+                (chunk, advanced) = try await withTaskCancellationHandler {
+                    try await connection.readChunk(current, progress: progress)
+                } onCancel: {
+                    self.abandon()
+                }
+            } catch {
+                let wasAbandoned = lock.withLock { () -> Bool in
+                    reading = false
+                    return abandoned
+                }
+                finish(refusal: (wasAbandoned ? "drain failed: " : "") + EngineLog.summary(of: error))
+                if wasAbandoned { throw CancellationError() }
+                throw error
+            }
+            enum Step { case deliver, end, overLimit, drain }
+            let step = lock.withLock { () -> Step in
+                reading = false
+                framing = advanced
+                if let chunk { received += Int64(chunk.count) }
+                if abandoned { return .drain }
+                if chunk == nil { return .end }
+                if received > Int64(limit) { return .overLimit }
+                return .deliver
+            }
+            switch step {
+            case .deliver:
+                return chunk
+            case .end:
+                let refusal = head.flatMap { PersistentHTTP1Connection.reuseRefusal($0, advanced) }
+                EngineLog.emit(
+                    "[HLSVODIngest] AE#732 connection \(connection.label) request \(connection.requestCount) "
+                        + "status=\(response.statusCode) \(progress()) \(reused ? "reused" : "fresh")"
+                        + (refusal.map { ", not reusable: \($0)" } ?? ""),
+                    category: .engine, level: .verbose)
+                finish(refusal: refusal)
+                return nil
+            case .overLimit:
+                finish(refusal: "body over the \(limit) byte limit")
+                throw BoundedFetch.Exceeded(limit: limit)
+            case .drain:
+                // The read in flight when the body was abandoned is back; the drain goes on from
+                // here, off the caller's task.
+                if chunk == nil {
+                    finish(refusal: head.flatMap { PersistentHTTP1Connection.reuseRefusal($0, advanced) }, drained: true)
+                } else {
+                    Task { await self.drain() }
+                }
+                throw CancellationError()
+            }
+        }
+
+        /// Stops reading. Little left: drained in the background, the connection kept, and the next
+        /// request to this origin waits for it. Otherwise the connection is closed. Idempotent.
+        func abandon() {
+            guard let connection else { return }
+            let decision = lock.withLock { () -> (inFlight: Bool, drainable: Bool)? in
+                guard !released, !abandoned else { return nil }
+                abandoned = true
+                switch framing {
+                case .identity(let remaining): return (reading, remaining <= PersistentHTTP1Transport.maxDrainBytes)
+                case .chunked, .empty: return (reading, true)
+                case .untilClose: return (reading, false)
+                }
+            }
+            guard let decision else { return }
+            guard decision.drainable else {
+                finish(refusal: "abandoned mid-body, \(progress())")
+                return
+            }
+            EngineLog.emit(
+                "[HLSVODIngest] AE#732 connection \(connection.label) draining abandoned body, \(progress())",
+                category: .engine)
+            Task {
+                try? await Task.sleep(nanoseconds: UInt64(PersistentHTTP1Transport.drainDeadline * 1_000_000_000))
+                self.finish(refusal: "drain not done within \(Int(PersistentHTTP1Transport.drainDeadline)) s, \(self.progress())")
+            }
+            if !decision.inFlight {
+                Task { await self.drain() }
+            }
+        }
+
+        private func drain() async {
+            guard let connection else { return }
+            var drained: Int64 = 0
+            while let current = lock.withLock({ released ? nil : framing }) {
+                do {
+                    let (chunk, advanced) = try await connection.readChunk(current, progress: progress)
+                    lock.withLock { framing = advanced }
+                    guard let chunk else {
+                        finish(refusal: head.flatMap { PersistentHTTP1Connection.reuseRefusal($0, advanced) }, drained: true)
+                        return
+                    }
+                    drained += Int64(chunk.count)
+                    if drained > PersistentHTTP1Transport.maxDrainBytes {
+                        finish(refusal: "drain over \(PersistentHTTP1Transport.maxDrainBytes) bytes")
+                        return
+                    }
+                } catch {
+                    finish(refusal: "drain failed: \(EngineLog.summary(of: error))")
+                    return
+                }
+            }
+        }
+
+        /// Releases the claim once, from whichever of the end, a failure, the drain or its deadline
+        /// gets there first.
+        private func finish(refusal: String?, drained: Bool = false) {
+            guard let connection else { return }
+            let first = lock.withLock { () -> Bool in
+                guard !released else { return false }
+                released = true
+                return true
+            }
+            guard first else { return }
+            if drained, refusal == nil {
+                EngineLog.emit(
+                    "[HLSVODIngest] AE#732 connection \(connection.label) drained, kept for the next request",
+                    category: .engine)
+            }
+            if let transport {
+                transport.release(connection, refusal: refusal)
+            } else {
+                connection.retire(reason: refusal ?? "transport gone")
+            }
+        }
+
+        /// "received/expected bytes in N s", for the log lines and the stall error.
+        private func progress() -> String {
+            let (count, expected) = lock.withLock { (received, expectedLength) }
+            let elapsed = String(format: "%.1f", Date().timeIntervalSince(started))
+            return "\(count)/\(expected.map(String.init) ?? "?") bytes in \(elapsed) s"
+        }
+    }
 }
 
 /// One HTTP/1.1 keep-alive connection: request, response head, body, and the next request on the
 /// same socket. Not safe for concurrent requests; the pool hands it to one caller at a time.
 final class PersistentHTTP1Connection: @unchecked Sendable {
-    private static let readTimeout: TimeInterval = 30
+    /// Longest wait for the next byte. The only time limit on a body: a slow segment that keeps
+    /// arriving is never cut off, one that stops is.
+    static let defaultReadTimeout: TimeInterval = 30
     private static let writeTimeout: TimeInterval = 20
-    /// Wall-clock ceiling of one exchange, the same as the ingest session's resource timeout.
-    private static let exchangeDeadline: TimeInterval = 45
+    /// Wall-clock ceiling from sending a request to its complete response head.
+    static let headDeadline: TimeInterval = 45
     private static let maxHeadBytes = 128 * 1024
     private static let maxReadBytes = 1 * 1024 * 1024
     /// A refused or redirecting answer is read to its end so the connection survives it; one with a
@@ -195,7 +478,10 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
         case unsupportedURL(URL)
         /// The origin closed a reused connection before answering; the request is safe to repeat.
         case staleKeepAlive
-        case deadlineExceeded
+        /// No complete response head within `headDeadline` of sending the request.
+        case headDeadlineExceeded
+        /// No byte of the body for `seconds`; `progress` is what had arrived by then.
+        case stalled(seconds: TimeInterval, progress: String)
 
         var errorDescription: String? {
             switch self {
@@ -203,19 +489,15 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
             case .tooManyRedirects: return "too many redirects"
             case .unsupportedURL(let url): return "unsupported URL for a persistent connection: \(url)"
             case .staleKeepAlive: return "keep-alive connection closed by the origin"
-            case .deadlineExceeded: return "response not complete within \(Int(PersistentHTTP1Connection.exchangeDeadline)) s"
+            case .headDeadlineExceeded:
+                return "no response head within \(Int(PersistentHTTP1Connection.headDeadline)) s"
+            case .stalled(let seconds, let progress):
+                return "body stalled, no bytes for \(String(format: "%g", seconds)) s after \(progress)"
             }
         }
     }
 
-    struct Outcome {
-        let head: HeldSourceConnection.ResponseHead
-        let body: Data
-        /// nil when the connection may carry the next request.
-        let notReusableBecause: String?
-    }
-
-    private enum Framing {
+    enum Framing {
         case identity(remaining: Int64)
         case chunked(ChunkedBodyDecoder)
         case untilClose
@@ -223,7 +505,8 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
     }
 
     let origin: PersistentHTTP1Transport.Origin
-    private let label: String
+    let label: String
+    private let readTimeout: TimeInterval
     private let stateLock = NSLock()
     private var session: URLSession?
     private var task: URLSessionStreamTask?
@@ -232,22 +515,26 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
     private var _requestCount = 0
     private var _lastUsed = Date.distantPast
 
-    init(origin: PersistentHTTP1Transport.Origin, label: String) {
+    init(origin: PersistentHTTP1Transport.Origin, label: String, readTimeout: TimeInterval = defaultReadTimeout) {
         self.origin = origin
         self.label = label
+        self.readTimeout = readTimeout
     }
 
     var requestCount: Int { stateLock.withLock { _requestCount } }
+    var isRetired: Bool { stateLock.withLock { retired } }
     var lastUsed: Date { stateLock.withLock { _lastUsed } }
 
-    func send(target: URL, headers: [String: String], limit: Int) async throws -> Outcome {
+    /// Writes the request and reads the response head. Cancellation closes the connection: a request
+    /// without its answer leaves nothing on the socket worth keeping.
+    func sendRequest(target: URL, headers: [String: String]) async throws -> HeldSourceConnection.ResponseHead {
         let task = try connectIfNeeded()
         let reused = stateLock.withLock { () -> Bool in
             _requestCount += 1
             _lastUsed = Date()
             return _requestCount > 1
         }
-        let deadline = Date().addingTimeInterval(Self.exchangeDeadline)
+        let deadline = Date().addingTimeInterval(Self.headDeadline)
         return try await withTaskCancellationHandler {
             let request = try HeldSourceConnection.requestBytes(
                 target: target, host: origin.host, port: origin.port, secure: origin.secure,
@@ -258,21 +545,65 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
                 if reused, !Task.isCancelled { throw ConnectionError.staleKeepAlive }
                 throw error
             }
-            let head: HeldSourceConnection.ResponseHead
             do {
-                head = try await readHead(task, reused: reused, deadline: deadline)
+                return try await readHead(task, reused: reused, deadline: deadline)
             } catch let error as ConnectionError {
                 throw error
             } catch {
                 if reused, !Task.isCancelled { throw ConnectionError.staleKeepAlive }
                 throw error
             }
-            return try await readBody(task, head: head, limit: limit, deadline: deadline)
         } onCancel: {
             self.retire(reason: "cancelled")
         }
     }
 
+    /// The next piece of a body under `framing`, nil at its end, plus the framing after it. No
+    /// cancellation handler: the caller decides whether an abandoned body is drained or closed.
+    func readChunk(_ framing: Framing, progress: () -> String) async throws -> (Data?, Framing) {
+        guard let task = stateLock.withLock({ retired ? nil : task }) else { throw CancellationError() }
+        while true {
+            switch framing {
+            case .empty:
+                return (nil, framing)
+            case .identity(let remaining):
+                if remaining <= 0 { return (nil, framing) }
+                let data = try await nextBytes(task, upTo: Int(min(remaining, Int64(Self.maxReadBytes))), progress: progress)
+                guard let data else {
+                    throw ConnectionError.malformed("connection closed \(remaining) bytes before the end of the body")
+                }
+                return (data, .identity(remaining: remaining - Int64(data.count)))
+            case .chunked(let decoder):
+                if let out = try decoder.take(upTo: Self.maxReadBytes) { return (out, framing) }
+                if decoder.isComplete { return (nil, framing) }
+                guard let data = try await nextBytes(task, upTo: Self.maxReadBytes, progress: progress) else {
+                    throw ConnectionError.malformed("connection closed inside a chunked body")
+                }
+                decoder.feed(data)
+            case .untilClose:
+                return (try await nextBytes(task, upTo: Self.maxReadBytes, progress: progress), framing)
+            }
+        }
+    }
+
+    /// Reads a non-2xx body to its end so the connection survives it. nil when the connection may
+    /// carry the next request, the reason otherwise.
+    func discardBody(_ head: HeldSourceConnection.ResponseHead) async throws -> String? {
+        var framing = Self.framing(for: head)
+        if case .identity(let length) = framing, length > Int64(Self.maxDiscardedBodyBytes) {
+            return "status \(head.status) body not drained"
+        }
+        var discarded = 0
+        while true {
+            let (chunk, advanced) = try await readChunk(framing, progress: { "\(discarded) discarded bytes" })
+            framing = advanced
+            guard let chunk else { break }
+            discarded += chunk.count
+            if discarded > Self.maxDiscardedBodyBytes { return "status \(head.status) body not drained" }
+        }
+        return Self.reuseRefusal(head, framing)
+    }
+
     /// Closes the socket. Idempotent; the first reason is the one logged.
     func retire(reason: String) {
         stateLock.lock()
@@ -298,6 +629,28 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
             category: .engine)
     }
 
+    /// Why the connection cannot carry another request after this response, nil when it can.
+    static func reuseRefusal(_ head: HeldSourceConnection.ResponseHead, _ framing: Framing) -> String? {
+        if case .untilClose = framing { return "body framed by close" }
+        let connection = head.headers["connection"]?.lowercased() ?? ""
+        if connection.split(separator: ",").contains(where: { $0.trimmingCharacters(in: .whitespaces) == "close" }) {
+            return "server close"
+        }
+        if !head.statusLine.hasPrefix("HTTP/1.1") { return "not HTTP/1.1 (\(head.statusLine.prefix(8)))" }
+        return nil
+    }
+
+    static func framing(for head: HeldSourceConnection.ResponseHead) -> Framing {
+        if (100..<200).contains(head.status) || head.status == 204 || head.status == 304 { return .empty }
+        if head.headers["transfer-encoding"]?.lowercased().contains("chunked") == true {
+            return .chunked(ChunkedBodyDecoder())
+        }
+        if let raw = head.headers["content-length"], let length = Int64(raw), length >= 0 {
+            return .identity(remaining: length)
+        }
+        return .untilClose
+    }
+
     // MARK: - Wire
 
     private func connectIfNeeded() throws -> URLSessionStreamTask {
@@ -311,7 +664,7 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
             return task
         }
         let configuration = URLSessionConfiguration.ephemeral
-        configuration.timeoutIntervalForRequest = Self.readTimeout
+        configuration.timeoutIntervalForRequest = readTimeout
         configuration.timeoutIntervalForResource = .greatestFiniteMagnitude
         let session = URLSession(
             configuration: configuration, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
@@ -333,7 +686,18 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
         let separator = Data("\r\n\r\n".utf8)
         var head = takePending()
         while head.range(of: separator) == nil {
-            let (chunk, eof) = try await read(task, maxLength: 64 * 1024, deadline: deadline)
+            try Task.checkCancellation()
+            let left = deadline.timeIntervalSinceNow
+            guard left > 0 else { throw ConnectionError.headDeadlineExceeded }
+            let (chunk, eof): (Data, Bool)
+            do {
+                (chunk, eof) = try await read(task, maxLength: 64 * 1024, timeout: min(readTimeout, left))
+            } catch where Self.isTimeout(error) {
+                // The read's timeout was clamped to the deadline; its expiry is the deadline's, not a
+                // stall, and the socket's own POSIX timeout would say neither.
+                if left < readTimeout { throw ConnectionError.headDeadlineExceeded }
+                throw error
+            }
             if chunk.isEmpty && eof {
                 if reused, head.isEmpty { throw ConnectionError.staleKeepAlive }
                 throw ConnectionError.malformed("connection closed before a response head")
@@ -350,90 +714,21 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
         return try HeldSourceConnection.ResponseHead(rawHead: head[..<split.lowerBound])
     }
 
-    private func readBody(
-        _ task: URLSessionStreamTask,
-        head: HeldSourceConnection.ResponseHead,
-        limit: Int,
-        deadline: Date
-    ) async throws -> Outcome {
-        let success = (200..<300).contains(head.status)
-        let cap = success ? limit : Self.maxDiscardedBodyBytes
-        var framing = Self.framing(for: head)
-        if case .identity(let length) = framing, length > Int64(cap) {
-            if success { throw BoundedFetch.Exceeded(limit: limit) }
-            return Outcome(head: head, body: Data(), notReusableBecause: "status \(head.status) body not drained")
-        }
-        var body = Data()
-        loop: while true {
-            switch framing {
-            case .empty:
-                break loop
-            case .identity(let remaining):
-                if remaining <= 0 { break loop }
-                let data = try await nextBytes(task, upTo: Int(min(remaining, Int64(Self.maxReadBytes))), deadline: deadline)
-                guard let data else {
-                    throw ConnectionError.malformed("connection closed \(remaining) bytes before the end of the body")
-                }
-                body.append(data)
-                framing = .identity(remaining: remaining - Int64(data.count))
-            case .chunked(let decoder):
-                if let out = try decoder.take(upTo: Self.maxReadBytes) {
-                    body.append(out)
-                } else if decoder.isComplete {
-                    break loop
-                } else {
-                    guard let data = try await nextBytes(task, upTo: Self.maxReadBytes, deadline: deadline) else {
-                        throw ConnectionError.malformed("connection closed inside a chunked body")
-                    }
-                    decoder.feed(data)
-                }
-            case .untilClose:
-                guard let data = try await nextBytes(task, upTo: Self.maxReadBytes, deadline: deadline) else {
-                    break loop
-                }
-                body.append(data)
-            }
-            if body.count > cap {
-                if success { throw BoundedFetch.Exceeded(limit: limit) }
-                return Outcome(head: head, body: Data(), notReusableBecause: "status \(head.status) body not drained")
-            }
-        }
-        return Outcome(head: head, body: success ? body : Data(), notReusableBecause: Self.reuseRefusal(head, framing))
-    }
-
-    /// Why the connection cannot carry another request after this response, nil when it can.
-    private static func reuseRefusal(_ head: HeldSourceConnection.ResponseHead, _ framing: Framing) -> String? {
-        if case .untilClose = framing { return "body framed by close" }
-        let connection = head.headers["connection"]?.lowercased() ?? ""
-        if connection.split(separator: ",").contains(where: { $0.trimmingCharacters(in: .whitespaces) == "close" }) {
-            return "server close"
-        }
-        if !head.statusLine.hasPrefix("HTTP/1.1") { return "not HTTP/1.1 (\(head.statusLine.prefix(8)))" }
-        return nil
-    }
-
-    private static func framing(for head: HeldSourceConnection.ResponseHead) -> Framing {
-        if (100..<200).contains(head.status) || head.status == 204 || head.status == 304 { return .empty }
-        if head.headers["transfer-encoding"]?.lowercased().contains("chunked") == true {
-            return .chunked(ChunkedBodyDecoder())
-        }
-        if let raw = head.headers["content-length"], let length = Int64(raw), length >= 0 {
-            return .identity(remaining: length)
-        }
-        return .untilClose
-    }
-
     /// Bytes left over from the head read first, then the socket. nil is EOF.
-    private func nextBytes(_ task: URLSessionStreamTask, upTo limit: Int, deadline: Date) async throws -> Data? {
+    private func nextBytes(_ task: URLSessionStreamTask, upTo limit: Int, progress: () -> String) async throws -> Data? {
         let buffered = stateLock.withLock { () -> Data in
             let slice = pending.prefix(limit)
             pending.removeFirst(slice.count)
             return Data(slice)
         }
         if !buffered.isEmpty { return buffered }
-        let (data, eof) = try await read(task, maxLength: limit, deadline: deadline)
-        if data.isEmpty && eof { return nil }
-        return data
+        do {
+            let (data, eof) = try await read(task, maxLength: limit, timeout: readTimeout)
+            if data.isEmpty && eof { return nil }
+            return data
+        } catch where Self.isTimeout(error) {
+            throw ConnectionError.stalled(seconds: readTimeout, progress: progress())
+        }
     }
 
     private func takePending() -> Data {
@@ -445,13 +740,16 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
     }
 
     private func read(
-        _ task: URLSessionStreamTask, maxLength: Int, deadline: Date
+        _ task: URLSessionStreamTask, maxLength: Int, timeout: TimeInterval
     ) async throws -> (Data, Bool) {
-        try Task.checkCancellation()
-        let left = deadline.timeIntervalSinceNow
-        guard left > 0 else { throw ConnectionError.deadlineExceeded }
         let (data, eof) = try await task.readData(
-            ofMinLength: 1, maxLength: max(1, maxLength), timeout: min(Self.readTimeout, left))
+            ofMinLength: 1, maxLength: max(1, maxLength), timeout: timeout)
         return (data ?? Data(), eof)
     }
+
+    private static func isTimeout(_ error: Error) -> Bool {
+        let error = error as NSError
+        return (error.domain == NSPOSIXErrorDomain && error.code == Int(ETIMEDOUT))
+            || (error.domain == NSURLErrorDomain && error.code == NSURLErrorTimedOut)
+    }
 }
diff --git a/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift b/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
index 6bedf6c02..d55933e9a 100644
--- a/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
+++ b/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
@@ -59,7 +59,181 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         let stream = Self.drain(reader)
         XCTAssertEqual(stream.count, 3 * 188 * 3)
         XCTAssertEqual(stream[Self.markerOffset], 3)
-        XCTAssertEqual(server.connectionCount, 2, "the cancelled body cost its connection, nothing more")
+        XCTAssertEqual(server.connectionCount, 1, "the short remainder was drained and the socket kept")
+        XCTAssertEqual(server.maxInFlight, 1, "the next request waited for the drain")
+        XCTAssertEqual(server.requests.map(\.path), ["/vod.m3u8", "/seg0.ts", "/seg1.ts", "/seg2.ts", "/seg3.ts", "/seg4.ts", "/seg5.ts"])
+    }
+
+    func testSlowSegmentReachesTheReaderBeforeItsDownloadEnds() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = ["seg0.ts", "seg1.ts"]
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return index == 0
+                ? .init(body: Self.transportStream(marker: 0))
+                : .init(body: Self.transportStream(marker: 1, packets: 600), trickleUs: 5_000)
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
+        var buffer = [UInt8](repeating: 0, count: 188 * 4)
+        var got = 0
+        while got < buffer.count {
+            let n = buffer.withUnsafeMutableBufferPointer { reader.read($0.baseAddress! + got, size: Int32(188 * 4 - got)) }
+            XCTAssertGreaterThan(n, 0)
+            if n <= 0 { break }
+            got += Int(n)
+        }
+        XCTAssertEqual(buffer[188 * 3], 0x47, "the first packet of segment 1 is in the reader")
+        XCTAssertFalse(server.completed.contains("/seg1.ts"), "while segment 1 is still downloading")
+
+        let rest = Self.drain(reader)
+        XCTAssertEqual(got + rest.count, 3 * 188 + 600 * 188)
+        XCTAssertEqual(server.connectionCount, 1)
+    }
+
+    func testProbeLeavesTheFirstSegmentOpenInsteadOfDownloadingIt() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = ["seg0.ts", "seg1.ts"]
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return index == 0
+                ? .init(body: Self.transportStream(marker: 0, packets: 400), trickleUs: 5_000)
+                : .init(body: Self.transportStream(marker: 1))
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+        XCTAssertFalse(server.completed.contains("/seg0.ts"), "the verdict did not wait for the whole segment")
+
+        let stream = Self.drain(reader)
+        XCTAssertEqual(stream.count, 400 * 188 + 3 * 188)
+        XCTAssertEqual(stream[Self.markerOffset], 0)
+        XCTAssertEqual(stream[400 * 188 + Self.markerOffset], 1)
+        XCTAssertEqual(server.requests.map(\.path), ["/vod.m3u8", "/seg0.ts", "/seg1.ts"])
+        XCTAssertEqual(server.connectionCount, 1)
+    }
+
+    func testSeekOverALargeRemainderClosesTheConnection() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = (0..<5).map { "seg\($0).ts" }
+        // 12,000 packets is about 2.2 MB, over the drain budget.
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return index == 1
+                ? .init(body: Self.transportStream(marker: 1, packets: 12_000), trickleUs: 2_000)
+                : .init(body: Self.transportStream(marker: UInt8(index)))
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
+        var head = [UInt8](repeating: 0, count: 188)
+        XCTAssertEqual(head.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: 188) }, 188)
+        try await waitUntil { server.requests.contains { $0.path == "/seg1.ts" } }
+        let seekStarted = Date()
+        XCTAssertTrue(reader.seek(to: 20)) // segment 3 contains 20 s, the restart is one earlier
+        let stream = Self.drain(reader)
+        XCTAssertLessThan(Date().timeIntervalSince(seekStarted), 2, "the seek did not wait for a drain")
+        XCTAssertEqual(stream.count, 3 * 188 * 3)
+        XCTAssertEqual(stream[Self.markerOffset], 2)
+        XCTAssertEqual(server.connectionCount, 2)
+    }
+
+    func testDrainPastItsDeadlineClosesAndTheNextRequestGoesAhead() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = (0..<5).map { "seg\($0).ts" }
+        // Inside the drain budget, but at 10 ms a packet its rest outlasts the drain deadline.
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return index == 1
+                ? .init(body: Self.transportStream(marker: 1, packets: 1_000), trickleUs: 10_000)
+                : .init(body: Self.transportStream(marker: UInt8(index)))
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
+        var head = [UInt8](repeating: 0, count: 188)
+        XCTAssertEqual(head.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: 188) }, 188)
+        try await waitUntil { server.requests.contains { $0.path == "/seg1.ts" } }
+        let seekStarted = Date()
+        XCTAssertTrue(reader.seek(to: 20))
+        let stream = Self.drain(reader)
+        let waited = Date().timeIntervalSince(seekStarted)
+        XCTAssertGreaterThanOrEqual(waited, PersistentHTTP1Transport.drainDeadline - 0.2)
+        XCTAssertLessThan(waited, PersistentHTTP1Transport.drainDeadline + 2)
+        XCTAssertEqual(stream.count, 3 * 188 * 3)
+        XCTAssertEqual(stream[Self.markerOffset], 2)
+        XCTAssertEqual(server.connectionCount, 2)
+    }
+
+    func testFullBufferLetsTheCurrentSegmentFinishAndHoldsTheNextRequest() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = (0..<3).map { "seg\($0).ts" }
+        // 12 MB of segment 0 plus 5.6 MB of segment 1: the 16 MB FIFO fills inside segment 1.
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return .init(body: Self.transportStream(marker: UInt8(index), packets: index == 0 ? 64_000 : 30_000))
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
+        var head = [UInt8](repeating: 0, count: 188)
+        XCTAssertEqual(head.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: 188) }, 188)
+        try await waitUntil { server.completed.contains("/seg1.ts") }
+        try await Task.sleep(nanoseconds: 200_000_000)
+        XCTAssertFalse(server.requests.contains { $0.path == "/seg2.ts" }, "the next request waits for the reader")
+
+        let rest = Self.drain(reader)
+        XCTAssertEqual(188 + rest.count, (64_000 + 30_000 + 30_000) * 188)
+        XCTAssertEqual(server.connectionCount, 1)
+    }
+
+    func testStalledBodyFailsWithWhatHadArrived() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        server.route = { _ in .init(body: Data(count: 5000), stallAfter: 1000) }
+        let transport = PersistentHTTP1Transport(label: "test", readTimeout: 0.5)
+        defer { transport.close() }
+
+        do {
+            _ = try await transport.get(server.url("/stall"), headers: [:], limit: 1 << 20)
+            XCTFail("a stalled body completed")
+        } catch let error as PersistentHTTP1Connection.ConnectionError {
+            guard case .stalled = error else { return XCTFail("\(error)") }
+            XCTAssertTrue(error.localizedDescription.contains("1000/5000 bytes"), error.localizedDescription)
+        }
+    }
+
+    func testSteadySlowBodyIsNeverCutOff() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        // 40 packets 50 ms apart: two seconds in all, against a read timeout of 0.3 s.
+        let body = Self.transportStream(marker: 7, packets: 40)
+        server.route = { _ in .init(body: body, trickleUs: 50_000) }
+        let transport = PersistentHTTP1Transport(label: "test", readTimeout: 0.3)
+        defer { transport.close() }
+
+        let answer = try await transport.get(server.url("/slow"), headers: [:], limit: 1 << 20)
+        XCTAssertEqual(answer.body, body)
     }
 
     func testServerCloseOpensAFreshConnection() async throws {
@@ -182,10 +356,10 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         return Data((text + "#EXT-X-ENDLIST").utf8)
     }
 
-    /// Three TS packets whose PMT declares HEVC (0x24); the marker sits in the PMT packet's filler.
-    private static func transportStream(marker: UInt8) -> Data {
-        var bytes = [UInt8](repeating: 0xFF, count: 188 * 3)
-        for packet in 0..<3 {
+    /// TS packets whose first PMT declares HEVC (0x24); the marker sits in the PMT packet's filler.
+    private static func transportStream(marker: UInt8, packets: Int = 3) -> Data {
+        var bytes = [UInt8](repeating: 0xFF, count: 188 * packets)
+        for packet in 0..<packets {
             bytes[packet * 188] = 0x47
             bytes[packet * 188 + 3] = 0x10
         }
@@ -229,10 +403,12 @@ final class KeepAliveOrigin: @unchecked Sendable {
         var silentClose = false
         /// Sends the body one 188-byte packet per interval.
         var trickleUs: useconds_t = 0
+        /// Sends this many body bytes, then nothing more until the origin stops.
+        var stallAfter: Int?
 
         init(status: Int = 200, headers: [String: String] = [:], body: Data = Data(),
              chunked: Bool = false, connectionClose: Bool = false, silentClose: Bool = false,
-             trickleUs: useconds_t = 0) {
+             trickleUs: useconds_t = 0, stallAfter: Int? = nil) {
             self.status = status
             self.headers = headers
             self.body = body
@@ -240,6 +416,7 @@ final class KeepAliveOrigin: @unchecked Sendable {
             self.connectionClose = connectionClose
             self.silentClose = silentClose
             self.trickleUs = trickleUs
+            self.stallAfter = stallAfter
         }
     }
 
@@ -255,6 +432,9 @@ final class KeepAliveOrigin: @unchecked Sendable {
     private var _route: @Sendable (String) -> Reply = { _ in Reply(status: 404) }
     private var _requests: [Request] = []
     private var _connections = 0
+    private var _completed: [String] = []
+    private var _inFlight = 0
+    private var _maxInFlight = 0
     private var _fds: [Int32] = []
     private var stopped = false
 
@@ -271,6 +451,10 @@ final class KeepAliveOrigin: @unchecked Sendable {
 
     var requests: [Request] { lock.withLock { _requests } }
     var connectionCount: Int { lock.withLock { _connections } }
+    /// Paths whose whole response went out.
+    var completed: [String] { lock.withLock { _completed } }
+    /// Most responses in progress at once, across connections.
+    var maxInFlight: Int { lock.withLock { _maxInFlight } }
 
     func url(_ path: String) -> URL {
         URL(string: "http://127.0.0.1:\(listener.port)\(path)")!
@@ -323,10 +507,17 @@ final class KeepAliveOrigin: @unchecked Sendable {
             }
             let route: @Sendable (String) -> Reply = lock.withLock {
                 _requests.append(Request(connection: id, path: path, requestLine: requestLine, headers: headers))
+                _inFlight += 1
+                _maxInFlight = max(_maxInFlight, _inFlight)
                 return _route
             }
             let reply = route(path)
-            if !respond(fd, reply) || reply.connectionClose || reply.silentClose { return }
+            let sent = respond(fd, reply)
+            lock.withLock {
+                _inFlight -= 1
+                if sent { _completed.append(path) }
+            }
+            if !sent || reply.connectionClose || reply.silentClose { return }
         }
     }
 
@@ -351,6 +542,11 @@ final class KeepAliveOrigin: @unchecked Sendable {
             }
             return send(fd, Data("0\r\n\r\n".utf8))
         }
+        if let stallAfter = reply.stallAfter {
+            guard send(fd, reply.body.prefix(stallAfter)) else { return false }
+            while !lock.withLock({ stopped }) { usleep(20_000) }
+            return false
+        }
         guard reply.trickleUs > 0 else { return send(fd, reply.body) }
         var offset = 0
         while offset < reply.body.count {
diff --git a/docs/api.md b/docs/api.md
index f15512449..eacd74371 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1334,7 +1334,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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, 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). |
 | `sourceOpenPolicy` | `SourceOpenPolicy()` | HTTP VOD opening budgets for the playback reader and its reopens: `firstByteTimeout` (15 s) bounds the first data wait, `sizeProbeTimeout` (25 s) bounds the one retry and the whole size discovery, slot waits included. Nonpositive or nonfinite values take the defaults, anything above 120 s is capped. A request that gets no response is retried once with an open-ended Range and that connection stays the playback connection; two unanswered requests fail as `.sourceOpenFailed` instead of demoting the source to forward-only. A real length-less or Range-ignoring response keeps the ordinary sequential handling. Single-request origins run the size probes serially, others race them and join the losers before playback starts. Live, `sequentialOrigin`, remote HLS and disposable probes keep their own budgets. |
-| `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. A finite HLS VOD on the HEVC-in-MPEG-TS ingest (AE#268) is covered too (AE#732): playlist, key and segment requests run over one persistent HTTP/1.1 connection per origin, reused across segments and fetched one at a time, for origins that refuse h2 or new connections but serve consecutive requests on one keep-alive connection; a new connection opens only on a server close, an origin change, or a seek that abandons a body, and the log names each connection's protocol and request count. **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. A finite HLS VOD on the HEVC-in-MPEG-TS ingest (AE#268) is covered too (AE#732): playlist, key and segment requests run over one persistent HTTP/1.1 connection per origin, reused across segments and fetched one at a time, for origins that refuse h2 or new connections but serve consecutive requests on one keep-alive connection. Each body is streamed into the ingest as it arrives, and only the wait for a response head has a wall-clock ceiling (45 s); a body ends on its size limit or on 30 s without a byte, never on its duration. A new connection opens only on a server close, an origin change, or a seek that abandons a body with more than 2 MB left (a smaller remainder is drained for up to 3 s and the connection kept, with the next request waiting for it), and the log names each connection's protocol and request count. **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
diff --git a/docs/cli.md b/docs/cli.md
index 92a88539f..a21fd5290 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -284,7 +284,12 @@ connection after five seconds and cost exactly one re-request at the frontier wh
 On a finite HEVC-in-MPEG-TS HLS VOD (the AE#268 ingest) the same flag puts the playlist and every
 segment on one persistent HTTP/1.1 connection (AE#732); the observable there is the
 `[HLSVODIngest] AE#732 connection ... open` and `... closed after N requests reason=...` lines, one
-pair per connection, and a run without seeks should show exactly one.
+pair per connection. A seek mid-body logs `draining abandoned body, <received>/<expected> bytes` and
+then `drained, kept for the next request`, or closes with `abandoned mid-body`; a stalled body ends
+the session with `body stalled, no bytes for 30 s after ...`. The engine's own repositions onto segment
+0 right after the open still cost one connection each. For the slow-origin case, serve 11 MB HEVC-in-TS
+segments from a keep-alive origin at 200 KB/s shared across its connections: each segment then takes
+about 58 s, longer than the 45 s a whole exchange used to be allowed (#732).
 
 `--progressive-segments` sets `LoadOptions.progressiveSegmentDelivery`: each VOD segment is served
 while it is written. Run it against a throttled origin and compare the `FIRSTFRAME` and first

From c127d85de18297c1387eb9ba3aa1713337c8f5d0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 16:14:21 +0200
Subject: [PATCH 119/132] fix(hls): review follow-ups for the streamed
 persistent ingest (#732)

- A probe response the producer's run does not open with (a seek onto
  another or an encrypted first segment) is abandoned before any request.
  It held the origin's claim unread, so the next request waited forever.
- A request cancelled while it waited for the origin does not take the
  connection; its cancellation handler would close the drained socket.
- A seek drains an abandoned body only when the rest arrives within the
  drain deadline at the rate seen so far; a slow remainder closes at once
  instead of holding the next request 3 s and closing anyway.
- next() checks cancellation before marking a read in flight, so abandon()
  never waits on a read that does not happen.
- A refused or redirecting body is drained for at most 45 s.
- No extra copy of each chunk into the pending buffer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |   6 +-
 .../IO/HLSIngest/HLSVODIngestReader.swift     |   8 +-
 .../HLSIngest/PersistentHTTP1Transport.swift  |  32 ++++--
 .../Issue732PersistentHTTP1Tests.swift        | 104 +++++++++++++++++-
 docs/api.md                                   |   2 +-
 5 files changed, 137 insertions(+), 15 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2fce29b7..84f69ff13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -89,9 +89,9 @@ third-party patent licensing; integrators who enable them are responsible for th
   for a response head, and a body is limited by its size and by 30 s without a byte, so a large
   segment that keeps arriving is never cut off. That ceiling surfaced as `NSPOSIXErrorDomain Code=60`,
   which named neither cause; a stall now says `body stalled, no bytes for 30 s after <received>/<expected>
-  bytes in <elapsed> s`. A seek that abandons a body with at most 2 MB left drains it for up to 3 s and
-  keeps the connection, and the next request waits for that instead of opening a second connection
-  beside it; a larger remainder still closes it. With the FIFO full the current segment is read to its
+  bytes in <elapsed> s`. A seek that abandons a body with at most 2 MB left, at a rate that brings it in within 3 s,
+  drains it and keeps the connection, and the next request waits for that instead of opening a
+  second connection beside it; a larger or slower remainder closes it at once. With the FIFO full the current segment is read to its
   end, so a paused session leaves the connection idle between two requests, not mid-body. Measured on a
   loopback origin at 200 KB/s with 11.6 MB segments: before, the probe died at 45.1 s with `Code=60` and
   the session left the ingest; after, the ingest held and played. The h2 path's 45 s resource timeout
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index c6ab47c6d..989560402 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -466,6 +466,12 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
             defer { primedSegment = nil }
             return primedSegment
         }
+        // A probe response this run does not open with holds the origin; let it go before any request,
+        // or that request waits behind a body nobody will read.
+        if let ready = primed, segments.first?.1 != ready.url || segments.first?.0.crypt != nil {
+            ready.body.abandon()
+            primed = nil
+        }
         defer { primed?.body.abandon() }
         for (offset, (segment, url)) in segments.enumerated() {
             try Task.checkCancellation()
@@ -512,7 +518,7 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
             while true {
                 let chunk = try await body.next()
                 if let chunk {
-                    pending.append(chunk)
+                    if pending.isEmpty { pending = chunk } else { pending.append(chunk) }
                     total += chunk.count
                 }
                 if !checked, chunk == nil || !pending.isEmpty {
diff --git a/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift b/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift
index 0189b09c9..4b1a6deab 100644
--- a/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/PersistentHTTP1Transport.swift
@@ -159,6 +159,9 @@ final class PersistentHTTP1Transport: @unchecked Sendable {
     /// deadline or its end.
     private func checkOut(_ origin: Origin) async throws -> PersistentHTTP1Connection {
         while true {
+            // A request cancelled while it waited must not take the connection: its cancellation
+            // handler would close the socket the drain just kept.
+            try Task.checkCancellation()
             if let connection = try claim(origin) { return connection }
             await withCheckedContinuation { (waiter: CheckedContinuation<Void, Never>) in
                 let parked = lock.withLock { () -> Bool in
@@ -305,6 +308,10 @@ final class PersistentHTTP1Transport: @unchecked Sendable {
         /// The next piece of the body, nil at its end.
         func next() async throws -> Data? {
             guard let connection else { return nil }
+            if Task.isCancelled {
+                abandon()
+                throw CancellationError()
+            }
             let current = lock.withLock { () -> PersistentHTTP1Connection.Framing? in
                 guard !released, !abandoned else { return nil }
                 reading = true
@@ -314,11 +321,6 @@ final class PersistentHTTP1Transport: @unchecked Sendable {
                 if lock.withLock({ abandoned }) { throw CancellationError() }
                 return nil
             }
-            if Task.isCancelled {
-                lock.withLock { reading = false }
-                abandon()
-                throw CancellationError()
-            }
             let chunk: Data?
             let advanced: PersistentHTTP1Connection.Framing
             do {
@@ -373,15 +375,18 @@ final class PersistentHTTP1Transport: @unchecked Sendable {
             }
         }
 
-        /// Stops reading. Little left: drained in the background, the connection kept, and the next
-        /// request to this origin waits for it. Otherwise the connection is closed. Idempotent.
+        /// Stops reading. Little left, at a rate that brings it in before `drainDeadline`: drained in
+        /// the background, the connection kept, and the next request to this origin waits for it.
+        /// Otherwise the connection is closed at once, since a drain that cannot finish only delays the
+        /// next request by its deadline and loses the connection anyway. Idempotent.
         func abandon() {
             guard let connection else { return }
             let decision = lock.withLock { () -> (inFlight: Bool, drainable: Bool)? in
                 guard !released, !abandoned else { return nil }
                 abandoned = true
                 switch framing {
-                case .identity(let remaining): return (reading, remaining <= PersistentHTTP1Transport.maxDrainBytes)
+                case .identity(let remaining):
+                    return (reading, remaining <= PersistentHTTP1Transport.maxDrainBytes && drainsInTime(remaining))
                 case .chunked, .empty: return (reading, true)
                 case .untilClose: return (reading, false)
                 }
@@ -403,6 +408,15 @@ final class PersistentHTTP1Transport: @unchecked Sendable {
             }
         }
 
+        /// Under `lock`. Whether `remaining` bytes arrive within the drain deadline at the rate this body
+        /// has come in so far; a body too young to have a rate gets the benefit of the doubt.
+        private func drainsInTime(_ remaining: Int64) -> Bool {
+            let elapsed = Date().timeIntervalSince(started)
+            guard remaining > 0, received > 0, elapsed >= 0.25 else { return true }
+            let rate = Double(received) / elapsed
+            return Double(remaining) / rate <= PersistentHTTP1Transport.drainDeadline
+        }
+
         private func drain() async {
             guard let connection else { return }
             var drained: Int64 = 0
@@ -594,7 +608,9 @@ final class PersistentHTTP1Connection: @unchecked Sendable {
             return "status \(head.status) body not drained"
         }
         var discarded = 0
+        let started = Date()
         while true {
+            if Date().timeIntervalSince(started) > Self.headDeadline { return "status \(head.status) body too slow to drain" }
             let (chunk, advanced) = try await readChunk(framing, progress: { "\(discarded) discarded bytes" })
             framing = advanced
             guard let chunk else { break }
diff --git a/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift b/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
index d55933e9a..799ba0218 100644
--- a/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
+++ b/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
@@ -1,3 +1,4 @@
+import CommonCrypto
 import Foundation
 import XCTest
 @testable import AetherEngine
@@ -150,11 +151,11 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         XCTAssertEqual(server.connectionCount, 2)
     }
 
-    func testDrainPastItsDeadlineClosesAndTheNextRequestGoesAhead() async throws {
+    func testSlowRemainderClosesAtOnceInsteadOfDraining() async throws {
         let server = try XCTUnwrap(KeepAliveOrigin())
         defer { server.stop() }
         let segments = (0..<5).map { "seg\($0).ts" }
-        // Inside the drain budget, but at 10 ms a packet its rest outlasts the drain deadline.
+        // Inside the drain budget by size, but at 10 ms a packet its rest needs seconds.
         server.route = { path in
             if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
             guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
@@ -167,6 +168,36 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         let reader = try XCTUnwrap(made)
         defer { reader.close() }
 
+        var head = [UInt8](repeating: 0, count: 188)
+        XCTAssertEqual(head.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: 188) }, 188)
+        try await waitUntil { server.requests.contains { $0.path == "/seg1.ts" } }
+        try await Task.sleep(nanoseconds: 500_000_000) // long enough for the body to show its rate
+        let seekStarted = Date()
+        XCTAssertTrue(reader.seek(to: 20))
+        let stream = Self.drain(reader)
+        XCTAssertLessThan(Date().timeIntervalSince(seekStarted), 1.5, "no drain that could not finish")
+        XCTAssertEqual(stream.count, 3 * 188 * 3)
+        XCTAssertEqual(stream[Self.markerOffset], 2)
+        XCTAssertEqual(server.connectionCount, 2)
+    }
+
+    func testDrainPastItsDeadlineClosesAndTheNextRequestGoesAhead() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = (0..<5).map { "seg\($0).ts" }
+        // Fast enough to look drainable, then silent: only the drain deadline ends it.
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return index == 1
+                ? .init(body: Self.transportStream(marker: 1, packets: 1_000), stallAfter: 188 * 100)
+                : .init(body: Self.transportStream(marker: UInt8(index)))
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
         var head = [UInt8](repeating: 0, count: 188)
         XCTAssertEqual(head.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: 188) }, 188)
         try await waitUntil { server.requests.contains { $0.path == "/seg1.ts" } }
@@ -181,6 +212,51 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         XCTAssertEqual(server.connectionCount, 2)
     }
 
+    func testSeekOntoAnEncryptedSegmentLetsTheProbeResponseGo() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let key = Data((0..<16).map { UInt8($0) })
+        let clear = (0..<5).map { Self.transportStream(marker: UInt8($0)) }
+        let encrypted = clear.map { Self.aes128CBC($0, key: key) }
+        var text = "#EXTM3U\n#EXT-X-TARGETDURATION:6\n"
+        for index in 0..<5 {
+            if index == 2 {
+                text += "#EXT-X-KEY:METHOD=AES-128,URI=\"key.bin\",IV=0x00000000000000000000000000000000\n"
+            }
+            text += "#EXTINF:6,\nseg\(index).ts\n"
+        }
+        let playlist = Data((text + "#EXT-X-ENDLIST").utf8)
+        // Segment 0 is large and slow, so its probe response is still open when the seek lands.
+        let first = Self.transportStream(marker: 0, packets: 2_000)
+        server.route = { path in
+            switch path {
+            case "/vod.m3u8": return .init(body: playlist)
+            case "/key.bin": return .init(body: key)
+            case "/seg0.ts": return .init(body: first, trickleUs: 2_000)
+            default:
+                guard let index = Int(path.dropFirst(4).dropLast(3)), (1..<5).contains(index) else {
+                    return .init(status: 404)
+                }
+                return .init(body: index >= 2 ? encrypted[index] : clear[index])
+            }
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
+        XCTAssertTrue(reader.seek(to: 20)) // segment 3 contains 20 s; the restart is 2, the first encrypted one
+        let done = expectation(description: "drained")
+        let box = StreamBox()
+        Thread.detachNewThread {
+            box.bytes = Self.drain(reader)
+            done.fulfill()
+        }
+        await fulfillment(of: [done], timeout: 10)
+        XCTAssertEqual(box.bytes.count, 3 * 188 * 3)
+        XCTAssertEqual(box.bytes.first.map { _ in box.bytes[Self.markerOffset] }, 2)
+    }
+
     func testFullBufferLetsTheCurrentSegmentFinishAndHoldsTheNextRequest() async throws {
         let server = try XCTUnwrap(KeepAliveOrigin())
         defer { server.stop() }
@@ -370,6 +446,30 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         return Data(bytes)
     }
 
+    private final class StreamBox: @unchecked Sendable {
+        var bytes: [UInt8] = []
+    }
+
+    private static func aes128CBC(_ data: Data, key: Data) -> Data {
+        var out = Data(count: data.count + kCCBlockSizeAES128)
+        var written = 0
+        let iv = Data(count: kCCBlockSizeAES128)
+        let outCapacity = out.count
+        let status = out.withUnsafeMutableBytes { outBytes in
+            data.withUnsafeBytes { inBytes in
+                key.withUnsafeBytes { keyBytes in
+                    iv.withUnsafeBytes { ivBytes in
+                        CCCrypt(CCOperation(kCCEncrypt), CCAlgorithm(kCCAlgorithmAES), CCOptions(kCCOptionPKCS7Padding),
+                                keyBytes.baseAddress, key.count, ivBytes.baseAddress,
+                                inBytes.baseAddress, data.count, outBytes.baseAddress, outCapacity, &written)
+                    }
+                }
+            }
+        }
+        precondition(status == kCCSuccess)
+        return out.prefix(written)
+    }
+
     private static func drain(_ reader: HLSVODIngestReader) -> [UInt8] {
         var out: [UInt8] = []
         var buffer = [UInt8](repeating: 0, count: 4096)
diff --git a/docs/api.md b/docs/api.md
index eacd74371..16362779c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1334,7 +1334,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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, 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). |
 | `sourceOpenPolicy` | `SourceOpenPolicy()` | HTTP VOD opening budgets for the playback reader and its reopens: `firstByteTimeout` (15 s) bounds the first data wait, `sizeProbeTimeout` (25 s) bounds the one retry and the whole size discovery, slot waits included. Nonpositive or nonfinite values take the defaults, anything above 120 s is capped. A request that gets no response is retried once with an open-ended Range and that connection stays the playback connection; two unanswered requests fail as `.sourceOpenFailed` instead of demoting the source to forward-only. A real length-less or Range-ignoring response keeps the ordinary sequential handling. Single-request origins run the size probes serially, others race them and join the losers before playback starts. Live, `sequentialOrigin`, remote HLS and disposable probes keep their own budgets. |
-| `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. A finite HLS VOD on the HEVC-in-MPEG-TS ingest (AE#268) is covered too (AE#732): playlist, key and segment requests run over one persistent HTTP/1.1 connection per origin, reused across segments and fetched one at a time, for origins that refuse h2 or new connections but serve consecutive requests on one keep-alive connection. Each body is streamed into the ingest as it arrives, and only the wait for a response head has a wall-clock ceiling (45 s); a body ends on its size limit or on 30 s without a byte, never on its duration. A new connection opens only on a server close, an origin change, or a seek that abandons a body with more than 2 MB left (a smaller remainder is drained for up to 3 s and the connection kept, with the next request waiting for it), and the log names each connection's protocol and request count. **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. A finite HLS VOD on the HEVC-in-MPEG-TS ingest (AE#268) is covered too (AE#732): playlist, key and segment requests run over one persistent HTTP/1.1 connection per origin, reused across segments and fetched one at a time, for origins that refuse h2 or new connections but serve consecutive requests on one keep-alive connection. Each body is streamed into the ingest as it arrives, and only the wait for a response head has a wall-clock ceiling (45 s); a body ends on its size limit or on 30 s without a byte, never on its duration. A new connection opens only on a server close, an origin change, or a seek that abandons a body with more than 2 MB left or too slow to arrive within 3 s (otherwise the remainder is drained and the connection kept, with the next request waiting for it), and the log names each connection's protocol and request count. **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 099fac0c2705c8049e389f75f3da976d4621aa37 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 17 Oct 2026 17:16:52 +0200
Subject: [PATCH 120/132] test(io): reader test knobs are init parameters, not
 process-wide hooks

LiveStreamRefusalRetryTests failed on CI in six recent runs (main and four
PR branches): "a stream refused mid-session ..." and "a stream refused for
longer than the budget ..." with drained.failure != nil and too few requests.

Cause: AVIOReader read AetherEngine.reconnectBackoffScaleForTesting,
pinIdleSecondsForTesting and liveRefusalRetryBudgetForTesting from statics at
init. swift-testing runs these tests, and the five other suites that set the
scale, in parallel, so a reader picked up whatever its neighbours had set:
the budget test's 1 s budget plus a scale another suite's defer had put back
to 1.0 makes the mid-session test give up after its second refusal. Forcing
exactly that interleaving on main reproduces the three CI expectation
failures deterministically.

The three values are now AVIOReader init parameters (backoffScale,
pinIdleSeconds, liveRefusalRetryBudget) with the shipped defaults, the same
shape connStallTimeout and windowHighWater already take for this reason, and
the statics are gone. Six suites pass their values to the reader they build.
No behaviour change outside tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift       | 11 --------
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 21 +++++++-------
 .../ErrorEndedReconnectTests.swift            |  4 +--
 .../Issue309SilentTransportDeathTests.swift   |  4 +--
 .../Issue410SourceStallVisibilityTests.swift  | 12 ++------
 .../LiveStreamRefusalRetryTests.swift         | 21 ++++++--------
 .../ResolvedURLInvalidationTests.swift        | 28 ++++---------------
 .../ServedFromMemoryProgressTests.swift       |  4 +--
 8 files changed, 30 insertions(+), 75 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 50c3c70b9..bdbf1a191 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1676,17 +1676,6 @@ public final class AetherEngine: ObservableObject {
         sourceThrottleKbpsForTesting = max(0, kbps)
     }
 
-    /// TEST-ONLY: scales the reader's reconnect backoff (1.0 = real timing). Read once by each
-    /// `AVIOReader` at init, so set it before `load`/`start`. Lets a bounded give-up that spans
-    /// ~13 exponential backoffs finish in test time instead of a minute of real sleeping.
-    nonisolated(unsafe) static var reconnectBackoffScaleForTesting = 1.0
-
-    /// TEST-ONLY: how long a pinned redirect target may carry no bytes before its first refusal
-    /// drops it instead of riding out the keep-pin grace (#392). Read once by each `AVIOReader` at
-    /// init, so set it before `load`/`start`. nil keeps the shipped minute, which no test can wait
-    /// out. See `AVIOReader.pinIdleRepinSecondsDefault`.
-    nonisolated(unsafe) static var pinIdleSecondsForTesting: TimeInterval? = nil
-
     /// Reads `AVPlayer.eligibleForHDRPlayback` and `AVPlayer.availableHDRModes` at call time.
     /// Eligibility is display-configuration aware on all platforms (its change notification fires
     /// on display connection/disconnection), so per-load reads pick up monitor changes; the value
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 1ef1d4ce7..c54dcdf9b 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -774,9 +774,6 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     static let liveRefusalMaximumRetryWait: TimeInterval = 5
     /// How long a live stream keeps asking before the refusal is the session's answer.
     static let liveRefusalRetryBudget: TimeInterval = 60
-    /// Test seam: a shorter budget, so the give-up is exercised without a minute of wall clock.
-    /// Read once per reader, at init.
-    nonisolated(unsafe) static var liveRefusalRetryBudgetForTesting: TimeInterval?
 
     /// The wait before a live stream's refused request is made again: a second, or the origin's
     /// Retry-After (0 for none) when that is longer, never more than `liveRefusalMaximumRetryWait`.
@@ -1137,18 +1134,20 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
     /// TEST-ONLY slow-CDN throttle (kbit/s, 0 = unlimited), captured once from the static hook at init.
     private let throttleKbps: Int
-    /// TEST-ONLY reconnect-backoff scale (1.0 = real timing), captured once from the static hook at init.
+    /// Reconnect-backoff scale, 1 in the shipped app; tests shrink it so a give-up spanning a dozen
+    /// backoffs finishes in test time. An init parameter like `connStallTimeout` below, for the same
+    /// reason: a process-wide hook leaked into every suite running alongside.
     private let backoffScale: Double
     /// #392: the idle gap this reader takes a first refusal at face value after. Shipped value
-    /// unless a test shortens it, captured once at init like the two hooks above.
+    /// unless a test shortens it.
     private let pinIdleSeconds: TimeInterval
-    /// How long a live refusal streak is ridden out, captured once at init like the hooks above.
+    /// How long a live refusal streak is ridden out, `liveRefusalRetryBudget` unless a test shortens it.
     private let liveRefusalRetryBudgetSeconds: TimeInterval
     /// Stall threshold this reader runs with, `connStallTimeoutDefault` unless a caller overrides it.
     /// One value for both detectors, because they are one policy: a connection that has delivered
     /// nothing for this long is replaced, whether or not a read is waiting on it (#309).
     ///
-    /// An init parameter rather than a process-wide test hook on purpose. The hooks next to it are
+    /// An init parameter rather than a process-wide test hook on purpose. A hook is
     /// read at every reader's init, so a test that sets one changes the behaviour of every reader any
     /// CONCURRENTLY running suite happens to build, and swift-testing runs suites in parallel. A
     /// shortened stall threshold leaking that way would make other suites reconnect early under
@@ -1185,7 +1184,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, detourIdleSeconds: TimeInterval? = nil, detourFetchBudget: TimeInterval? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil, sourceOpenPolicy: SourceOpenPolicy = .init(), requestHeaderStore: RequestHeaderStore? = 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, detourFetchBudget: TimeInterval? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil, sourceOpenPolicy: SourceOpenPolicy = .init(), requestHeaderStore: RequestHeaderStore? = nil, backoffScale: Double = 1, pinIdleSeconds: TimeInterval = AVIOReader.pinIdleRepinSecondsDefault, liveRefusalRetryBudget: TimeInterval = AVIOReader.liveRefusalRetryBudget) {
         self.sourceOpenPolicy = sourceOpenPolicy
         self.probeControl = probeControl
         self.probeRequestSession = probeControl == nil ? nil : probeRequestSession
@@ -1201,9 +1200,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         self.chunkMaxRetries = max(1, chunkMaxRetries)
         self.boundedInitialFetch = boundedInitialFetch.map { max(1, $0) }
         self.throttleKbps = AetherEngine.sourceThrottleKbpsForTesting
-        self.backoffScale = AetherEngine.reconnectBackoffScaleForTesting
-        self.pinIdleSeconds = AetherEngine.pinIdleSecondsForTesting ?? Self.pinIdleRepinSecondsDefault
-        self.liveRefusalRetryBudgetSeconds = Self.liveRefusalRetryBudgetForTesting ?? Self.liveRefusalRetryBudget
+        self.backoffScale = backoffScale
+        self.pinIdleSeconds = pinIdleSeconds
+        self.liveRefusalRetryBudgetSeconds = liveRefusalRetryBudget
         self.connStallTimeout = max(0.05, connStallTimeout)
         self.winHighWater = max(1, windowHighWater
             ?? (isLive ? Self.liveWinHighWaterDefault : Self.winHighWaterDefault))
diff --git a/Tests/AetherEngineTests/ErrorEndedReconnectTests.swift b/Tests/AetherEngineTests/ErrorEndedReconnectTests.swift
index d6d68e5f0..a4a24fdf8 100644
--- a/Tests/AetherEngineTests/ErrorEndedReconnectTests.swift
+++ b/Tests/AetherEngineTests/ErrorEndedReconnectTests.swift
@@ -42,8 +42,6 @@ struct ErrorEndedReconnectTests {
     @Test("an origin refusing every refill is retried with backoff and given up on",
           .timeLimit(.minutes(2)))
     func refusedRefillIsBoundedAndGivenUp() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 512 * 1024
         let serverMaybe = ThrottledOriginServer(
@@ -53,7 +51,7 @@ struct ErrorEndedReconnectTests {
         let server = try #require(serverMaybe)
         defer { server.stop() }
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         let phases = PhaseLog()
         reader.onNetworkPhaseChanged = { phases.append($0) }
diff --git a/Tests/AetherEngineTests/Issue309SilentTransportDeathTests.swift b/Tests/AetherEngineTests/Issue309SilentTransportDeathTests.swift
index d3f5c4945..4d27ae900 100644
--- a/Tests/AetherEngineTests/Issue309SilentTransportDeathTests.swift
+++ b/Tests/AetherEngineTests/Issue309SilentTransportDeathTests.swift
@@ -165,8 +165,6 @@ struct Issue309SilentTransportDeathTests {
     @Test("a generation that never sees a first byte is ended too", .timeLimit(.minutes(2)))
     func headersWithoutABodyAreEnded() async throws {
         let stallTimeout: TimeInterval = 0.6
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let silenceOffset = Self.silenceOffset
         let attempts = AttemptCounter()
@@ -180,7 +178,7 @@ struct Issue309SilentTransportDeathTests {
         defer { server.stop() }
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
                                 boundedInitialFetch: Self.firstRange,
-                                connStallTimeout: stallTimeout)
+                                connStallTimeout: stallTimeout, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
diff --git a/Tests/AetherEngineTests/Issue410SourceStallVisibilityTests.swift b/Tests/AetherEngineTests/Issue410SourceStallVisibilityTests.swift
index cb3cf52b5..de1f3a6e3 100644
--- a/Tests/AetherEngineTests/Issue410SourceStallVisibilityTests.swift
+++ b/Tests/AetherEngineTests/Issue410SourceStallVisibilityTests.swift
@@ -36,8 +36,6 @@ struct Issue410SourceStallVisibilityTests {
     @Test("a refusing origin stays visible across the runway and the give-up",
           .timeLimit(.minutes(2)))
     func refusedRefillHoldsTheStallThroughGiveUp() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         // 8 MB of runway so the low-water refill is refused while the window still has plenty to serve:
         // the reads after the refusal are exactly the memory serves that used to report delivery.
@@ -50,7 +48,7 @@ struct Issue410SourceStallVisibilityTests {
         defer { server.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         let phases = PhaseLog()
         reader.onNetworkPhaseChanged = { phases.append($0) }
@@ -79,8 +77,6 @@ struct Issue410SourceStallVisibilityTests {
     @Test("a transient refusal clears once the origin delivers again",
           .timeLimit(.minutes(2)))
     func transientRefusalClearsOnDelivery() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 1024 * 1024
         let refusals = OSAllocatedUnfairLockCounter()
@@ -95,7 +91,7 @@ struct Issue410SourceStallVisibilityTests {
         defer { server.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         let phases = PhaseLog()
         reader.onNetworkPhaseChanged = { phases.append($0) }
@@ -125,8 +121,6 @@ struct Issue410SourceStallVisibilityTests {
     @Test("bytes handed back out of memory do not clear the stall",
           .timeLimit(.minutes(2)))
     func memoryServeDoesNotClearTheStall() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let runway: Int64 = 8 * 1024 * 1024
         let serverMaybe = ThrottledOriginServer(
@@ -137,7 +131,7 @@ struct Issue410SourceStallVisibilityTests {
         defer { server.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
-                                boundedInitialFetch: runway)
+                                boundedInitialFetch: runway, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         let phases = PhaseLog()
         reader.onNetworkPhaseChanged = { phases.append($0) }
diff --git a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
index 593db234c..2c2391b5e 100644
--- a/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
+++ b/Tests/AetherEngineTests/LiveStreamRefusalRetryTests.swift
@@ -10,6 +10,8 @@ import Foundation
 ///
 /// The loopback cases run with the reconnect backoff scaled down, the way the other reader suites
 /// do, and are judged by what came through and how many requests it took, never by the wall clock.
+/// Scale and budget go to each reader at init: process-wide hooks raced between these tests, which
+/// run in parallel, and handed one test's one-second budget to its neighbour.
 /// The wait itself is a pure rule, tested as one.
 @Suite("Live stream reader rides out refusals", .offCooperativePool, .timeLimit(.minutes(2)))
 struct LiveStreamRefusalRetryTests {
@@ -101,8 +103,11 @@ struct LiveStreamRefusalRetryTests {
         return data
     }
 
-    private static func makeLiveReader(_ url: URL) -> AVIOReader {
-        AVIOReader(url: url, label: "live", prefetchEnabled: true, isLive: true)
+    private static func makeLiveReader(
+        _ url: URL, backoffScale: Double = 0.02, refusalBudget: TimeInterval = AVIOReader.liveRefusalRetryBudget
+    ) -> AVIOReader {
+        AVIOReader(url: url, label: "live", prefetchEnabled: true, isLive: true,
+                   backoffScale: backoffScale, liveRefusalRetryBudget: refusalBudget)
     }
 
     /// Reads until `expectedBytes` have come through or the reader fails; the bytes, and the code
@@ -134,8 +139,6 @@ struct LiveStreamRefusalRetryTests {
 
     @Test("a stream refused mid-session is asked for again until it is served, and arms no pacer")
     func refusedMidStreamIsRetriedUntilServed() throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
         let first = Self.streamBytes(count: 400)
         let second = Self.streamBytes(count: 400)
         let refusals = 3
@@ -168,16 +171,12 @@ struct LiveStreamRefusalRetryTests {
 
     @Test("a stream refused for longer than the budget ends as a read error")
     func refusedPastTheBudgetGivesUp() throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
-        AVIOReader.liveRefusalRetryBudgetForTesting = 1
-        defer { AVIOReader.liveRefusalRetryBudgetForTesting = nil }
         let first = Self.streamBytes(count: 400)
         let origin = try #require(ScriptedOrigin { index in
             index == 0 ? .init(status: 200, body: first) : .init(status: 509)
         })
         defer { origin.stop() }
-        let reader = Self.makeLiveReader(origin.url)
+        let reader = Self.makeLiveReader(origin.url, refusalBudget: 1)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
@@ -207,8 +206,6 @@ struct LiveStreamRefusalRetryTests {
 
     @Test("a live open answered with a server error is asked once more and plays when served")
     func serverErrorAtOpenIsAskedOnceMore() throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
         let body = Self.streamBytes(count: 400)
         let origin = try #require(ScriptedOrigin { index in
             index == 0 ? .init(status: 502) : .init(status: 200, body: body)
@@ -225,8 +222,6 @@ struct LiveStreamRefusalRetryTests {
 
     @Test("a live open answered with a server error twice fails typed with its status")
     func serverErrorTwiceAtOpenFailsTyped() throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
         let origin = try #require(ScriptedOrigin { _ in .init(status: 500) })
         defer { origin.stop() }
         let reader = Self.makeLiveReader(origin.url)
diff --git a/Tests/AetherEngineTests/ResolvedURLInvalidationTests.swift b/Tests/AetherEngineTests/ResolvedURLInvalidationTests.swift
index a55d28faa..613320306 100644
--- a/Tests/AetherEngineTests/ResolvedURLInvalidationTests.swift
+++ b/Tests/AetherEngineTests/ResolvedURLInvalidationTests.swift
@@ -134,8 +134,6 @@ struct ResolvedURLInvalidationTests {
     @Test("a rate-limited refill keeps the pin instead of re-resolving through the source",
           .timeLimit(.minutes(2)))
     func rateLimitedRefillKeepsThePin() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 256 * 1024
         let attempts = AttemptCounter()
@@ -158,7 +156,7 @@ struct ResolvedURLInvalidationTests {
         defer { source.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(source.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
@@ -186,8 +184,6 @@ struct ResolvedURLInvalidationTests {
     @Test("a 509 refill keeps the pin instead of re-resolving through the source",
           .timeLimit(.minutes(2)))
     func connectionCappedRefillKeepsThePin() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 256 * 1024
         let attempts = AttemptCounter()
@@ -211,7 +207,7 @@ struct ResolvedURLInvalidationTests {
         defer { source.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(source.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
@@ -241,8 +237,6 @@ struct ResolvedURLInvalidationTests {
     @Test("a permanent 509 pays the rate-limit ladder and gives up cleanly",
           .timeLimit(.minutes(2)))
     func permanent509TakesTheRateLimitLadder() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 256 * 1024
         let cdnMaybe = ThrottledOriginServer(
@@ -262,7 +256,7 @@ struct ResolvedURLInvalidationTests {
         defer { source.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(source.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
@@ -301,8 +295,6 @@ struct ResolvedURLInvalidationTests {
     @Test("a 509 outliving the keep-pin grace re-resolves once through the source",
           .timeLimit(.minutes(2)))
     func stalePinned509HealsThroughTheSource() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 256 * 1024
         let leases = LeaseLatch()
@@ -328,7 +320,7 @@ struct ResolvedURLInvalidationTests {
         defer { source.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(source.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
@@ -364,8 +356,6 @@ struct ResolvedURLInvalidationTests {
     /// 20 generations across ~85 s, none of them counted).
     @Test("a draining window does not reset the rate-limit ladder", .timeLimit(.minutes(2)))
     func drainingWindowKeepsTheLadderCharged() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         let firstRange: Int64 = 2 * 1024 * 1024
         let cdnMaybe = ThrottledOriginServer(
@@ -385,7 +375,7 @@ struct ResolvedURLInvalidationTests {
         defer { source.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(source.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
@@ -428,12 +418,6 @@ struct ResolvedURLInvalidationTests {
     @Test("an idle pin is dropped by its FIRST refusal instead of riding out the grace",
           .timeLimit(.minutes(2)))
     func idlePinDropsOnTheFirstRefusal() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        AetherEngine.pinIdleSecondsForTesting = 0.2
-        defer {
-            AetherEngine.reconnectBackoffScaleForTesting = 1.0
-            AetherEngine.pinIdleSecondsForTesting = nil
-        }
 
         let leases = LeaseLatch()
         let gate = RefusalGate()
@@ -465,7 +449,7 @@ struct ResolvedURLInvalidationTests {
         // request already in flight is never re-offered to the origin's gate.
         let firstRange: Int64 = 1024 * 1024
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(source.port)/movie.bin")!,
-                                boundedInitialFetch: firstRange)
+                                boundedInitialFetch: firstRange, backoffScale: 0.02, pinIdleSeconds: 0.2)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 
diff --git a/Tests/AetherEngineTests/ServedFromMemoryProgressTests.swift b/Tests/AetherEngineTests/ServedFromMemoryProgressTests.swift
index 3e946e66f..4f8debe42 100644
--- a/Tests/AetherEngineTests/ServedFromMemoryProgressTests.swift
+++ b/Tests/AetherEngineTests/ServedFromMemoryProgressTests.swift
@@ -68,8 +68,6 @@ struct ServedFromMemoryProgressTests {
     @Test("a retained-span serve is not progress against a metered origin",
           .timeLimit(.minutes(2)))
     func retainedSpanServeDoesNotClearTheLadder() async throws {
-        AetherEngine.reconnectBackoffScaleForTesting = 0.02
-        defer { AetherEngine.reconnectBackoffScaleForTesting = 1.0 }
 
         // The first range ends here and every refill at the frontier is refused: the shape of an
         // origin that answers the range boundary and meters everything past it.
@@ -82,7 +80,7 @@ struct ServedFromMemoryProgressTests {
         defer { server.stop() }
 
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
-                                boundedInitialFetch: frontier)
+                                boundedInitialFetch: frontier, backoffScale: 0.02)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
 

From 76d77973ce0605c4dfad2f45b28fe2399eb01318 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 10:19:59 +0200
Subject: [PATCH 121/132] feat(audio): TrueHD Atmos from the stream's own
 channel presentation, split by object energy (#731)

The TrueHD path no longer mixes object signals into the layout. The
decoder discards the matrix interpolation values and carries the
stream's channel-based presentation (Dolby's 7.1 or 5.1 rendering of
the same mix) alongside each block; BedSplitter divides every bed
channel per STFT bin between the floor speakers it covers and the
heights, by where the objects' energy lies, bounded by the bed and
balanced per band towards a direct render. Elements are plain point
sources. A 5.1 bed covers a 7.1 layout's sides and rears.

The splitter's 2048-frame latency is drained before the encoder
restarts elsewhere and at end of input, so no audio is lost there.
AETHER_TRUEHD_REFERENCE_RENDER=1 keeps the exact decode and mix for
measurements.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/Spatial/BedSplitter.swift           | 628 ++++++++++++++++++
 .../Audio/Spatial/ObjectAudioDecoding.swift   |  11 +
 .../Audio/Spatial/ObjectAudioRenderer.swift   |  74 +++
 .../Audio/Spatial/ObjectMetadataHold.swift    |   8 +-
 .../Audio/Spatial/SpatialAudioBridge.swift    |  76 ++-
 .../Spatial/TrueHDObjectAudioDecoder.swift    |  49 +-
 .../Video/HLSVideoEngine+SpatialAudio.swift   |  23 +-
 7 files changed, 856 insertions(+), 13 deletions(-)
 create mode 100644 Sources/AetherEngine/Audio/Spatial/BedSplitter.swift

diff --git a/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift b/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
new file mode 100644
index 000000000..2a319ccfb
--- /dev/null
+++ b/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
@@ -0,0 +1,628 @@
+// Only with the TrueHDObjectAudio trait (off by default), which links LibTrueHD.
+#if TrueHDObjectAudio
+import Accelerate
+import Foundation
+
+/// Builds a `SpatialSpeakerLayout` bed out of a TrueHD stream's own channel-based presentation, the
+/// 7.1 (or 5.1) bed Dolby renders the same mix into, using the object presentation only to learn
+/// where its energy belongs.
+///
+/// Every output is a share of that bed: per STFT bin, each bed channel is divided between the floor
+/// speakers it covers and the heights, in proportion to how much of the bin's energy in that channel
+/// comes from elements at each place. An element's part in a bed channel is its spectral energy times
+/// its ear-level gain into the channel; it goes to the heights in proportion to its layout gains
+/// above ear level, the rest to the floor speakers the channel covers. No element signal reaches an
+/// output, so the elements only need to be right in where their energy lies, which an object
+/// presentation decoded without its matrix interpolation is.
+///
+/// Two corrections keep that estimate honest:
+/// - An element can hold no more energy than the bed channels it feeds carry (`boundMargin` times what
+///   its ear-level share of them allows). The decode without interpolation leaves a residue in quiet
+///   elements; bounded by the bed, it can no longer pull a quiet channel's content up or sideways.
+/// - Per output and band, the result is steered towards the energy the elements would give that
+///   output in a direct render (smoothed over about 200 ms, at most `balanceLimit` either way), which
+///   restores the spread a per-bin split loses where several elements share a bin.
+///
+/// The LFE is the bed's own, delayed alongside.
+///
+/// Streaming: output frame i is input frame i. The first `latency` frames after a reset produce no
+/// output, and `drain` returns the ones still inside.
+final class BedSplitter {
+    static let fftSize = 2048
+    static let hop = 512
+    static let latency = fftSize
+    static let boundMargin: Float = 2
+    static let boundMinShare: Float = 0.05
+    static let balanceSmoothing: Float = 0.95
+    static let balanceLimit: Float = 4
+
+    let layout: SpatialSpeakerLayout
+    let bedRoles: [ObjectAudioRole]
+
+    // MARK: Configuration
+
+    private let n = BedSplitter.fftSize
+    private let h = BedSplitter.hop
+    private let bins = BedSplitter.fftSize / 2 + 1
+    private let outputs: Int
+    private let lfeOutput: Int
+    /// Layout indices of the height speakers, and of the outputs that are split (all but the LFE).
+    private let heights: [Int]
+    private let positional: [Int]
+    /// Bed planes: the LFE, and the ones split onto the layout.
+    private let bedLFE: Int?
+    private let splitBeds: [Int]
+    /// Per split bed channel: its index in `bedPanner`'s layout (nil when the panner has no speaker
+    /// for it), and the pairs (`pairs` indices) of floor outputs it covers, its primary one first.
+    private let bedPannerIndex: [Int?]
+    private let pairsOfBed: [[Int]]
+    /// (split bed channel, floor output) for every floor output a bed channel covers.
+    private let pairs: [(bed: Int, output: Int)]
+    /// Pans a position into the bed's channels (ear level), and into the layout at ear level.
+    private let bedPanner: AllocentricPanner
+    private let layoutPanner: AllocentricPanner
+    private let bandEdges: [Int]
+
+    // MARK: State
+
+    private var elementCount = 0
+    private var elementHistory: [Float] = []
+    private var bedHistory: [Float]
+    private var elementHop: [Float] = []
+    private var bedHop: [Float]
+    private var filled = 0
+    private var accumulators: [Float]
+    private var lfeDelay: [Float]
+    /// The `h` frames being handed out during the current hop.
+    private var ready: [Float]
+    private var consumed: Int64 = 0
+    private var written: Int64 = 0
+
+    /// Per element: the position and gain its ear-level and bed gains were computed for.
+    private var cachedPosition: [SIMD3<Float>?] = []
+    private var cachedGain: [Float] = []
+    private var earGains: [Float] = []
+    private var bedGains: [Float] = []
+    private var snapshot = ObjectAudioGainSnapshot()
+    private var hasSnapshot = false
+    /// Element weights for the last three hops, the oldest used: a frame spans four hops, so its
+    /// centre lies two hops back from the newest input.
+    private var weightRing: [[Float]] = [[], [], []]
+    private var ringNewest = 0
+    private var ringCount = 0
+    private let weightStride: Int
+
+    private var smoothedTarget: [Float]
+    private var smoothedSplit: [Float]
+
+    // MARK: Scratch
+
+    private let window: [Float]
+    private let forward: vDSP_DFT_Setup
+    private let inverse: vDSP_DFT_Setup
+    private var frameBuf: [Float]
+    private var evenBuf: [Float], oddBuf: [Float], specRe: [Float], specIm: [Float]
+    private var power: [Float], scratch: [Float]
+    private var bedRe: [Float], bedIm: [Float], bedPower: [Float]
+    private var den: [Float], floorNum: [Float], topNum: [Float], target: [Float]
+    private var outRe: [Float], outIm: [Float], expect: [Float]
+
+    init(layout: SpatialSpeakerLayout, bedRoles: [ObjectAudioRole]) {
+        self.layout = layout
+        self.bedRoles = bedRoles
+        let speakers = layout.speakers
+        outputs = speakers.count
+        lfeOutput = layout.lfeIndex
+        heights = speakers.indices.filter { speakers[$0].isHeight }
+        positional = speakers.indices.filter { $0 != layout.lfeIndex }
+        let floor = speakers.indices.filter { !speakers[$0].isHeight && $0 != layout.lfeIndex }
+
+        bedLFE = bedRoles.firstIndex(of: .lfe)
+        let beds: [(plane: Int, speaker: SpatialSpeaker?, position: SIMD3<Float>)] = bedRoles.indices.compactMap { i in
+            switch bedRoles[i] {
+            case .bed(let s) where !s.isHeight: return (i, s, s.position)
+            case .fixed(let p) where p.z == 0: return (i, nil, p)
+            default: return nil
+            }
+        }
+        splitBeds = beds.map(\.plane)
+        let bedLayout = SpatialSpeakerLayout.l916
+        let bedSpeakers = Set(beds.compactMap(\.speaker))
+        bedPanner = AllocentricPanner(
+            layout: bedLayout, excluded: Set(bedLayout.speakers.filter { !bedSpeakers.contains($0) }))
+        bedPannerIndex = beds.map { bed in bed.speaker.flatMap { bedLayout.speakers.firstIndex(of: $0) } }
+        layoutPanner = AllocentricPanner(layout: layout)
+
+        // A floor output takes the bed channels nearest to it; a bed channel no output is nearest to
+        // goes to the outputs nearest to it. So a 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's
+        // surrounds cover a 7.1 layout's sides and rears, and a 7.1 bed's rears fold onto a 5.1 floor.
+        func distance(_ a: SIMD3<Float>, _ b: SIMD3<Float>) -> Float {
+            let d = SIMD2(a.x - b.x, a.y - b.y)
+            return (d * d).sum()
+        }
+        var covered = [[Int]](repeating: [], count: beds.count)
+        for o in floor {
+            let p = speakers[o].position
+            let distances = beds.map { distance($0.position, p) }
+            guard let best = distances.min() else { continue }
+            for (j, d) in distances.enumerated() where d <= best + 1e-6 { covered[j].append(o) }
+        }
+        for j in beds.indices where covered[j].isEmpty {
+            let distances = floor.map { distance(beds[j].position, speakers[$0].position) }
+            guard let best = distances.min() else { continue }
+            covered[j] = floor.indices.filter { distances[$0] <= best + 1e-6 }.map { floor[$0] }
+        }
+        // The primary output (first) is the nearest one, where a bed channel no element explains goes.
+        var pairs: [(bed: Int, output: Int)] = []
+        var pairsOfBed = [[Int]](repeating: [], count: beds.count)
+        for j in beds.indices {
+            let sorted = covered[j].sorted { distance(beds[j].position, speakers[$0].position)
+                < distance(beds[j].position, speakers[$1].position) }
+            for o in sorted {
+                pairsOfBed[j].append(pairs.count)
+                pairs.append((j, o))
+            }
+        }
+        self.pairs = pairs
+        self.pairsOfBed = pairsOfBed
+
+        var edges: [Int] = []
+        for i in 0...24 {
+            let e = Int(pow(Double(n / 2 + 1), Double(i) / 24).rounded())
+            if edges.last != e { edges.append(e) }
+        }
+        edges[0] = 0
+        bandEdges = edges
+
+        // Per element: layout g² (outputs), its total over the positional outputs, its bed shares
+        // (split beds), floor share per pair, top share per height.
+        weightStride = outputs + 1 + beds.count + pairs.count + heights.count
+
+        var w = [Float](repeating: 0, count: n)
+        for i in 0..<n { w[i] = 0.5 - 0.5 * cos(2 * .pi * Float(i) / Float(n)) }
+        window = w
+        forward = vDSP_DFT_zrop_CreateSetup(nil, vDSP_Length(n), .FORWARD)!
+        inverse = vDSP_DFT_zrop_CreateSetup(forward, vDSP_Length(n), .INVERSE)!
+        let bedPlanes = bedRoles.count
+        bedHistory = [Float](repeating: 0, count: bedPlanes * n)
+        bedHop = [Float](repeating: 0, count: bedPlanes * h)
+        accumulators = [Float](repeating: 0, count: outputs * n)
+        lfeDelay = [Float](repeating: 0, count: n)
+        ready = [Float](repeating: 0, count: outputs * h)
+        frameBuf = [Float](repeating: 0, count: n)
+        evenBuf = [Float](repeating: 0, count: n / 2)
+        oddBuf = evenBuf; specRe = evenBuf; specIm = evenBuf
+        power = [Float](repeating: 0, count: bins)
+        scratch = power
+        bedRe = [Float](repeating: 0, count: beds.count * bins)
+        bedIm = bedRe; bedPower = bedRe; den = bedRe
+        floorNum = [Float](repeating: 0, count: pairs.count * bins)
+        topNum = [Float](repeating: 0, count: beds.count * heights.count * bins)
+        target = [Float](repeating: 0, count: outputs * bins)
+        outRe = target; outIm = target; expect = target
+        smoothedTarget = [Float](repeating: 0, count: outputs * bandEdges.count)
+        smoothedSplit = smoothedTarget
+    }
+
+    deinit {
+        vDSP_DFT_DestroySetup(forward)
+        vDSP_DFT_DestroySetup(inverse)
+    }
+
+    /// Input frames taken that have not come out yet.
+    var backlog: Int { Int(consumed - written) }
+
+    /// Forget everything: the next input starts a new stream (a seek, a restart).
+    func reset() {
+        for i in elementHistory.indices { elementHistory[i] = 0 }
+        for i in bedHistory.indices { bedHistory[i] = 0 }
+        for i in accumulators.indices { accumulators[i] = 0 }
+        for i in lfeDelay.indices { lfeDelay[i] = 0 }
+        for i in ready.indices { ready[i] = 0 }
+        for i in smoothedTarget.indices { smoothedTarget[i] = 0; smoothedSplit[i] = 0 }
+        cachedPosition = Array(repeating: nil, count: elementCount)
+        ringCount = 0
+        hasSnapshot = false
+        filled = 0
+        consumed = 0
+        written = 0
+    }
+
+    /// The elements' gains and positions from here on (`ObjectAudioRenderer.snapshot`).
+    func setGains(_ source: ObjectAudioGainSnapshot) {
+        snapshot = source
+        hasSnapshot = true
+    }
+
+    /// Takes `frameCount` frames of elements and bed (nil for silence) and writes the output frames
+    /// that are complete into `output` (one plane per layout channel), returning how many.
+    @discardableResult
+    func process(elements: [UnsafePointer<Float>]?, bed: [UnsafePointer<Float>]?, frameCount: Int,
+                 output: [UnsafeMutablePointer<Float>]) -> Int {
+        let count = elements?.count ?? elementCount
+        if count != elementCount { resizeElements(count) }
+        var taken = 0
+        var out = 0
+        while taken < frameCount {
+            let take = min(h - filled, frameCount - taken)
+            for c in 0..<elementCount {
+                let dst = c * h + filled
+                if let elements { elementHop.withUnsafeMutableBufferPointer { (($0.baseAddress! + dst)).update(from: elements[c] + taken, count: take) } }
+                else { elementHop.withUnsafeMutableBufferPointer { ($0.baseAddress! + dst).update(repeating: 0, count: take) } }
+            }
+            for c in 0..<bedRoles.count {
+                let dst = c * h + filled
+                if let bed, c < bed.count { bedHop.withUnsafeMutableBufferPointer { ($0.baseAddress! + dst).update(from: bed[c] + taken, count: take) } }
+                else { bedHop.withUnsafeMutableBufferPointer { ($0.baseAddress! + dst).update(repeating: 0, count: take) } }
+            }
+            // Output for these frames: `ready` holds the hop that came out of the last full frame.
+            let skip = Int(max(0, min(Int64(take), Int64(Self.latency) - consumed)))
+            if take > skip {
+                for c in 0..<outputs {
+                    ready.withUnsafeBufferPointer {
+                        (output[c] + out).update(from: $0.baseAddress! + c * h + filled + skip, count: take - skip)
+                    }
+                }
+                out += take - skip
+            }
+            consumed += Int64(take)
+            filled += take
+            taken += take
+            if filled == h {
+                filled = 0
+                processHop()
+            }
+        }
+        written += Int64(out)
+        return out
+    }
+
+    /// Writes the frames still inside (at most `latency`) into `output` and returns how many. The
+    /// splitter is reset afterwards.
+    func drain(output: [UnsafeMutablePointer<Float>]) -> Int {
+        let pending = backlog
+        guard pending > 0 else { reset(); return 0 }
+        var out = 0
+        var remaining = Self.latency
+        var cursor = output
+        while remaining > 0, out < pending {
+            let step = min(remaining, h)
+            let got = process(elements: nil, bed: nil, frameCount: step, output: cursor)
+            let keep = min(got, pending - out)
+            out += keep
+            cursor = cursor.map { $0 + keep }
+            remaining -= step
+        }
+        reset()
+        return out
+    }
+
+    private func resizeElements(_ count: Int) {
+        elementCount = count
+        elementHistory = [Float](repeating: 0, count: count * n)
+        elementHop = [Float](repeating: 0, count: count * h)
+        cachedPosition = Array(repeating: nil, count: count)
+        cachedGain = [Float](repeating: 0, count: count)
+        earGains = [Float](repeating: 0, count: count * outputs)
+        bedGains = [Float](repeating: 0, count: count * bedPanner.layout.channelCount)
+        for i in weightRing.indices { weightRing[i] = [Float](repeating: 0, count: count * weightStride) }
+        ringCount = 0
+    }
+
+    // MARK: - Hop
+
+    private func processHop() {
+        shiftIn(&elementHistory, from: elementHop, channels: elementCount)
+        shiftIn(&bedHistory, from: bedHop, channels: bedRoles.count)
+        pushWeights()
+        let weights = weightRing[(ringNewest + 3 - (ringCount - 1)) % 3]
+        split(weights: ringCount > 0 ? weights : nil)
+        emitHop()
+    }
+
+    private func shiftIn(_ history: inout [Float], from hopBuffer: [Float], channels: Int) {
+        let n = self.n, h = self.h
+        history.withUnsafeMutableBufferPointer { hist in
+            hopBuffer.withUnsafeBufferPointer { hop in
+                for c in 0..<channels {
+                    let p = hist.baseAddress! + c * n
+                    p.update(from: p + h, count: n - h)
+                    (p + n - h).update(from: hop.baseAddress! + c * h, count: h)
+                }
+            }
+        }
+    }
+
+    /// Derive this hop's element weights from the latest gains and push them on the ring.
+    private func pushWeights() {
+        guard hasSnapshot, snapshot.positions.count == elementCount,
+              snapshot.layoutGains.count == elementCount * outputs else { return }
+        ringNewest = (ringNewest + 1) % 3
+        ringCount = min(ringCount + 1, 3)
+        let bedChannels = bedPanner.layout.channelCount
+        var ear = [Float](repeating: 0, count: outputs)
+        var bedRow = [Float](repeating: 0, count: bedChannels)
+        weightRing[ringNewest].withUnsafeMutableBufferPointer { w in
+            for k in 0..<elementCount {
+                let base = k * weightStride
+                for i in 0..<weightStride { w[base + i] = 0 }
+                guard let position = snapshot.positions[k] else { continue }
+                let gain = snapshot.gains[k]
+                if cachedPosition[k] != position || cachedGain[k] != gain {
+                    cachedPosition[k] = position
+                    cachedGain[k] = gain
+                    let floor = SIMD3(position.x, position.y, 0)
+                    for i in ear.indices { ear[i] = 0 }
+                    layoutPanner.pointGains(floor, into: &ear)
+                    for i in bedRow.indices { bedRow[i] = 0 }
+                    bedPanner.pointGains(floor, into: &bedRow)
+                    for i in 0..<outputs { earGains[k * outputs + i] = ear[i] * gain }
+                    for i in 0..<bedChannels { bedGains[k * bedChannels + i] = bedRow[i] * gain }
+                }
+                var total: Float = 0
+                for c in positional {
+                    let g = snapshot.layoutGains[k * outputs + c]
+                    w[base + c] = g * g
+                    total += g * g
+                }
+                guard total > 0 else { continue }
+                w[base + outputs] = total
+                var above: Float = 0
+                let tops = base + outputs + 1 + splitBeds.count + pairs.count
+                for (t, c) in heights.enumerated() {
+                    w[tops + t] = w[base + c] / total
+                    above += w[tops + t]
+                }
+                let shares = base + outputs + 1
+                for j in splitBeds.indices {
+                    if let i = bedPannerIndex[j] {
+                        let g = bedGains[k * bedChannels + i]
+                        w[shares + j] = g * g
+                    }
+                }
+                let floorShares = shares + splitBeds.count
+                for j in splitBeds.indices {
+                    var sum: Float = 0
+                    for p in pairsOfBed[j] { let e = earGains[k * outputs + pairs[p].output]; sum += e * e }
+                    for (rank, p) in pairsOfBed[j].enumerated() {
+                        let e = earGains[k * outputs + pairs[p].output]
+                        let share = sum > 0 ? e * e / sum : (rank == 0 ? 1 : 0)
+                        w[floorShares + p] = share * (1 - above)
+                    }
+                }
+            }
+        }
+    }
+
+    /// Windowed real FFT of `n` frames at `source`, into `specRe`/`specIm` (zrop packing).
+    private func spectrum(_ source: UnsafePointer<Float>) {
+        frameBuf.withUnsafeMutableBufferPointer { f in
+            vDSP_vmul(source, 1, window, 1, f.baseAddress!, 1, vDSP_Length(n))
+        }
+        frameBuf.withUnsafeBufferPointer { f in
+            evenBuf.withUnsafeMutableBufferPointer { e in
+                oddBuf.withUnsafeMutableBufferPointer { o in
+                    f.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: n / 2) { c in
+                        var split = DSPSplitComplex(realp: e.baseAddress!, imagp: o.baseAddress!)
+                        vDSP_ctoz(c, 2, &split, 1, vDSP_Length(n / 2))
+                    }
+                }
+            }
+        }
+        vDSP_DFT_Execute(forward, evenBuf, oddBuf, &specRe, &specIm)
+    }
+
+    /// Unpack `specRe`/`specIm` into `bins` real and imaginary values at `re`/`im`.
+    private func unpack(re: UnsafeMutablePointer<Float>, im: UnsafeMutablePointer<Float>) {
+        let half = n / 2
+        specRe.withUnsafeBufferPointer { r in
+            specIm.withUnsafeBufferPointer { i in
+                re.update(from: r.baseAddress!, count: half)
+                im.update(from: i.baseAddress!, count: half)
+                re[half] = i[0]
+                im[0] = 0
+                im[half] = 0
+            }
+        }
+    }
+
+    private func split(weights: [Float]?) {
+        let bins = self.bins, B = splitBeds.count, H = heights.count
+        let nb = vDSP_Length(bins)
+        let tiny: Float = 1e-20
+
+        // Bed spectra and powers.
+        bedHistory.withUnsafeBufferPointer { hist in
+            bedRe.withUnsafeMutableBufferPointer { re in
+                bedIm.withUnsafeMutableBufferPointer { im in
+                    for j in 0..<B {
+                        spectrum(hist.baseAddress! + splitBeds[j] * n)
+                        unpack(re: re.baseAddress! + j * bins, im: im.baseAddress! + j * bins)
+                    }
+                }
+            }
+        }
+        bedPower.withUnsafeMutableBufferPointer { p in
+            vDSP_vmma(bedRe, 1, bedRe, 1, bedIm, 1, bedIm, 1, p.baseAddress!, 1, vDSP_Length(B * bins))
+        }
+        zero(&den); zero(&floorNum); zero(&topNum); zero(&target)
+
+        if let weights {
+            var re = [Float](repeating: 0, count: bins), im = re
+            for k in 0..<elementCount {
+                let base = k * weightStride
+                let total = weights[base + outputs]
+                let shares = base + outputs + 1
+                guard total > 0 else { continue }
+                var shareSum: Float = 0
+                for j in 0..<B { shareSum += weights[shares + j] }
+                guard shareSum > 0 else { continue }
+                elementHistory.withUnsafeBufferPointer { spectrum($0.baseAddress! + k * n) }
+                re.withUnsafeMutableBufferPointer { r in
+                    im.withUnsafeMutableBufferPointer { i in unpack(re: r.baseAddress!, im: i.baseAddress!) }
+                }
+                vDSP_vmma(re, 1, re, 1, im, 1, im, 1, &power, 1, nb)
+                // The bed bound, from every bed channel the element puts a real part of itself in.
+                for j in 0..<B where weights[shares + j] > Self.boundMinShare * shareSum {
+                    var scale = Self.boundMargin / weights[shares + j]
+                    bedPower.withUnsafeBufferPointer { vDSP_vsmul($0.baseAddress! + j * bins, 1, &scale, &scratch, 1, nb) }
+                    vDSP_vmin(power, 1, scratch, 1, &power, 1, nb)
+                }
+                target.withUnsafeMutableBufferPointer { t in
+                    for c in positional {
+                        var g = weights[base + c]
+                        if g > 0 { vDSP_vsma(power, 1, &g, t.baseAddress! + c * bins, 1, t.baseAddress! + c * bins, 1, nb) }
+                    }
+                }
+                let floorShares = shares + B
+                let tops = floorShares + pairs.count
+                for j in 0..<B {
+                    let a = weights[shares + j]
+                    if a == 0 { continue }
+                    var w = a
+                    den.withUnsafeMutableBufferPointer { vDSP_vsma(power, 1, &w, $0.baseAddress! + j * bins, 1, $0.baseAddress! + j * bins, 1, nb) }
+                    floorNum.withUnsafeMutableBufferPointer { f in
+                        for p in pairsOfBed[j] {
+                            var s = a * weights[floorShares + p]
+                            if s > 0 { vDSP_vsma(power, 1, &s, f.baseAddress! + p * bins, 1, f.baseAddress! + p * bins, 1, nb) }
+                        }
+                    }
+                    topNum.withUnsafeMutableBufferPointer { t in
+                        for ti in 0..<H {
+                            var s = a * weights[tops + ti]
+                            let row = (j * H + ti) * bins
+                            if s > 0 { vDSP_vsma(power, 1, &s, t.baseAddress! + row, 1, t.baseAddress! + row, 1, nb) }
+                        }
+                    }
+                }
+            }
+        }
+
+        // Each bed channel, split by those shares: a bin no element explains stays on the channel's
+        // primary floor output.
+        zero(&outRe); zero(&outIm); zero(&expect)
+        var eps = tiny
+        var dSafe = [Float](repeating: 0, count: bins), share = dSafe, gain = dSafe
+        for j in 0..<B {
+            den.withUnsafeBufferPointer { vDSP_vsadd($0.baseAddress! + j * bins, 1, &eps, &dSafe, 1, nb) }
+            func add(_ output: Int, num: UnsafePointer<Float>?, primary: Bool) {
+                if let num {
+                    if primary {
+                        vDSP_vsadd(num, 1, &eps, &share, 1, nb)
+                        vDSP_vdiv(dSafe, 1, share, 1, &share, 1, nb)
+                    } else {
+                        vDSP_vdiv(dSafe, 1, num, 1, &share, 1, nb)
+                    }
+                }
+                var count = Int32(bins)
+                vvsqrtf(&gain, share, &count)
+                let row = output * bins, bedRow = j * bins
+                outRe.withUnsafeMutableBufferPointer { o in
+                    bedRe.withUnsafeBufferPointer { vDSP_vma($0.baseAddress! + bedRow, 1, gain, 1, o.baseAddress! + row, 1, o.baseAddress! + row, 1, nb) }
+                }
+                outIm.withUnsafeMutableBufferPointer { o in
+                    bedIm.withUnsafeBufferPointer { vDSP_vma($0.baseAddress! + bedRow, 1, gain, 1, o.baseAddress! + row, 1, o.baseAddress! + row, 1, nb) }
+                }
+                expect.withUnsafeMutableBufferPointer { e in
+                    bedPower.withUnsafeBufferPointer { vDSP_vma($0.baseAddress! + bedRow, 1, share, 1, e.baseAddress! + row, 1, e.baseAddress! + row, 1, nb) }
+                }
+            }
+            floorNum.withUnsafeBufferPointer { f in
+                for (rank, p) in pairsOfBed[j].enumerated() {
+                    add(pairs[p].output, num: f.baseAddress! + p * bins, primary: rank == 0)
+                }
+            }
+            topNum.withUnsafeBufferPointer { t in
+                for (ti, c) in heights.enumerated() {
+                    add(c, num: t.baseAddress! + (j * H + ti) * bins, primary: false)
+                }
+            }
+        }
+
+        // An output fed by several bed channels sums them coherently; set each bin's energy to the
+        // shares' sum.
+        for c in positional {
+            let row = c * bins
+            for b in 0..<bins {
+                let got = outRe[row + b] * outRe[row + b] + outIm[row + b] * outIm[row + b]
+                let fix: Float = got > tiny ? (expect[row + b] / got).squareRoot() : 1
+                outRe[row + b] *= fix
+                outIm[row + b] *= fix
+            }
+        }
+
+        // Balance per output and band, towards the energy a direct render would give it.
+        let a = Self.balanceSmoothing, bands = bandEdges.count
+        for band in 0..<(bands - 1) {
+            let lo = bandEdges[band], hi = min(bandEdges[band + 1], bins)
+            guard lo < hi else { continue }
+            for c in positional {
+                var t: Float = 0, e: Float = 0
+                let row = c * bins
+                for b in lo..<hi { t += target[row + b]; e += expect[row + b] }
+                let slot = c * bands + band
+                smoothedTarget[slot] = a * smoothedTarget[slot] + (1 - a) * t
+                smoothedSplit[slot] = a * smoothedSplit[slot] + (1 - a) * e
+                let st = smoothedTarget[slot], se = smoothedSplit[slot]
+                guard st > tiny, se > tiny else { continue }
+                let g = min(max(st / se, 1 / Self.balanceLimit), Self.balanceLimit).squareRoot()
+                for b in lo..<hi { outRe[row + b] *= g; outIm[row + b] *= g }
+            }
+        }
+
+        // Back to the time domain, overlap-added.
+        let half = n / 2
+        var scale = 1 / (2 * Float(n) * 1.5)
+        for c in positional {
+            let row = c * bins
+            outRe.withUnsafeBufferPointer { r in specRe.withUnsafeMutableBufferPointer { $0.baseAddress!.update(from: r.baseAddress! + row, count: half) } }
+            outIm.withUnsafeBufferPointer { i in specIm.withUnsafeMutableBufferPointer { $0.baseAddress!.update(from: i.baseAddress! + row, count: half) } }
+            specIm[0] = outRe[row + half]
+            vDSP_DFT_Execute(inverse, specRe, specIm, &evenBuf, &oddBuf)
+            evenBuf.withUnsafeMutableBufferPointer { e in
+                oddBuf.withUnsafeMutableBufferPointer { o in
+                    frameBuf.withUnsafeMutableBufferPointer { f in
+                        f.baseAddress!.withMemoryRebound(to: DSPComplex.self, capacity: half) { cplx in
+                            var s = DSPSplitComplex(realp: e.baseAddress!, imagp: o.baseAddress!)
+                            vDSP_ztoc(&s, 1, cplx, 2, vDSP_Length(half))
+                        }
+                    }
+                }
+            }
+            vDSP_vmul(frameBuf, 1, window, 1, &frameBuf, 1, vDSP_Length(n))
+            accumulators.withUnsafeMutableBufferPointer { acc in
+                vDSP_vsma(frameBuf, 1, &scale, acc.baseAddress! + c * n, 1, acc.baseAddress! + c * n, 1, vDSP_Length(n))
+            }
+        }
+    }
+
+    /// The oldest hop of every accumulator, and the LFE `latency` back, into `ready`.
+    private func emitHop() {
+        let n = self.n, h = self.h
+        ready.withUnsafeMutableBufferPointer { r in
+            accumulators.withUnsafeMutableBufferPointer { acc in
+                for c in positional {
+                    let a = acc.baseAddress! + c * n
+                    (r.baseAddress! + c * h).update(from: a, count: h)
+                    a.update(from: a + h, count: n - h)
+                    (a + n - h).update(repeating: 0, count: h)
+                }
+            }
+            lfeDelay.withUnsafeMutableBufferPointer { d in
+                let p = d.baseAddress!
+                (r.baseAddress! + lfeOutput * h).update(from: p, count: h)
+                p.update(from: p + h, count: n - h)
+                if let bedLFE {
+                    bedHistory.withUnsafeBufferPointer { (p + n - h).update(from: $0.baseAddress! + bedLFE * n + n - h, count: h) }
+                } else {
+                    (p + n - h).update(repeating: 0, count: h)
+                }
+            }
+        }
+    }
+
+    private func zero(_ a: inout [Float]) {
+        a.withUnsafeMutableBufferPointer { vDSP_vclr($0.baseAddress!, 1, vDSP_Length($0.count)) }
+    }
+}
+#endif
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
index bbe3fc29b..6d436161c 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
@@ -21,6 +21,17 @@ struct ObjectAudioDecodedBlock {
     var planes: [UnsafePointer<Float>]
     /// Metadata taking effect inside this block, sorted by frame offset.
     var updates: [ObjectAudioMetadataUpdate]
+    /// The stream's channel-based presentation of the same frames (Dolby's own 7.1 or 5.1 rendering
+    /// of the mix), when the decoder carries one: see `BedSplitter`.
+    var bed: ObjectAudioBed?
+}
+
+/// A channel bed decoded alongside an object presentation, sample-aligned with it.
+struct ObjectAudioBed {
+    /// One per plane: `.bed`, `.fixed` or `.lfe`, never `.object`.
+    var roles: [ObjectAudioRole]
+    /// `frameCount` frames each, borrowed like the block's planes.
+    var planes: [UnsafePointer<Float>]
 }
 
 /// A decoder that turns an object-audio bitstream (TrueHD with Atmos, DTS:X) into signals plus the
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift
index 4d1ab1701..4d95d0f24 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioRenderer.swift
@@ -45,6 +45,21 @@ struct ObjectAudioMetadataUpdate: Sendable {
     var states: [ObjectAudioElementState?]
 }
 
+/// Element gains and positions as `ObjectAudioRenderer.snapshot` reads them, reused across blocks.
+struct ObjectAudioGainSnapshot {
+    var layoutGains: [Float] = []
+    var positions: [SIMD3<Float>?] = []
+    var gains: [Float] = []
+
+    mutating func resize(elements: Int, channels: Int) {
+        if layoutGains.count != elements * channels { layoutGains = [Float](repeating: 0, count: elements * channels) }
+        if positions.count != elements {
+            positions = Array(repeating: nil, count: elements)
+            gains = [Float](repeating: 0, count: elements)
+        }
+    }
+}
+
 /// Renders object audio (beds + dynamic objects + metadata) into a `SpatialSpeakerLayout` bed.
 ///
 /// Gains are computed once per metadata update and interpolated linearly across each update's
@@ -68,6 +83,9 @@ final class ObjectAudioRenderer {
     /// from, and ramping from silence would fade every object in after each seek.
     private var hasMetadata: [Bool]
 
+    /// Each object's latest state, for `snapshot`.
+    private var objectStates: [ObjectAudioElementState?]
+
     private var scratch: [Float] = []
     private var rampScratch: [Float] = []
 
@@ -80,6 +98,7 @@ final class ObjectAudioRenderer {
         rampRemaining = Array(repeating: 0, count: roles.count)
         rampTotal = rampRemaining
         hasMetadata = Array(repeating: false, count: roles.count)
+        objectStates = Array(repeating: nil, count: roles.count)
         // Beds and LFE have gains the moment the renderer exists; objects wait for metadata and are
         // silent until their first update, rather than guessing at a position. The TrueHD decoder
         // holds the blocks before that update and gives the first of them its state at frame 0
@@ -96,6 +115,7 @@ final class ObjectAudioRenderer {
         for index in roles.indices {
             rampRemaining[index] = 0
             hasMetadata[index] = false
+            objectStates[index] = nil
             if roles[index] == .object {
                 for c in current[index].indices { current[index][c] = 0 }
             } else {
@@ -154,12 +174,66 @@ final class ObjectAudioRenderer {
         for update in pending { apply(update) }
     }
 
+    /// Take `frameCount` frames of metadata and ramps forward without mixing any audio: what
+    /// `render` does to the gains, for a caller that reads them through `snapshot` instead.
+    func advance(frameCount: Int, updates: [ObjectAudioMetadataUpdate]) {
+        var cursor = 0
+        var pending = updates[...]
+        while cursor < frameCount {
+            while let next = pending.first, next.frameOffset <= cursor {
+                apply(next)
+                pending = pending.dropFirst()
+            }
+            let end = min(frameCount, pending.first?.frameOffset ?? frameCount)
+            for index in roles.indices where rampRemaining[index] > 0 {
+                rampRemaining[index] -= min(rampRemaining[index], end - cursor)
+                if rampRemaining[index] == 0 { current[index] = target[index] }
+            }
+            cursor = end
+        }
+        for update in pending { apply(update) }
+    }
+
+    /// Every element's gains towards the layout as they stand now (mid-ramp included), and where
+    /// it sits: `layoutGains` holds `roles.count` rows of `layout.channelCount`; `positions` is nil
+    /// for the LFE and for an object without metadata yet; `gains` is the element gain.
+    func snapshot(into snapshot: inout ObjectAudioGainSnapshot) {
+        let channels = layout.channelCount
+        snapshot.resize(elements: roles.count, channels: channels)
+        for index in roles.indices {
+            let row = index * channels
+            if rampRemaining[index] > 0 {
+                let t = Float(rampTotal[index] - rampRemaining[index]) / Float(rampTotal[index])
+                for c in 0..<channels {
+                    snapshot.layoutGains[row + c] = current[index][c] + (target[index][c] - current[index][c]) * t
+                }
+            } else {
+                for c in 0..<channels { snapshot.layoutGains[row + c] = current[index][c] }
+            }
+            switch roles[index] {
+            case .object:
+                snapshot.positions[index] = objectStates[index]?.position
+                snapshot.gains[index] = objectStates[index]?.gain ?? 0
+            case .bed(let speaker):
+                snapshot.positions[index] = speaker.position
+                snapshot.gains[index] = 1
+            case .fixed(let position):
+                snapshot.positions[index] = position
+                snapshot.gains[index] = 1
+            case .lfe:
+                snapshot.positions[index] = nil
+                snapshot.gains[index] = 0
+            }
+        }
+    }
+
     // MARK: - Metadata
 
     private func apply(_ update: ObjectAudioMetadataUpdate) {
         let count = min(update.states.count, roles.count)
         for index in 0..<count {
             guard let state = update.states[index] else { continue }
+            if roles[index] == .object { objectStates[index] = state }
             let jump = update.rampFrames <= 0 || !hasMetadata[index]
             hasMetadata[index] = true
             var gains = [Float](repeating: 0, count: layout.channelCount)
diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift b/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift
index dd756c359..9b9ecb5bf 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectMetadataHold.swift
@@ -26,13 +26,19 @@ final class ObjectMetadataHold {
 
         init(_ source: ObjectAudioDecodedBlock) {
             let frames = source.frameCount
-            storage = .allocate(capacity: max(1, source.planes.count * frames))
+            let bedPlanes = source.bed?.planes ?? []
+            storage = .allocate(capacity: max(1, (source.planes.count + bedPlanes.count) * frames))
             block = source
             block.planes = source.planes.enumerated().map { channel, plane in
                 let copy = storage + channel * frames
                 copy.update(from: plane, count: frames)
                 return UnsafePointer(copy)
             }
+            block.bed?.planes = bedPlanes.enumerated().map { channel, plane in
+                let copy = storage + (source.planes.count + channel) * frames
+                copy.update(from: plane, count: frames)
+                return UnsafePointer(copy)
+            }
         }
 
         deinit { storage.deallocate() }
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
index ba4817a5a..3743547bb 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
@@ -61,6 +61,20 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
     /// `encodeChunkFrames` at a time (see `APACEncodePipeline`).
     private var output: APACEncodePipeline.PlaneBuffer
     private var pendingFrames = 0
+#if TrueHDObjectAudio
+    /// Built from the first block that carries a bed: every output comes from that bed instead of
+    /// the renderer's mix (see `BedSplitter`). Its latency is the frames it holds, `backlog`.
+    private var splitter: BedSplitter?
+    private var gainSnapshot = ObjectAudioGainSnapshot()
+#endif
+    /// Frames taken from the decoder that have not reached `output` yet.
+    private var heldBack: Int {
+#if TrueHDObjectAudio
+        splitter?.backlog ?? 0
+#else
+        0
+#endif
+    }
     private static let encodeChunkFrames = 2048
 
     /// Timeline, in 48 kHz frames on the output time base.
@@ -287,6 +301,7 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         var results: [UnsafeMutablePointer<AVPacket>] = []
         // Audio the decoder held back for metadata that never came plays as it is.
         renderHeldBlocks(into: &results)
+        drainSplitter()
         encodePending()
         logLevels(levelMeter.restart())
         let finished = pipeline.finish()
@@ -303,6 +318,9 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         defer { opLock.unlock() }
         decoder.reset()
         renderer?.reset()
+#if TrueHDObjectAudio
+        splitter?.reset()
+#endif
         pipeline.reset()
         limiter.reset()
         logLevels(levelMeter.restart())
@@ -384,20 +402,52 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         } else if reanchorPending, let start = encoderStartFrame {
             // After the decoder's own reset: put this block where the source says it plays.
             reanchorPending = false
-            let target = (originFrame ?? start + encoderFramesIn + Int64(pendingFrames)) + block.inputFrameOffset
+            let target = (originFrame ?? start + encoderFramesIn + Int64(pendingFrames + heldBack))
+                + block.inputFrameOffset
             place(at: target)
         } else if let expected = nextExpectedInputOffset, block.inputFrameOffset > expected,
                   let start = encoderStartFrame {
-            let end = start + encoderFramesIn + Int64(pendingFrames)
+            let end = start + encoderFramesIn + Int64(pendingFrames + heldBack)
             place(at: end + (block.inputFrameOffset - expected))
         }
         nextExpectedInputOffset = block.inputFrameOffset + Int64(block.frameCount)
 
         output.ensureCapacity(pendingFrames + block.frameCount, keeping: pendingFrames)
+#if TrueHDObjectAudio
+        if let bed = block.bed {
+            if splitter?.bedRoles != bed.roles {
+                drainSplitter()
+                output.ensureCapacity(pendingFrames + block.frameCount, keeping: pendingFrames)
+                splitter = BedSplitter(layout: layout, bedRoles: bed.roles)
+                EngineLog.emit(
+                    "[SpatialAudioBridge] every output from the stream's \(bed.roles.count)-channel presentation, "
+                    + "split by the objects' energy (latency \(BedSplitter.latency) frames)",
+                    category: .session)
+            }
+            renderer!.advance(frameCount: block.frameCount, updates: block.updates)
+            renderer!.snapshot(into: &gainSnapshot)
+            splitter!.setGains(gainSnapshot)
+            pendingFrames += splitter!.process(
+                elements: block.planes, bed: bed.planes, frameCount: block.frameCount,
+                output: output.planes.map { $0 + pendingFrames })
+        } else if let splitter {
+            // A block without its bed in a stream that has one: silence on the bed's timeline.
+            renderer!.advance(frameCount: block.frameCount, updates: block.updates)
+            pendingFrames += splitter.process(
+                elements: nil, bed: nil, frameCount: block.frameCount,
+                output: output.planes.map { $0 + pendingFrames })
+        } else {
+            renderer!.render(
+                inputs: block.planes, frameCount: block.frameCount, updates: block.updates,
+                outputs: output.planes.map { $0 + pendingFrames })
+            pendingFrames += block.frameCount
+        }
+#else
         renderer!.render(
             inputs: block.planes, frameCount: block.frameCount, updates: block.updates,
             outputs: output.planes.map { $0 + pendingFrames })
         pendingFrames += block.frameCount
+#endif
         stats.samplesEnqueued += Int64(block.frameCount)
         stats.packetsFedSinceLastEnqueue = 0
         if pendingFrames >= Self.encodeChunkFrames { encodePending() }
@@ -408,13 +458,14 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
     /// later packet keeps its source position.
     private func place(at target: Int64) {
         guard let start = encoderStartFrame else { return }
-        let end = start + encoderFramesIn + Int64(pendingFrames)
+        let end = start + encoderFramesIn + Int64(pendingFrames + heldBack)
         let gap = target - end
         if gap == 0 { return }
         if gap > 0, gap <= Int64(Self.maxSilenceFillFrames) {
             encodeSilence(frames: Int(gap))
             return
         }
+        drainSplitter()
         encodePending()
         pipeline.restart()
         limiter.reset()
@@ -436,6 +487,15 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
             let n = min(remaining, max(Self.encodeChunkFrames - pendingFrames, 0))
             if n == 0 { encodePending(); continue }
             output.ensureCapacity(pendingFrames + n, keeping: pendingFrames)
+#if TrueHDObjectAudio
+            if let splitter {
+                pendingFrames += splitter.process(
+                    elements: nil, bed: nil, frameCount: n, output: output.planes.map { $0 + pendingFrames })
+                remaining -= n
+                if pendingFrames >= Self.encodeChunkFrames { encodePending() }
+                continue
+            }
+#endif
             for plane in output.planes { (plane + pendingFrames).update(repeating: 0, count: n) }
             pendingFrames += n
             remaining -= n
@@ -443,6 +503,16 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
         }
     }
 
+    /// The frames the splitter still holds, into `output`: before the encoder restarts somewhere else
+    /// or the input ends, so the audio up to there plays in full.
+    private func drainSplitter() {
+#if TrueHDObjectAudio
+        guard let splitter, splitter.backlog > 0 else { return }
+        output.ensureCapacity(pendingFrames + splitter.backlog, keeping: pendingFrames)
+        pendingFrames += splitter.drain(output: output.planes.map { $0 + pendingFrames })
+#endif
+    }
+
     /// Hand the rendered frames to the encoder's queue. Its packets come back through
     /// `collectEncoded` on a later call.
     private func encodePending() {
diff --git a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
index 1064456be..6af8bed72 100644
--- a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
@@ -7,6 +7,12 @@ import TrueHD
 /// a C API): lossless decode of presentation 3, which for an Atmos stream is the bed plus up to 15
 /// dynamic objects, together with the object audio metadata (OAMD) that positions them.
 ///
+/// With `splitsBed` (the engine's TrueHD path, see `BedSplitter`) the decode is a different one:
+/// the matrix interpolation values are discarded, so the object signals are approximate, every block
+/// also carries the stream's channel-based presentation (Dolby's own 7.1 or 5.1 rendering of the mix)
+/// from the same access unit, and elements are described as plain point sources: the bridge then
+/// takes every output from that bed and only reads where the objects' energy lies.
+///
 /// The library's coordinates are OAMD room coordinates (ETSI TS 103 420 4.2.1): x left→right and
 /// y front→back on 0...1, z −1 floor, 0 ear level, +1 ceiling. That is the renderer's own room
 /// model above ear level; home Atmos keeps objects at z ≥ 0, and anything below is clamped to the
@@ -23,17 +29,26 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
     private var roles: [ObjectAudioRole] = []
     private var rolesSerial: UInt32?
     private var planes: [UnsafePointer<Float>] = []
+    let splitsBed: Bool
+    private var bedRoles: [ObjectAudioRole] = []
+    private var bedRolesSerial: UInt32?
+    private var bedPlanes: [UnsafePointer<Float>] = []
     private(set) var selfResetCount = 0
     /// Blocks between a reset and the first metadata, so objects play from the first frame (see
     /// `ObjectMetadataHold`), and the released block last handed out, whose planes it owns.
     private let hold = ObjectMetadataHold()
     private var lent: ObjectMetadataHold.Copy?
 
-    init() throws {
+    init(splitsBed: Bool = true) throws {
         guard let handle = truehd_atmos_decoder_create(TRUEHD_ATMOS_PRESENTATION_HIGHEST) else {
             throw DecoderError(status: TRUEHD_ATMOS_ERR_INVALID_ARGUMENT, message: "create failed")
         }
         self.handle = handle
+        self.splitsBed = splitsBed
+        if splitsBed {
+            _ = truehd_atmos_decoder_set_bed_companion(handle, true)
+            _ = truehd_atmos_decoder_set_ignore_interpolation(handle, true)
+        }
     }
 
     deinit { truehd_atmos_decoder_destroy(handle) }
@@ -88,6 +103,18 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
         planes.removeAll(keepingCapacity: true)
         for c in 0..<channels { planes.append(UnsafePointer(block.channels[c]!)) }
 
+        var bed: ObjectAudioBed?
+        let bedChannels = Int(block.bed_channel_count)
+        if bedChannels > 0, let channels = block.bed_channels, let speakers = block.bed_speakers {
+            if bedRolesSerial != block.layout_serial || bedRoles.count != bedChannels {
+                bedRolesSerial = block.layout_serial
+                bedRoles = (0..<bedChannels).map { Self.role(forSpeaker: speakers[$0]) }
+            }
+            bedPlanes.removeAll(keepingCapacity: true)
+            for c in 0..<bedChannels { bedPlanes.append(UnsafePointer(channels[c]!)) }
+            bed = ObjectAudioBed(roles: bedRoles, planes: bedPlanes)
+        }
+
         var updates: [ObjectAudioMetadataUpdate] = []
         var firstStates: [ObjectAudioElementState?]?
         if block.flags & TRUEHD_ATMOS_BLOCK_METADATA_UPDATED != 0, let metadata = block.metadata {
@@ -95,13 +122,13 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
             let count = min(Int(md.element_count), channels)
             for u in 0..<Int(md.update_count) {
                 let update = md.updates[u]
-                if u == 0 { firstStates = (0..<count).map { Self.state(for: update.elements[$0]) } }
+                if u == 0 { firstStates = (0..<count).map { state(for: update.elements[$0]) } }
                 var states: [ObjectAudioElementState?] = []
                 states.reserveCapacity(count)
                 for e in 0..<count {
                     let element = update.elements[e]
                     states.append(element.flags & TRUEHD_ATMOS_ELEMENT_CHANGED != 0
-                                  ? Self.state(for: element) : nil)
+                                  ? state(for: element) : nil)
                 }
                 updates.append(ObjectAudioMetadataUpdate(
                     frameOffset: Int(update.frame_offset), rampFrames: Int(update.ramp_frames), states: states))
@@ -116,7 +143,8 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
             isDiscontinuity: block.flags & TRUEHD_ATMOS_BLOCK_DISCONTINUITY != 0,
             roles: roles,
             planes: planes,
-            updates: updates), firstStates)
+            updates: updates,
+            bed: bed), firstStates)
     }
 
     func reset() {
@@ -169,6 +197,19 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
         }
     }
 
+    private func state(for element: TrueHDAtmosElement) -> ObjectAudioElementState {
+        splitsBed ? Self.pointSource(for: element) : Self.state(for: element)
+    }
+
+    /// An element as a point at its position: no size, snap, zone exclusion, screen anchoring or
+    /// elevation switch. ISF elements, whose positions the library does not decode, sit in the room's
+    /// centre.
+    static func pointSource(for element: TrueHDAtmosElement) -> ObjectAudioElementState {
+        let active = element.flags & TRUEHD_ATMOS_ELEMENT_ACTIVE != 0
+        let p = element.kind == TRUEHD_ATMOS_ELEMENT_ISF ? (Float(0.5), Float(0.5), Float(0.5)) : element.position
+        return ObjectAudioElementState(position: SIMD3(p.0, p.1, max(0, p.2)), gain: active ? element.gain : 0)
+    }
+
     static func state(for element: TrueHDAtmosElement) -> ObjectAudioElementState {
         let active = element.flags & TRUEHD_ATMOS_ELEMENT_ACTIVE != 0
         var p = element.position
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index 3ab67b27f..e23797b92 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -3,6 +3,13 @@ import AetherLibavformat
 import AetherLibavcodec
 import AetherLibavutil
 
+/// Measurement only: with this environment variable set to 1, TrueHD Atmos is decoded exactly and
+/// its objects mixed into the layout, the rendering `BedSplitter` is compared against.
+enum TrueHDReferenceRender {
+    static let variable = "AETHER_TRUEHD_REFERENCE_RENDER"
+    static var isOn: Bool { ProcessInfo.processInfo.environment[variable] == "1" }
+}
+
 extension HLSVideoEngine {
 
     /// The object-audio format a source would be rendered as, before it is confirmed.
@@ -203,7 +210,7 @@ extension HLSVideoEngine {
             switch source {
             case .trueHDAtmos:
                 #if TrueHDObjectAudio
-                decoder = try TrueHDObjectAudioDecoder()
+                decoder = try TrueHDObjectAudioDecoder(splitsBed: !TrueHDReferenceRender.isOn)
                 #else
                 return nil
                 #endif
@@ -289,11 +296,17 @@ extension HLSVideoEngine {
                 : "DTS:X → APAC \(layout.rawValue)"
             audioDelivery = .bridged
             audioIsAPAC = true
+            let rendering: String
+            switch source {
+            case .trueHDAtmos where TrueHDReferenceRender.isOn:
+                rendering = "objects rendered into \(layout.rawValue) (reference render, \(TrueHDReferenceRender.variable))"
+            case .trueHDAtmos:
+                rendering = "channel presentation split into \(layout.rawValue) by the objects' energy"
+            case .dtsHDMasterAudio:
+                rendering = "bed, heights and objects rendered into \(layout.rawValue)"
+            }
             EngineLog.emit(
-                "[HLSVideoEngine] \(source.name): "
-                + (source == .trueHDAtmos ? "objects" : "bed, heights and objects")
-                + " rendered into \(layout.rawValue), delivered as \(bridge.hlsCodecs) (lossy; the lossless "
-                + (source == .trueHDAtmos ? "7.1 channel presentation" : "7.1 downmix") + " is not used)",
+                "[HLSVideoEngine] \(source.name): \(rendering), delivered as \(bridge.hlsCodecs) (lossy)",
                 category: .session
             )
             return producer

From f6c51f1658267d4fb9f4ceb7175da2dcc5914421 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 11:05:42 +0200
Subject: [PATCH 122/132] fix(audio): fuller heights from the bed splitter, its
 LFE on time (#731)

The bed bound now compares an element with its bed channels per band
instead of per bin: in a single bin Dolby's mix can hold less than one
element where several cancel, and the per-bin bound cut legitimate
height content there. The balance only raises an output towards the
direct-render estimate and never lowers it, since the elements'
energies add up to less than a mix of them wherever they carry the
same signal. Against the exact render on nine height-heavy windows of
five films the heights went from -0.61 to -0.20 dB, the median
misplaced energy from 0.54 to 0.38 %; on Unfold from 4.6 to 3.0 %,
worst second 9.9 to 6.8 %.

The LFE delay line was one hop longer than the split outputs' latency.

Bridge tests run with and without the stream's bed; BedSplitterTests
pin the split, the 5.1 bed on a 7.1 layout and the timeline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/Spatial/BedSplitter.swift           |  69 ++++---
 .../AetherEngineTests/BedSplitterTests.swift  | 168 ++++++++++++++++++
 .../SpatialAudioBridgeTests.swift             |  51 ++++--
 3 files changed, 252 insertions(+), 36 deletions(-)
 create mode 100644 Tests/AetherEngineTests/BedSplitterTests.swift

diff --git a/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift b/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
index 2a319ccfb..c8af16f2b 100644
--- a/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
+++ b/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
@@ -16,12 +16,15 @@ import Foundation
 /// presentation decoded without its matrix interpolation is.
 ///
 /// Two corrections keep that estimate honest:
-/// - An element can hold no more energy than the bed channels it feeds carry (`boundMargin` times what
-///   its ear-level share of them allows). The decode without interpolation leaves a residue in quiet
-///   elements; bounded by the bed, it can no longer pull a quiet channel's content up or sideways.
-/// - Per output and band, the result is steered towards the energy the elements would give that
-///   output in a direct render (smoothed over about 200 ms, at most `balanceLimit` either way), which
-///   restores the spread a per-bin split loses where several elements share a bin.
+/// - Per band, an element can hold no more energy than the bed channels it feeds carry (`boundMargin`
+///   times what its ear-level share of them allows). The decode without interpolation leaves a
+///   residue in quiet elements; bounded by the bed, it can no longer pull a quiet channel's content
+///   up or sideways.
+/// - Per output and band, an output the split leaves short of the energy the elements would give it
+///   in a direct render is raised towards it (smoothed over about 200 ms, at most `balanceLimit`),
+///   which restores the spread a per-bin split loses where several elements share a bin. It is never
+///   lowered: the elements' energies add up to less than a mix of them wherever they carry the same
+///   signal, so a target below the split is the estimate's shortfall, not the mix's.
 ///
 /// The LFE is the bed's own, delayed alongside.
 ///
@@ -104,6 +107,7 @@ final class BedSplitter {
     private var evenBuf: [Float], oddBuf: [Float], specRe: [Float], specIm: [Float]
     private var power: [Float], scratch: [Float]
     private var bedRe: [Float], bedIm: [Float], bedPower: [Float]
+    private var bedBandEnergy: [Float]
     private var den: [Float], floorNum: [Float], topNum: [Float], target: [Float]
     private var outRe: [Float], outIm: [Float], expect: [Float]
 
@@ -187,7 +191,7 @@ final class BedSplitter {
         bedHistory = [Float](repeating: 0, count: bedPlanes * n)
         bedHop = [Float](repeating: 0, count: bedPlanes * h)
         accumulators = [Float](repeating: 0, count: outputs * n)
-        lfeDelay = [Float](repeating: 0, count: n)
+        lfeDelay = [Float](repeating: 0, count: n - h)
         ready = [Float](repeating: 0, count: outputs * h)
         frameBuf = [Float](repeating: 0, count: n)
         evenBuf = [Float](repeating: 0, count: n / 2)
@@ -200,6 +204,7 @@ final class BedSplitter {
         topNum = [Float](repeating: 0, count: beds.count * heights.count * bins)
         target = [Float](repeating: 0, count: outputs * bins)
         outRe = target; outIm = target; expect = target
+        bedBandEnergy = [Float](repeating: 0, count: beds.count * bandEdges.count)
         smoothedTarget = [Float](repeating: 0, count: outputs * bandEdges.count)
         smoothedSplit = smoothedTarget
     }
@@ -446,6 +451,15 @@ final class BedSplitter {
             vDSP_vmma(bedRe, 1, bedRe, 1, bedIm, 1, bedIm, 1, p.baseAddress!, 1, vDSP_Length(B * bins))
         }
         zero(&den); zero(&floorNum); zero(&topNum); zero(&target)
+        let bands = bandEdges.count - 1
+        for j in 0..<B {
+            for band in 0..<bands {
+                let lo = bandEdges[band], hi = min(bandEdges[band + 1], bins)
+                var e: Float = 0
+                if lo < hi { bedPower.withUnsafeBufferPointer { vDSP_sve($0.baseAddress! + j * bins + lo, 1, &e, vDSP_Length(hi - lo)) } }
+                bedBandEnergy[j * bands + band] = e
+            }
+        }
 
         if let weights {
             var re = [Float](repeating: 0, count: bins), im = re
@@ -462,11 +476,23 @@ final class BedSplitter {
                     im.withUnsafeMutableBufferPointer { i in unpack(re: r.baseAddress!, im: i.baseAddress!) }
                 }
                 vDSP_vmma(re, 1, re, 1, im, 1, im, 1, &power, 1, nb)
-                // The bed bound, from every bed channel the element puts a real part of itself in.
-                for j in 0..<B where weights[shares + j] > Self.boundMinShare * shareSum {
-                    var scale = Self.boundMargin / weights[shares + j]
-                    bedPower.withUnsafeBufferPointer { vDSP_vsmul($0.baseAddress! + j * bins, 1, &scale, &scratch, 1, nb) }
-                    vDSP_vmin(power, 1, scratch, 1, &power, 1, nb)
+                // The bed bound, per band, from every bed channel the element puts a real part of
+                // itself in. Per band rather than per bin: in a single bin the bed can hold less than
+                // one element, where several cancel in Dolby's mix, and a per-bin bound cut those.
+                for band in 0..<bands {
+                    let lo = bandEdges[band], hi = min(bandEdges[band + 1], bins)
+                    guard lo < hi else { continue }
+                    var e: Float = 0
+                    vDSP_sve(power.withUnsafeBufferPointer { $0.baseAddress! + lo }, 1, &e, vDSP_Length(hi - lo))
+                    guard e > 0 else { continue }
+                    var limit = Float.infinity
+                    for j in 0..<B where weights[shares + j] > Self.boundMinShare * shareSum {
+                        limit = min(limit, Self.boundMargin * bedBandEnergy[j * bands + band] / weights[shares + j])
+                    }
+                    if e > limit {
+                        var f = limit / e
+                        power.withUnsafeMutableBufferPointer { vDSP_vsmul($0.baseAddress! + lo, 1, &f, $0.baseAddress! + lo, 1, vDSP_Length(hi - lo)) }
+                    }
                 }
                 target.withUnsafeMutableBufferPointer { t in
                     for c in positional {
@@ -498,6 +524,7 @@ final class BedSplitter {
             }
         }
 
+
         // Each bed channel, split by those shares: a bin no element explains stays on the channel's
         // primary floor output.
         zero(&outRe); zero(&outIm); zero(&expect)
@@ -551,9 +578,9 @@ final class BedSplitter {
             }
         }
 
-        // Balance per output and band, towards the energy a direct render would give it.
-        let a = Self.balanceSmoothing, bands = bandEdges.count
-        for band in 0..<(bands - 1) {
+        // Balance per output and band: raised towards the energy a direct render would give it.
+        let a = Self.balanceSmoothing
+        for band in 0..<bands {
             let lo = bandEdges[band], hi = min(bandEdges[band + 1], bins)
             guard lo < hi else { continue }
             for c in positional {
@@ -565,7 +592,7 @@ final class BedSplitter {
                 smoothedSplit[slot] = a * smoothedSplit[slot] + (1 - a) * e
                 let st = smoothedTarget[slot], se = smoothedSplit[slot]
                 guard st > tiny, se > tiny else { continue }
-                let g = min(max(st / se, 1 / Self.balanceLimit), Self.balanceLimit).squareRoot()
+                let g = min(max(st / se, 1), Self.balanceLimit).squareRoot()
                 for b in lo..<hi { outRe[row + b] *= g; outIm[row + b] *= g }
             }
         }
@@ -608,14 +635,16 @@ final class BedSplitter {
                     (a + n - h).update(repeating: 0, count: h)
                 }
             }
+            // The newest hop enters `n - h` back and leaves three hops later, for the hop after
+            // that: `latency` frames, like the split outputs.
             lfeDelay.withUnsafeMutableBufferPointer { d in
-                let p = d.baseAddress!
+                let p = d.baseAddress!, length = n - h
                 (r.baseAddress! + lfeOutput * h).update(from: p, count: h)
-                p.update(from: p + h, count: n - h)
+                p.update(from: p + h, count: length - h)
                 if let bedLFE {
-                    bedHistory.withUnsafeBufferPointer { (p + n - h).update(from: $0.baseAddress! + bedLFE * n + n - h, count: h) }
+                    bedHistory.withUnsafeBufferPointer { (p + length - h).update(from: $0.baseAddress! + bedLFE * n + n - h, count: h) }
                 } else {
-                    (p + n - h).update(repeating: 0, count: h)
+                    (p + length - h).update(repeating: 0, count: h)
                 }
             }
         }
diff --git a/Tests/AetherEngineTests/BedSplitterTests.swift b/Tests/AetherEngineTests/BedSplitterTests.swift
new file mode 100644
index 000000000..ca85d9493
--- /dev/null
+++ b/Tests/AetherEngineTests/BedSplitterTests.swift
@@ -0,0 +1,168 @@
+// Only with the TrueHDObjectAudio trait: the splitter is not built without it.
+#if TrueHDObjectAudio
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// The TrueHD path takes every output from the stream's own channel presentation and only reads
+/// where the objects' energy lies. These pin what that split has to get right: the timeline (output
+/// frame i is input frame i, nothing lost at the end), where a bed channel's energy goes for an
+/// element on the floor and one on the ceiling, a 5.1 bed covering a 7.1 layout, and the LFE.
+@Suite("Bed splitter")
+struct BedSplitterTests {
+
+    static let bed71: [ObjectAudioRole] = [.bed(.left), .bed(.right), .bed(.center), .lfe,
+                                           .bed(.sideLeft), .bed(.sideRight), .bed(.rearLeft), .bed(.rearRight)]
+    static let bed51: [ObjectAudioRole] = [.bed(.left), .bed(.right), .bed(.center), .lfe,
+                                           .bed(.sideLeft), .bed(.sideRight)]
+
+    /// Deterministic noise, so every bin has energy.
+    static func noise(_ count: Int, seed: UInt64) -> [Float] {
+        var state = seed
+        return (0..<count).map { _ in
+            state = state &* 6364136223846793005 &+ 1442695040888963407
+            return Float(Int64(bitPattern: state >> 11) % 2000 - 1000) / 10_000
+        }
+    }
+
+    /// Runs `frames` frames through a splitter in 40-frame blocks with one element at `position`
+    /// whose signal is `element`, and returns every output channel, drained.
+    static func run(layout: SpatialSpeakerLayout, bedRoles: [ObjectAudioRole], bed: [[Float]],
+                    element: [Float]?, position: SIMD3<Float>, frames: Int) -> [[Float]] {
+        let splitter = BedSplitter(layout: layout, bedRoles: bedRoles)
+        var snapshot = ObjectAudioGainSnapshot()
+        if element != nil {
+            snapshot.resize(elements: 1, channels: layout.channelCount)
+            var gains: [Float] = []
+            AllocentricPanner(layout: layout).pointGains(position, into: &gains)
+            snapshot.layoutGains = gains
+            snapshot.positions = [position]
+            snapshot.gains = [1]
+            splitter.setGains(snapshot)
+        }
+        let out = (0..<layout.channelCount).map { _ in UnsafeMutablePointer<Float>.allocate(capacity: frames) }
+        defer { out.forEach { $0.deallocate() } }
+        var written = 0
+        var offset = 0
+        while offset < frames {
+            let n = min(40, frames - offset)
+            let got = bed.withPointers { bedPlanes in
+                (element ?? []).withUnsafeBufferPointer { e in
+                    splitter.process(
+                        elements: element == nil ? [] : [e.baseAddress! + offset],
+                        bed: bedPlanes.map { $0 + offset }, frameCount: n,
+                        output: out.map { $0 + written })
+                }
+            }
+            written += got
+            offset += n
+        }
+        written += splitter.drain(output: out.map { $0 + written })
+        #expect(written == frames)
+        return out.map { Array(UnsafeBufferPointer(start: $0, count: written)) }
+    }
+
+    static func energy(_ x: [Float]) -> Float { x.reduce(0) { $0 + $1 * $1 } }
+
+    static func silent(_ count: Int) -> [Float] { [Float](repeating: 0, count: count) }
+
+    @Test("output frame i is input frame i, and everything comes out by the end",
+          arguments: [300, 2047, 2048, 2049, 9_000])
+    func timeline(frames: Int) {
+        let layout = SpatialSpeakerLayout.l714
+        var left = Self.silent(frames)
+        let at = frames / 2
+        left[at] = 0.5
+        var bed = Self.bed71.map { _ in Self.silent(frames) }
+        bed[0] = left
+        bed[3] = left
+        let out = Self.run(layout: layout, bedRoles: Self.bed71, bed: bed, element: nil,
+                           position: SIMD3(0, 0, 0), frames: frames)
+        let peak = out[0].indices.max { abs(out[0][$0]) < abs(out[0][$1]) }!
+        #expect(peak == at)
+        // The LFE is a pure delay: exactly the bed's.
+        let lfe = out[layout.lfeIndex]
+        #expect(lfe == left, "LFE peak at \(lfe.indices.max { abs(lfe[$0]) < abs(lfe[$1]) }!), expected \(at)")
+    }
+
+    @Test("an element on the floor keeps its bed channel on its own speaker")
+    func floorElement() {
+        let layout = SpatialSpeakerLayout.l714, frames = 48_000
+        let signal = Self.noise(frames, seed: 1)
+        var bed = Self.bed71.map { _ in Self.silent(frames) }
+        bed[0] = signal
+        let out = Self.run(layout: layout, bedRoles: Self.bed71, bed: bed, element: signal,
+                           position: SIMD3(0, 0, 0), frames: frames)
+        let total = out.map(Self.energy).reduce(0, +)
+        #expect(Self.energy(out[0]) / total > 0.99)
+        #expect(abs(total / Self.energy(signal) - 1) < 0.05)
+    }
+
+    @Test("an element on the ceiling takes its bed channel's energy up to the heights")
+    func ceilingElement() {
+        let layout = SpatialSpeakerLayout.l714, frames = 48_000
+        let signal = Self.noise(frames, seed: 2)
+        var bed = Self.bed71.map { _ in Self.silent(frames) }
+        bed[0] = signal
+        let out = Self.run(layout: layout, bedRoles: Self.bed71, bed: bed, element: signal,
+                           position: SIMD3(0, 0, 1), frames: frames)
+        let topFrontLeft = layout.speakers.firstIndex(of: .topFrontLeft)!
+        let total = out.map(Self.energy).reduce(0, +)
+        #expect(Self.energy(out[topFrontLeft]) / total > 0.95)
+        #expect(Self.energy(out[0]) / total < 0.05)
+    }
+
+    @Test("a 5.1 bed's surround covers a 7.1 layout's rear as well as its side")
+    func fiveOneBedOnSevenOne() {
+        let layout = SpatialSpeakerLayout.l714, frames = 48_000
+        let signal = Self.noise(frames, seed: 3)
+        var bed = Self.bed51.map { _ in Self.silent(frames) }
+        bed[4] = signal
+        let rearLeft = layout.speakers.firstIndex(of: .rearLeft)!
+        let sideLeft = layout.speakers.firstIndex(of: .sideLeft)!
+        let atRear = Self.run(layout: layout, bedRoles: Self.bed51, bed: bed, element: signal,
+                              position: SIMD3(0, 1, 0), frames: frames)
+        let total = atRear.map(Self.energy).reduce(0, +)
+        #expect(Self.energy(atRear[rearLeft]) / total > 0.95)
+        // The same channel with nothing to say where it belongs stays on the side, its primary output.
+        let unexplained = Self.run(layout: layout, bedRoles: Self.bed51, bed: bed, element: nil,
+                                   position: SIMD3(0, 1, 0), frames: frames)
+        #expect(Self.energy(unexplained[sideLeft]) / unexplained.map(Self.energy).reduce(0, +) > 0.99)
+    }
+
+    @Test("a 7.1 bed's rears fold onto a 5.1 layout's surrounds")
+    func sevenOneBedOnFiveOne() {
+        let layout = SpatialSpeakerLayout.l514, frames = 24_000
+        let signal = Self.noise(frames, seed: 4)
+        var bed = Self.bed71.map { _ in Self.silent(frames) }
+        bed[6] = signal
+        let out = Self.run(layout: layout, bedRoles: Self.bed71, bed: bed, element: nil,
+                           position: SIMD3(0, 1, 0), frames: frames)
+        let surroundLeft = layout.speakers.firstIndex(of: .surroundLeft)!
+        #expect(Self.energy(out[surroundLeft]) / out.map(Self.energy).reduce(0, +) > 0.99)
+    }
+
+    @Test("the element's own signal never reaches an output: a silent bed stays silent")
+    func elementAloneIsSilent() {
+        let layout = SpatialSpeakerLayout.l714, frames = 24_000
+        let bed = Self.bed71.map { _ in Self.silent(frames) }
+        let out = Self.run(layout: layout, bedRoles: Self.bed71, bed: bed, element: Self.noise(frames, seed: 5),
+                           position: SIMD3(0.5, 0.5, 1), frames: frames)
+        #expect(out.allSatisfy { $0.allSatisfy { $0 == 0 } })
+    }
+}
+
+private extension Array where Element == [Float] {
+    func withPointers<R>(_ body: ([UnsafePointer<Float>]) -> R) -> R {
+        var pointers: [UnsafePointer<Float>] = []
+        func recurse(_ i: Int) -> R {
+            if i == count { return body(pointers) }
+            return self[i].withUnsafeBufferPointer { buffer in
+                pointers.append(buffer.baseAddress!)
+                return recurse(i + 1)
+            }
+        }
+        return recurse(0)
+    }
+}
+#endif
diff --git a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
index 96722c8a9..2db79ee2f 100644
--- a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
@@ -24,6 +24,9 @@ struct SpatialAudioBridgeTests {
         let framesPerAU = 40
         var skipAfterReset: Int
         var dropAt: (push: Int, count: Int)?
+        /// Carry the left bed channel and the LFE as the stream's channel presentation too, as the
+        /// TrueHD decoder does for the bed splitter.
+        var withBed = false
         private var pushes = 0
         private var skipped = 0
         private var inputFrames: Int64 = 0
@@ -31,9 +34,10 @@ struct SpatialAudioBridgeTests {
         private let planes: [UnsafeMutablePointer<Float>] = (0..<3).map { _ in .allocate(capacity: 1 << 16) }
         private var t = 0
 
-        init(skipAfterReset: Int, dropAt: (push: Int, count: Int)? = nil) {
+        init(skipAfterReset: Int, dropAt: (push: Int, count: Int)? = nil, withBed: Bool = false) {
             self.skipAfterReset = skipAfterReset
             self.dropAt = dropAt
+            self.withBed = withBed
         }
         deinit { planes.forEach { $0.deallocate() } }
 
@@ -70,7 +74,9 @@ struct SpatialAudioBridgeTests {
                 configurationGeneration: 0, roles: [.bed(.left), .lfe, .object],
                 planes: planes.map { UnsafePointer($0) },
                 updates: [.init(frameOffset: 0, rampFrames: b.frames,
-                                states: [.init(), .init(), .init(position: SIMD3(x, 0.5, 1))])])
+                                states: [.init(), .init(), .init(position: SIMD3(x, 0.5, 1))])],
+                bed: withBed ? ObjectAudioBed(roles: [.bed(.left), .lfe],
+                                              planes: [UnsafePointer(planes[0]), UnsafePointer(planes[1])]) : nil)
         }
 
         func reset() { skipped = 0; inputFrames = 0; blocks = []; pushes = 0 }
@@ -94,7 +100,8 @@ struct SpatialAudioBridgeTests {
         private var stateSent = false
         private let plane = UnsafeMutablePointer<Float>.allocate(capacity: 1 << 16)
 
-        init(clickFrame: Int64) { self.clickFrame = clickFrame }
+        let withBed: Bool
+        init(clickFrame: Int64, withBed: Bool = false) { self.clickFrame = clickFrame; self.withBed = withBed }
         deinit { plane.deallocate() }
 
         func push(_ bytes: UnsafeRawBufferPointer) throws {
@@ -113,7 +120,8 @@ struct SpatialAudioBridgeTests {
             return ObjectAudioDecodedBlock(
                 sampleRate: 48_000, frameCount: b.frames, inputFrameOffset: b.offset,
                 configurationGeneration: 0, roles: [.bed(.left)], planes: [UnsafePointer(plane)],
-                updates: stateSent ? [] : [.init(frameOffset: 0, rampFrames: 0, states: [.init()])])
+                updates: stateSent ? [] : [.init(frameOffset: 0, rampFrames: 0, states: [.init()])],
+                bed: withBed ? ObjectAudioBed(roles: [.bed(.left)], planes: [UnsafePointer(plane)]) : nil)
         }
 
         func reset() { inputFrames = 0; blocks = []; stateSent = false }
@@ -180,12 +188,23 @@ struct SpatialAudioBridgeTests {
     #endif
 
     #if TrueHDObjectAudio || DTSXObjectAudio
-    @Test("the first packet sits at the source position of the first decodable frame, and steps by 1024")
-    func anchorsOnSource() throws {
+    /// With the stream's bed the output comes from `BedSplitter`, whose latency the bridge has to
+    /// keep off the timeline: the same timestamps, and the same tail at the end.
+    static let bedArms: [Bool] = {
+        #if TrueHDObjectAudio
+        [false, true]
+        #else
+        [false]
+        #endif
+    }()
+
+    @Test("the first packet sits at the source position of the first decodable frame, and steps by 1024",
+          arguments: bedArms)
+    func anchorsOnSource(withBed: Bool) throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
         let bridge = try SpatialAudioBridge(
             srcTimeBase: AVRational(num: 1, den: 1000), layout: .l714,
-            decoder: SyntheticDecoder(skipAfterReset: 5))
+            decoder: SyntheticDecoder(skipAfterReset: 5, withBed: withBed))
         defer { bridge.close() }
         var packets = try feed(bridge, startMs: 1000, count: 100)
         packets += bridge.flush().map { fp in
@@ -358,12 +377,12 @@ struct SpatialAudioBridgeTests {
         #expect(a == b)
     }
 
-    @Test("a producer restart re-anchors on the new position")
-    func restartReanchors() throws {
+    @Test("a producer restart re-anchors on the new position", arguments: bedArms)
+    func restartReanchors(withBed: Bool) throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
         let bridge = try SpatialAudioBridge(
             srcTimeBase: AVRational(num: 1, den: 1000), layout: .l916,
-            decoder: SyntheticDecoder(skipAfterReset: 3))
+            decoder: SyntheticDecoder(skipAfterReset: 3, withBed: withBed))
         defer { bridge.close() }
         _ = try feed(bridge, startMs: 0, count: 30)
         bridge.startSegment()
@@ -372,12 +391,12 @@ struct SpatialAudioBridgeTests {
         #expect(zip(packets, packets.dropFirst()).allSatisfy { $1.pts - $0.pts == 1024 })
     }
 
-    @Test("a span the decoder drops is filled, so everything after it keeps its timestamp")
-    func gapKeepsTimeline() throws {
+    @Test("a span the decoder drops is filled, so everything after it keeps its timestamp", arguments: bedArms)
+    func gapKeepsTimeline(withBed: Bool) throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
         let bridge = try SpatialAudioBridge(
             srcTimeBase: AVRational(num: 1, den: 1000), layout: .l714,
-            decoder: SyntheticDecoder(skipAfterReset: 0, dropAt: (push: 10, count: 12)))
+            decoder: SyntheticDecoder(skipAfterReset: 0, dropAt: (push: 10, count: 12), withBed: withBed))
         defer { bridge.close() }
         var packets = try feed(bridge, startMs: 0, count: 100)
         packets += bridge.flush().map { fp in
@@ -497,13 +516,13 @@ struct SpatialAudioBridgeTests {
     /// rendered, encoded, muxed and decoded back by AVFoundation, which presents APAC the way
     /// AVPlayer does, and has to come out where the source put it. With the encoder's priming
     /// packets dropped it came out 2048 frames (42.7 ms) early, and so did every session's audio.
-    @Test("a click decodes back at its source position through AVFoundation")
-    func clickDecodesOnItsSourcePosition() async throws {
+    @Test("a click decodes back at its source position through AVFoundation", arguments: bedArms)
+    func clickDecodesOnItsSourcePosition(withBed: Bool) async throws {
         guard #available(macOS 26.0, iOS 26.0, tvOS 26.0, visionOS 26.0, *) else { return }
         // The source starts at 0 and the click is 12000 frames in, so it belongs at 0.25 s.
         let bridge = try SpatialAudioBridge(
             srcTimeBase: AVRational(num: 1, den: 1000), layout: .l714,
-            decoder: ClickDecoder(clickFrame: 12_000))
+            decoder: ClickDecoder(clickFrame: 12_000, withBed: withBed))
         defer { bridge.close() }
         guard let muxed = try muxWithProbeVideo(bridge, startMs: 0, count: 30) else { return }
         let sessionDir = muxed.sessionDir

From 39c72a55df7eadcde7047c64ea1f2d2abb715752 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 11:06:51 +0200
Subject: [PATCH 123/132] docs(audio): the TrueHD Atmos bed comes from the
 channel presentation (#731)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md    | 9 +++++++++
 docs/cli.md     | 2 +-
 docs/formats.md | 6 ++++--
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 84f69ff13..be7f3c81a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,15 @@ the public-API contract.
 
 ### Changed
 
+- **TrueHD Atmos is built from the stream's own channel presentation.** With `objectAudioRendering`
+  in a `TrueHDObjectAudio` build, every output is now a share of the 7.1 (or 5.1) bed Dolby renders
+  the same mix into, split per frequency bin between floor and heights by where the objects' energy
+  lies (`BedSplitter`). No object signal is mixed into an output; the objects are decoded without
+  their matrix interpolation and taken as points. Measured against the previous exact render through
+  Apple's APAC decode it places the same energy within a few percent, with the heights within a
+  fraction of a dB. Needs LibTrueHD 3.0 (bed companion, per-handle interpolation switch). A 5.1 bed
+  now covers a 7.1 layout's rears as well as its sides. `AETHER_TRUEHD_REFERENCE_RENDER=1` keeps the
+  exact render for measurements (#731).
 - **The documentation no longer says TrueHD Atmos objects are always lost.** The Known limitations
   entry in `docs/formats.md`, the `AudioDelivery.bridged` reference and the channel bridge's notes
   predate `objectAudioRendering` (#731) and said objects and heights never survive. They now say the
diff --git a/docs/cli.md b/docs/cli.md
index a21fd5290..ea18027b1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -75,7 +75,7 @@ open 'http://127.0.0.1:<port>/<token>/master.m3u8'   # macOS QuickTime
 
 `--start-position S` starts the session at S seconds, the resume anchor a host passes to `load(url:startPosition:)`. Also available on `play`.
 
-`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: objects rendered into …` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`.
+`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: channel presentation split into … by the objects' energy` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`. With `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment the TrueHD track is decoded exactly and its objects mixed by the renderer instead (`… objects rendered into 7.1.4 (reference render, …)`), the reference the split is measured against: serve the file both ways, decode each APAC track to PCM and compare per channel.
 
 `--audio-delay <ms>` parks the server with the AE#464 audio offset already in its muxer, which is how the DELIVERED offset is measured rather than argued about: fetch the media playlist and walk its segments, then read the first audio and video packet timestamps out of `init.mp4` + a segment with `ffprobe -show_entries packet=stream_index,pts_time`. On a 30 fps H.264 + AAC fixture the source's own alignment is +21.8 ms, `--audio-delay 200` reads +221.8 ms and `--audio-delay -150` reads -128.2 ms, i.e. exactly the offset asked for, with the video timestamp unchanged in every arm.
 
diff --git a/docs/formats.md b/docs/formats.md
index 7257a04a9..d621991e7 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -348,9 +348,11 @@ Matroska CodecPrivate doesn't usually carry the pre-parsed `dec3` / `dac3` box c
 
 ### TrueHD Atmos with heights
 
-Apple TV cannot bitstream TrueHD, and no Apple platform hands a third-party app a compressed bitstream output, so the audio bridge decodes a TrueHD track and re-encodes its 7.1 channel presentation (`audioBridgeMode`). For TrueHD Atmos that loses every height and every object position before the audio leaves the engine. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them (AetherEngine#731): the engine decodes the Atmos object presentation (the bed, up to 15 dynamic objects and their object audio metadata, through [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)), renders it into the `SpatialSpeakerLayout` bed the host names (5.1.2, 5.1.4, 7.1.2, 7.1.4 or 9.1.6, as `SpatialSpeaker` positions in CoreAudio's channel order), and encodes that bed as Apple Positional Audio. tvOS sends APAC to an Atmos receiver or soundbar as Dolby MAT, the same way it delivers its own spatial content, and iOS plays it as Spatial Audio.
+Apple TV cannot bitstream TrueHD, and no Apple platform hands a third-party app a compressed bitstream output, so the audio bridge decodes a TrueHD track and re-encodes its 7.1 channel presentation (`audioBridgeMode`). For TrueHD Atmos that loses every height and every object position before the audio leaves the engine. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them (AetherEngine#731): the engine decodes the Atmos object presentation (the bed, up to 15 dynamic objects and their object audio metadata, through [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) together with the stream's own channel-based presentation (the 7.1, or 5.1, bed Dolby renders the same mix into), builds the `SpatialSpeakerLayout` bed the host names (5.1.2, 5.1.4, 7.1.2, 7.1.4 or 9.1.6, as `SpatialSpeaker` positions in CoreAudio's channel order) out of that channel presentation, and encodes it as Apple Positional Audio. tvOS sends APAC to an Atmos receiver or soundbar as Dolby MAT, the same way it delivers its own spatial content, and iOS plays it as Spatial Audio.
 
-The renderer is allocentric, the model Atmos metadata is authored in: the room is a unit cube, and an object is balanced constant-power between the two speaker planes that bracket its height, the two rows that bracket its depth and the two speakers that bracket its width, so moving an object never changes its loudness. Ceiling speakers sit where ETSI TS 103 448 puts them, a quarter of the room in from each wall rather than in its corners, so an object on the ceiling a third of the way back plays mostly from the front tops, as Apple's own Atmos render places it. A 5.1 bed's surrounds sit halfway down the side walls, also as TS 103 448 places them, so on 5.1.2 and 5.1.4 an object at the back wall stays on them. Object size spreads it over a grid of points summed by power, snap sends it to the nearest speaker, zone masks keep it off the speakers they exclude, and an object without elevation stays off the ceiling. Bed channels the layout has route discretely, LFE goes to the LFE channel, and metadata updates ramp gains sample-accurately as the stream specifies. After a seek, decoding resumes at the next major sync, and the stream's first object metadata follows it up to 32 ms later; the decoder holds the audio in between and plays it at that metadata's positions, rather than leaving every object silent until it arrives (it waits at most 100 ms).
+**How the bed is built.** Every output is a share of the stream's channel presentation (`BedSplitter`). Per STFT bin (2048-frame Hann windows, 512-frame hop), each of its channels is divided between the floor speakers it covers and the heights, in proportion to how much of that bin's energy comes from objects at each place: an object's part is its spectral energy times its ear-level gain into the channel, and it goes up in proportion to its layout gains above ear level. The objects only say where energy lies; no object signal reaches an output, so they are decoded without the stream's matrix interpolation values (LibTrueHD's `set_ignore_interpolation`, the channel presentation comes from the same access units through `set_bed_companion`) and taken as plain points at their positions, without size, snap, zones, screen anchoring or the elevation switch. Two corrections keep the estimate honest. Per band, an object holds no more than twice the energy its bed channels allow it, which keeps the decoding residue in quiet objects from pulling a quiet channel's content up or sideways. And per output and band, an output the split leaves short of the energy a direct render would give it is raised towards it (smoothed over about 200 ms, at most 6 dB), never lowered: objects carrying the same signal add up to more in a mix than their energies do, so a lower estimate is the estimate's shortfall. A 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's surrounds cover a 7.1 layout's sides and rears, a 7.1 bed's rears fold onto a 5.1 floor, and the LFE is the bed's own. The split runs 2048 frames behind its input: the bridge starts its output that much later after every reset and drains it before the encoder restarts elsewhere and at the end of input, so nothing moves against the picture and nothing is cut off. `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment keeps the exact decode mixed by the renderer instead, for measuring the split against it.
+
+The renderer, which gives the split its object gains and mixes DTS:X directly, is allocentric, the model Atmos metadata is authored in: the room is a unit cube, and an object is balanced constant-power between the two speaker planes that bracket its height, the two rows that bracket its depth and the two speakers that bracket its width, so moving an object never changes its loudness. Ceiling speakers sit where ETSI TS 103 448 puts them, a quarter of the room in from each wall rather than in its corners, so an object on the ceiling a third of the way back plays mostly from the front tops, as Apple's own Atmos render places it. A 5.1 bed's surrounds sit halfway down the side walls, also as TS 103 448 places them, so on 5.1.2 and 5.1.4 an object at the back wall stays on them. For DTS:X, object size spreads it over a grid of points summed by power, snap sends it to the nearest speaker, zone masks keep it off the speakers they exclude, and an object without elevation stays off the ceiling. Bed channels the layout has route discretely, LFE goes to the LFE channel, and metadata updates ramp gains sample-accurately as the stream specifies. After a seek, decoding resumes at the next major sync, and the stream's first object metadata follows it up to 32 ms later; the decoder holds the audio in between and plays it at that metadata's positions, rather than leaving every object silent until it arrives (it waits at most 100 ms).
 
 **Track choice.** With the option on, the automatic audio pick prefers a TrueHD Atmos track over the other tracks of the same language: of the `preferredAudioLanguages` match, or of the session's default track when no preference decides it. It never crosses a language or a dub (a region or script both tags state and disagree on), never picks a commentary for it, applies only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later), and an explicit `audioSourceStreamIndexOverride` still wins. Without that, a film carrying DTS-HD and TrueHD Atmos in one language usually opened on whichever the container listed first.
 

From 6292d7a4cac25c85746a5ecea47242f55b6a7561 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 11:34:38 +0200
Subject: [PATCH 124/132] fix(audio): the bed splitter lowers an output by a
 third of the gap (#731)

Never lowering let a split that over-allocates stand: on 72 windows of
six films two scenes came out 1.5 dB loud in heights and surrounds
(worst second 9.0 % misplaced). Lowering by a third of the gap in dB
keeps the heights within about a dB of the exact render while those
scenes drop to 5.3 and 5.7 %; Unfold stays at 3.3 % median, its
second 9 left rear at 15.1 % against the reference's 14.5 %.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/Spatial/BedSplitter.swift           | 19 ++++++++++++-------
 docs/formats.md                               |  2 +-
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift b/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
index c8af16f2b..d5cba8124 100644
--- a/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
+++ b/Sources/AetherEngine/Audio/Spatial/BedSplitter.swift
@@ -20,11 +20,13 @@ import Foundation
 ///   times what its ear-level share of them allows). The decode without interpolation leaves a
 ///   residue in quiet elements; bounded by the bed, it can no longer pull a quiet channel's content
 ///   up or sideways.
-/// - Per output and band, an output the split leaves short of the energy the elements would give it
-///   in a direct render is raised towards it (smoothed over about 200 ms, at most `balanceLimit`),
-///   which restores the spread a per-bin split loses where several elements share a bin. It is never
-///   lowered: the elements' energies add up to less than a mix of them wherever they carry the same
-///   signal, so a target below the split is the estimate's shortfall, not the mix's.
+/// - Per output and band, the result is steered towards the energy the elements would give that
+///   output in a direct render (smoothed over about 200 ms), which restores the spread a per-bin
+///   split loses where several elements share a bin. Raised fully (at most `balanceLimit`), lowered
+///   only by a third of the gap in dB (`balanceLowering`): the elements' energies add up to less than
+///   a mix of them wherever they carry the same signal, so a target below the split is mostly the
+///   estimate's shortfall, and lowering fully cost heights. Not lowering at all let a split that
+///   over-allocates stand.
 ///
 /// The LFE is the bed's own, delayed alongside.
 ///
@@ -38,6 +40,8 @@ final class BedSplitter {
     static let boundMinShare: Float = 0.05
     static let balanceSmoothing: Float = 0.95
     static let balanceLimit: Float = 4
+    /// A lowering is applied at this fraction of its size in dB.
+    static let balanceLowering: Float = 1.0 / 3
 
     let layout: SpatialSpeakerLayout
     let bedRoles: [ObjectAudioRole]
@@ -578,7 +582,7 @@ final class BedSplitter {
             }
         }
 
-        // Balance per output and band: raised towards the energy a direct render would give it.
+        // Balance per output and band, towards the energy a direct render would give it.
         let a = Self.balanceSmoothing
         for band in 0..<bands {
             let lo = bandEdges[band], hi = min(bandEdges[band + 1], bins)
@@ -592,7 +596,8 @@ final class BedSplitter {
                 smoothedSplit[slot] = a * smoothedSplit[slot] + (1 - a) * e
                 let st = smoothedTarget[slot], se = smoothedSplit[slot]
                 guard st > tiny, se > tiny else { continue }
-                let g = min(max(st / se, 1), Self.balanceLimit).squareRoot()
+                let r = st / se
+                let g = (r >= 1 ? min(r, Self.balanceLimit) : pow(r, Self.balanceLowering)).squareRoot()
                 for b in lo..<hi { outRe[row + b] *= g; outIm[row + b] *= g }
             }
         }
diff --git a/docs/formats.md b/docs/formats.md
index d621991e7..c5315b619 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -350,7 +350,7 @@ Matroska CodecPrivate doesn't usually carry the pre-parsed `dec3` / `dac3` box c
 
 Apple TV cannot bitstream TrueHD, and no Apple platform hands a third-party app a compressed bitstream output, so the audio bridge decodes a TrueHD track and re-encodes its 7.1 channel presentation (`audioBridgeMode`). For TrueHD Atmos that loses every height and every object position before the audio leaves the engine. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them (AetherEngine#731): the engine decodes the Atmos object presentation (the bed, up to 15 dynamic objects and their object audio metadata, through [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) together with the stream's own channel-based presentation (the 7.1, or 5.1, bed Dolby renders the same mix into), builds the `SpatialSpeakerLayout` bed the host names (5.1.2, 5.1.4, 7.1.2, 7.1.4 or 9.1.6, as `SpatialSpeaker` positions in CoreAudio's channel order) out of that channel presentation, and encodes it as Apple Positional Audio. tvOS sends APAC to an Atmos receiver or soundbar as Dolby MAT, the same way it delivers its own spatial content, and iOS plays it as Spatial Audio.
 
-**How the bed is built.** Every output is a share of the stream's channel presentation (`BedSplitter`). Per STFT bin (2048-frame Hann windows, 512-frame hop), each of its channels is divided between the floor speakers it covers and the heights, in proportion to how much of that bin's energy comes from objects at each place: an object's part is its spectral energy times its ear-level gain into the channel, and it goes up in proportion to its layout gains above ear level. The objects only say where energy lies; no object signal reaches an output, so they are decoded without the stream's matrix interpolation values (LibTrueHD's `set_ignore_interpolation`, the channel presentation comes from the same access units through `set_bed_companion`) and taken as plain points at their positions, without size, snap, zones, screen anchoring or the elevation switch. Two corrections keep the estimate honest. Per band, an object holds no more than twice the energy its bed channels allow it, which keeps the decoding residue in quiet objects from pulling a quiet channel's content up or sideways. And per output and band, an output the split leaves short of the energy a direct render would give it is raised towards it (smoothed over about 200 ms, at most 6 dB), never lowered: objects carrying the same signal add up to more in a mix than their energies do, so a lower estimate is the estimate's shortfall. A 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's surrounds cover a 7.1 layout's sides and rears, a 7.1 bed's rears fold onto a 5.1 floor, and the LFE is the bed's own. The split runs 2048 frames behind its input: the bridge starts its output that much later after every reset and drains it before the encoder restarts elsewhere and at the end of input, so nothing moves against the picture and nothing is cut off. `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment keeps the exact decode mixed by the renderer instead, for measuring the split against it.
+**How the bed is built.** Every output is a share of the stream's channel presentation (`BedSplitter`). Per STFT bin (2048-frame Hann windows, 512-frame hop), each of its channels is divided between the floor speakers it covers and the heights, in proportion to how much of that bin's energy comes from objects at each place: an object's part is its spectral energy times its ear-level gain into the channel, and it goes up in proportion to its layout gains above ear level. The objects only say where energy lies; no object signal reaches an output, so they are decoded without the stream's matrix interpolation values (LibTrueHD's `set_ignore_interpolation`, the channel presentation comes from the same access units through `set_bed_companion`) and taken as plain points at their positions, without size, snap, zones, screen anchoring or the elevation switch. Two corrections keep the estimate honest. Per band, an object holds no more than twice the energy its bed channels allow it, which keeps the decoding residue in quiet objects from pulling a quiet channel's content up or sideways. And per output and band, an output the split leaves short of the energy a direct render would give it is raised towards it (smoothed over about 200 ms, at most 6 dB), and one the split leaves above it is lowered by only a third of the gap in dB: objects carrying the same signal add up to more in a mix than their energies do, so a lower estimate is mostly the estimate's shortfall. A 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's surrounds cover a 7.1 layout's sides and rears, a 7.1 bed's rears fold onto a 5.1 floor, and the LFE is the bed's own. The split runs 2048 frames behind its input: the bridge starts its output that much later after every reset and drains it before the encoder restarts elsewhere and at the end of input, so nothing moves against the picture and nothing is cut off. `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment keeps the exact decode mixed by the renderer instead, for measuring the split against it.
 
 The renderer, which gives the split its object gains and mixes DTS:X directly, is allocentric, the model Atmos metadata is authored in: the room is a unit cube, and an object is balanced constant-power between the two speaker planes that bracket its height, the two rows that bracket its depth and the two speakers that bracket its width, so moving an object never changes its loudness. Ceiling speakers sit where ETSI TS 103 448 puts them, a quarter of the room in from each wall rather than in its corners, so an object on the ceiling a third of the way back plays mostly from the front tops, as Apple's own Atmos render places it. A 5.1 bed's surrounds sit halfway down the side walls, also as TS 103 448 places them, so on 5.1.2 and 5.1.4 an object at the back wall stays on them. For DTS:X, object size spreads it over a grid of points summed by power, snap sends it to the nearest speaker, zone masks keep it off the speakers they exclude, and an object without elevation stays off the ceiling. Bed channels the layout has route discretely, LFE goes to the LFE channel, and metadata updates ramp gains sample-accurately as the stream specifies. After a seek, decoding resumes at the next major sync, and the stream's first object metadata follows it up to 32 ms later; the decoder holds the audio in between and plays it at that metadata's positions, rather than leaving every object silent until it arrives (it waits at most 100 ms).
 

From 7aa41288256935da19f6861fb8a791dbf4c95525 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 12:45:53 +0200
Subject: [PATCH 125/132] fix(audio): the TrueHD path never mixes object
 signals, takes metadata without ramps (#731)

A block that arrives without the channel presentation before the
splitter exists played through the renderer's mix; it is now silence,
since a decoder that splits its bed plays nothing but the bed.
Metadata updates are taken as they stand rather than ramped towards:
the split's weights are smoothed over about 200 ms anyway, and on the
measured windows nothing moved by more than 0.1 point.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift | 4 ++++
 Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift  | 5 +++++
 .../Audio/Spatial/TrueHDObjectAudioDecoder.swift             | 5 ++++-
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift b/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
index 6d436161c..4351d3222 100644
--- a/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
+++ b/Sources/AetherEngine/Audio/Spatial/ObjectAudioDecoding.swift
@@ -51,10 +51,14 @@ protocol ObjectAudioDecoding: AnyObject {
     /// How often the decoder has reset ITSELF after an internal failure. Its input offsets count from
     /// zero again afterwards, so the caller has to re-anchor its timeline.
     var selfResetCount: Int { get }
+    /// The decoder's output is meant to come from its channel bed (`ObjectAudioDecodedBlock.bed`) and
+    /// nothing else: a block without one plays as silence rather than through the renderer's mix.
+    var playsBedOnly: Bool { get }
 }
 
 extension ObjectAudioDecoding {
     var selfResetCount: Int { 0 }
+    var playsBedOnly: Bool { false }
     func releaseHeldBlocks() {}
 }
 #endif
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
index 3743547bb..a04b7b13c 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialAudioBridge.swift
@@ -436,6 +436,11 @@ final class SpatialAudioBridge: AudioTranscodingBridge, @unchecked Sendable {
             pendingFrames += splitter.process(
                 elements: nil, bed: nil, frameCount: block.frameCount,
                 output: output.planes.map { $0 + pendingFrames })
+        } else if decoder.playsBedOnly {
+            // No bed yet: silence, never a mix of the object signals.
+            renderer!.advance(frameCount: block.frameCount, updates: block.updates)
+            for plane in output.planes { (plane + pendingFrames).update(repeating: 0, count: block.frameCount) }
+            pendingFrames += block.frameCount
         } else {
             renderer!.render(
                 inputs: block.planes, frameCount: block.frameCount, updates: block.updates,
diff --git a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
index 6af8bed72..3f2f8e14e 100644
--- a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
@@ -30,6 +30,7 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
     private var rolesSerial: UInt32?
     private var planes: [UnsafePointer<Float>] = []
     let splitsBed: Bool
+    var playsBedOnly: Bool { splitsBed }
     private var bedRoles: [ObjectAudioRole] = []
     private var bedRolesSerial: UInt32?
     private var bedPlanes: [UnsafePointer<Float>] = []
@@ -131,7 +132,9 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
                                   ? state(for: element) : nil)
                 }
                 updates.append(ObjectAudioMetadataUpdate(
-                    frameOffset: Int(update.frame_offset), rampFrames: Int(update.ramp_frames), states: states))
+                    frameOffset: Int(update.frame_offset),
+                    // Splitting the bed, each update is taken as it stands, without the ramp towards it.
+                    rampFrames: splitsBed ? 0 : Int(update.ramp_frames), states: states))
             }
         }
 

From 3e53e7c0418792bbb5c2a0bbbd2dbf9dc994d1ea Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 12:51:41 +0200
Subject: [PATCH 126/132] fix(audio): the TrueHD reference render is a
 measurement-only trait (#731)

The exact decode and the size, snap, zone, screen and elevation mapping
for TrueHD are now built only with the TrueHDReferenceRender trait. A
shipped TrueHDObjectAudio build contains the bed split alone, and a
decoder that is asked for the exact path without the trait traps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                      |  4 ++--
 Package.swift                                     |  5 +++++
 .../Audio/Spatial/TrueHDObjectAudioDecoder.swift  | 11 +++++++++++
 .../Video/HLSVideoEngine+SpatialAudio.swift       | 13 ++++++++++---
 .../TrueHDObjectMetadataMappingTests.swift        | 15 +++++++++++++++
 docs/cli.md                                       |  2 +-
 docs/formats.md                                   |  2 +-
 7 files changed, 45 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index be7f3c81a..9759b21b9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,8 +19,8 @@ the public-API contract.
   their matrix interpolation and taken as points. Measured against the previous exact render through
   Apple's APAC decode it places the same energy within a few percent, with the heights within a
   fraction of a dB. Needs LibTrueHD 3.0 (bed companion, per-handle interpolation switch). A 5.1 bed
-  now covers a 7.1 layout's rears as well as its sides. `AETHER_TRUEHD_REFERENCE_RENDER=1` keeps the
-  exact render for measurements (#731).
+  now covers a 7.1 layout's rears as well as its sides. The exact render it is measured against
+  is only built with the measurement-only `TrueHDReferenceRender` trait (#731).
 - **The documentation no longer says TrueHD Atmos objects are always lost.** The Known limitations
   entry in `docs/formats.md`, the `AudioDelivery.bridged` reference and the channel bridge's notes
   predate `objectAudioRendering` (#731) and said objects and heights never survive. They now say the
diff --git a/Package.swift b/Package.swift
index 67945ff2f..c3a4a3520 100644
--- a/Package.swift
+++ b/Package.swift
@@ -37,6 +37,11 @@ let package = Package(
             name: "TrueHDObjectAudio",
             description: "Link LibTrueHD and the object renderer, so objectAudioRendering can render TrueHD Atmos objects to APAC."
         ),
+        .trait(
+            name: "TrueHDReferenceRender",
+            description: "Measurement only: with TrueHDObjectAudio and a LibTrueHD built with matrix interpolation, AETHER_TRUEHD_REFERENCE_RENDER=1 decodes TrueHD Atmos exactly and mixes its objects, the reference the bed split is measured against. Never ship it.",
+            enabledTraits: ["TrueHDObjectAudio"]
+        ),
         .trait(
             name: "DTSXObjectAudio",
             description: "Link LibDTSX and the object renderer, so objectAudioRendering can render DTS:X heights and objects to APAC."
diff --git a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
index 3f2f8e14e..56dcc48ad 100644
--- a/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/TrueHDObjectAudioDecoder.swift
@@ -40,7 +40,11 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
     private let hold = ObjectMetadataHold()
     private var lent: ObjectMetadataHold.Copy?
 
+    /// `splitsBed` is false only for the measurement reference (`TrueHDReferenceRender` trait).
     init(splitsBed: Bool = true) throws {
+        #if !TrueHDReferenceRender
+        precondition(splitsBed, "the exact decode and mix are only built with the TrueHDReferenceRender trait")
+        #endif
         guard let handle = truehd_atmos_decoder_create(TRUEHD_ATMOS_PRESENTATION_HIGHEST) else {
             throw DecoderError(status: TRUEHD_ATMOS_ERR_INVALID_ARGUMENT, message: "create failed")
         }
@@ -201,7 +205,11 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
     }
 
     private func state(for element: TrueHDAtmosElement) -> ObjectAudioElementState {
+        #if TrueHDReferenceRender
         splitsBed ? Self.pointSource(for: element) : Self.state(for: element)
+        #else
+        Self.pointSource(for: element)
+        #endif
     }
 
     /// An element as a point at its position: no size, snap, zone exclusion, screen anchoring or
@@ -213,6 +221,8 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
         return ObjectAudioElementState(position: SIMD3(p.0, p.1, max(0, p.2)), gain: active ? element.gain : 0)
     }
 
+    #if TrueHDReferenceRender
+    // The reference render's mapping: size, snap, zones, screen anchoring and the elevation switch.
     static func state(for element: TrueHDAtmosElement) -> ObjectAudioElementState {
         let active = element.flags & TRUEHD_ATMOS_ELEMENT_ACTIVE != 0
         var p = element.position
@@ -264,5 +274,6 @@ final class TrueHDObjectAudioDecoder: ObjectAudioDecoding {
         default: return []
         }
     }
+    #endif
 }
 #endif
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index e23797b92..26b45321d 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -3,11 +3,18 @@ import AetherLibavformat
 import AetherLibavcodec
 import AetherLibavutil
 
-/// Measurement only: with this environment variable set to 1, TrueHD Atmos is decoded exactly and
-/// its objects mixed into the layout, the rendering `BedSplitter` is compared against.
+/// Measurement only, in a build with the TrueHDReferenceRender trait: with this environment variable
+/// set to 1, TrueHD Atmos is decoded exactly and its objects mixed into the layout, the rendering
+/// `BedSplitter` is compared against. Without the trait it is always off and that path is not built.
 enum TrueHDReferenceRender {
     static let variable = "AETHER_TRUEHD_REFERENCE_RENDER"
-    static var isOn: Bool { ProcessInfo.processInfo.environment[variable] == "1" }
+    static var isOn: Bool {
+        #if TrueHDReferenceRender
+        ProcessInfo.processInfo.environment[variable] == "1"
+        #else
+        false
+        #endif
+    }
 }
 
 extension HLSVideoEngine {
diff --git a/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift b/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
index 480f11248..3b3cf1281 100644
--- a/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
+++ b/Tests/AetherEngineTests/TrueHDObjectMetadataMappingTests.swift
@@ -49,6 +49,19 @@ struct TrueHDObjectMetadataMappingTests {
         #expect(TrueHDObjectAudioDecoder.role(forSpeaker: TRUEHD_ATMOS_SPEAKER_UNKNOWN) == .object)
     }
 
+    @Test("splitting the bed, an element is a point at its position with its gain, and nothing else")
+    func pointSource() {
+        let flags = TRUEHD_ATMOS_ELEMENT_ACTIVE | TRUEHD_ATMOS_ELEMENT_SNAP | TRUEHD_ATMOS_ELEMENT_SCREEN_REF
+        let state = TrueHDObjectAudioDecoder.pointSource(
+            for: element(flags: flags, position: (0.8, 0.6, 1), size: (0.4, 0.4, 0.4), zone: TRUEHD_ATMOS_ZONE_NO_BACK))
+        #expect(state == ObjectAudioElementState(position: SIMD3(0.8, 0.6, 1), gain: 0.5))
+        #expect(TrueHDObjectAudioDecoder.pointSource(for: element(flags: 0)).gain == 0)
+        #expect(TrueHDObjectAudioDecoder.pointSource(for: element(position: (0.5, 0.5, -0.6))).position.z == 0)
+        #expect(TrueHDObjectAudioDecoder.pointSource(for: element(kind: TRUEHD_ATMOS_ELEMENT_ISF)).position
+                == SIMD3(0.5, 0.5, 0.5))
+    }
+
+    #if TrueHDReferenceRender
     @Test("an active elevated object keeps its position, gain and largest size dimension")
     func plainObject() {
         let state = TrueHDObjectAudioDecoder.state(for: element(size: (0.1, 0.3, 0.2)))
@@ -141,6 +154,8 @@ struct TrueHDObjectMetadataMappingTests {
         #expect(abs(gains.reduce(0) { $0 + $1 * $1 } - 1) < 1e-5)
     }
 
+    #endif
+
     @Test("the decoder opens, takes input and asks for more")
     func decoderLifecycle() throws {
         let decoder = try TrueHDObjectAudioDecoder()
diff --git a/docs/cli.md b/docs/cli.md
index ea18027b1..d37a9b40b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -75,7 +75,7 @@ open 'http://127.0.0.1:<port>/<token>/master.m3u8'   # macOS QuickTime
 
 `--start-position S` starts the session at S seconds, the resume anchor a host passes to `load(url:startPosition:)`. Also available on `play`.
 
-`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: channel presentation split into … by the objects' energy` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`. With `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment the TrueHD track is decoded exactly and its objects mixed by the renderer instead (`… objects rendered into 7.1.4 (reference render, …)`), the reference the split is measured against: serve the file both ways, decode each APAC track to PCM and compare per channel.
+`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: channel presentation split into … by the objects' energy` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`. In a build with the `TrueHDReferenceRender` trait (and a LibTrueHD built with `matrix-interpolation`), `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment decodes the TrueHD track exactly and mixes its objects through the renderer instead (`… objects rendered into 7.1.4 (reference render, …)`), the reference the split is measured against: serve the file both ways, decode each APAC track to PCM and compare per channel.
 
 `--audio-delay <ms>` parks the server with the AE#464 audio offset already in its muxer, which is how the DELIVERED offset is measured rather than argued about: fetch the media playlist and walk its segments, then read the first audio and video packet timestamps out of `init.mp4` + a segment with `ffprobe -show_entries packet=stream_index,pts_time`. On a 30 fps H.264 + AAC fixture the source's own alignment is +21.8 ms, `--audio-delay 200` reads +221.8 ms and `--audio-delay -150` reads -128.2 ms, i.e. exactly the offset asked for, with the video timestamp unchanged in every arm.
 
diff --git a/docs/formats.md b/docs/formats.md
index c5315b619..27a3b5993 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -350,7 +350,7 @@ Matroska CodecPrivate doesn't usually carry the pre-parsed `dec3` / `dac3` box c
 
 Apple TV cannot bitstream TrueHD, and no Apple platform hands a third-party app a compressed bitstream output, so the audio bridge decodes a TrueHD track and re-encodes its 7.1 channel presentation (`audioBridgeMode`). For TrueHD Atmos that loses every height and every object position before the audio leaves the engine. `LoadOptions.objectAudioRendering = .apac(layout)` keeps them (AetherEngine#731): the engine decodes the Atmos object presentation (the bed, up to 15 dynamic objects and their object audio metadata, through [LibTrueHD](https://github.com/superuser404notfound/LibTrueHD)) together with the stream's own channel-based presentation (the 7.1, or 5.1, bed Dolby renders the same mix into), builds the `SpatialSpeakerLayout` bed the host names (5.1.2, 5.1.4, 7.1.2, 7.1.4 or 9.1.6, as `SpatialSpeaker` positions in CoreAudio's channel order) out of that channel presentation, and encodes it as Apple Positional Audio. tvOS sends APAC to an Atmos receiver or soundbar as Dolby MAT, the same way it delivers its own spatial content, and iOS plays it as Spatial Audio.
 
-**How the bed is built.** Every output is a share of the stream's channel presentation (`BedSplitter`). Per STFT bin (2048-frame Hann windows, 512-frame hop), each of its channels is divided between the floor speakers it covers and the heights, in proportion to how much of that bin's energy comes from objects at each place: an object's part is its spectral energy times its ear-level gain into the channel, and it goes up in proportion to its layout gains above ear level. The objects only say where energy lies; no object signal reaches an output, so they are decoded without the stream's matrix interpolation values (LibTrueHD's `set_ignore_interpolation`, the channel presentation comes from the same access units through `set_bed_companion`) and taken as plain points at their positions, without size, snap, zones, screen anchoring or the elevation switch. Two corrections keep the estimate honest. Per band, an object holds no more than twice the energy its bed channels allow it, which keeps the decoding residue in quiet objects from pulling a quiet channel's content up or sideways. And per output and band, an output the split leaves short of the energy a direct render would give it is raised towards it (smoothed over about 200 ms, at most 6 dB), and one the split leaves above it is lowered by only a third of the gap in dB: objects carrying the same signal add up to more in a mix than their energies do, so a lower estimate is mostly the estimate's shortfall. A 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's surrounds cover a 7.1 layout's sides and rears, a 7.1 bed's rears fold onto a 5.1 floor, and the LFE is the bed's own. The split runs 2048 frames behind its input: the bridge starts its output that much later after every reset and drains it before the encoder restarts elsewhere and at the end of input, so nothing moves against the picture and nothing is cut off. `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment keeps the exact decode mixed by the renderer instead, for measuring the split against it.
+**How the bed is built.** Every output is a share of the stream's channel presentation (`BedSplitter`). Per STFT bin (2048-frame Hann windows, 512-frame hop), each of its channels is divided between the floor speakers it covers and the heights, in proportion to how much of that bin's energy comes from objects at each place: an object's part is its spectral energy times its ear-level gain into the channel, and it goes up in proportion to its layout gains above ear level. The objects only say where energy lies; no object signal reaches an output, so they are decoded without the stream's matrix interpolation values (LibTrueHD's `set_ignore_interpolation`, the channel presentation comes from the same access units through `set_bed_companion`) and taken as plain points at their positions, without size, snap, zones, screen anchoring or the elevation switch. Two corrections keep the estimate honest. Per band, an object holds no more than twice the energy its bed channels allow it, which keeps the decoding residue in quiet objects from pulling a quiet channel's content up or sideways. And per output and band, an output the split leaves short of the energy a direct render would give it is raised towards it (smoothed over about 200 ms, at most 6 dB), and one the split leaves above it is lowered by only a third of the gap in dB: objects carrying the same signal add up to more in a mix than their energies do, so a lower estimate is mostly the estimate's shortfall. A 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's surrounds cover a 7.1 layout's sides and rears, a 7.1 bed's rears fold onto a 5.1 floor, and the LFE is the bed's own. The split runs 2048 frames behind its input: the bridge starts its output that much later after every reset and drains it before the encoder restarts elsewhere and at the end of input, so nothing moves against the picture and nothing is cut off. The exact decode mixed by the renderer, which the split is measured against, is only built with the `TrueHDReferenceRender` package trait and a LibTrueHD built with its `matrix-interpolation` feature (measurement builds, never shipped); `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment then selects it. A shipped build contains neither the interpolating decode nor the size, snap, zone, screen and elevation mapping for TrueHD.
 
 The renderer, which gives the split its object gains and mixes DTS:X directly, is allocentric, the model Atmos metadata is authored in: the room is a unit cube, and an object is balanced constant-power between the two speaker planes that bracket its height, the two rows that bracket its depth and the two speakers that bracket its width, so moving an object never changes its loudness. Ceiling speakers sit where ETSI TS 103 448 puts them, a quarter of the room in from each wall rather than in its corners, so an object on the ceiling a third of the way back plays mostly from the front tops, as Apple's own Atmos render places it. A 5.1 bed's surrounds sit halfway down the side walls, also as TS 103 448 places them, so on 5.1.2 and 5.1.4 an object at the back wall stays on them. For DTS:X, object size spreads it over a grid of points summed by power, snap sends it to the nearest speaker, zone masks keep it off the speakers they exclude, and an object without elevation stays off the ceiling. Bed channels the layout has route discretely, LFE goes to the LFE channel, and metadata updates ramp gains sample-accurately as the stream specifies. After a seek, decoding resumes at the next major sync, and the stream's first object metadata follows it up to 32 ms later; the decoder holds the audio in between and plays it at that metadata's positions, rather than leaving every object silent until it arrives (it waits at most 100 ms).
 

From 7a0751704f8d143f045dd944b5b2ebdeef299b18 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 13:19:22 +0200
Subject: [PATCH 127/132] docs(changelog): unreleased TrueHD path and the #732
 / relay fixes

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9759b21b9..c5ef8073c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,11 +16,14 @@ the public-API contract.
   in a `TrueHDObjectAudio` build, every output is now a share of the 7.1 (or 5.1) bed Dolby renders
   the same mix into, split per frequency bin between floor and heights by where the objects' energy
   lies (`BedSplitter`). No object signal is mixed into an output; the objects are decoded without
-  their matrix interpolation and taken as points. Measured against the previous exact render through
-  Apple's APAC decode it places the same energy within a few percent, with the heights within a
-  fraction of a dB. Needs LibTrueHD 3.0 (bed companion, per-handle interpolation switch). A 5.1 bed
-  now covers a 7.1 layout's rears as well as its sides. The exact render it is measured against
-  is only built with the measurement-only `TrueHDReferenceRender` trait (#731).
+  their matrix interpolation (LibTrueHD 3.0 no longer compiles the interpolating decode at all) and
+  taken as points at their positions, without size, snap, zones, screen anchoring, the elevation
+  switch or metadata ramps. Measured against the previous exact render through Apple's APAC decode on
+  72 windows of six films, 0.35 % of the energy lands on another speaker (median of the windows with
+  heights), Dolby's Unfold demo 3.3 %, the heights within about a dB. A 5.1 bed now covers a 7.1
+  layout's rears as well as its sides, and the split's 2048-frame latency is drained at the end of
+  input and before every encoder restart. The exact render it is measured against is only built with
+  the measurement-only `TrueHDReferenceRender` trait (#731).
 - **The documentation no longer says TrueHD Atmos objects are always lost.** The Known limitations
   entry in `docs/formats.md`, the `AudioDelivery.bridged` reference and the channel bridge's notes
   predate `objectAudioRendering` (#731) and said objects and heights never survive. They now say the
@@ -41,6 +44,16 @@ the public-API contract.
   decode. `aetherctl play` takes `--atmos-bed` as `serve` does and prints them: on a TrueHD Atmos
   remux, `obj=13/13 up=4 bed=7.1.4`.
 
+### Fixed
+
+- **A slow origin no longer fails large HEVC-in-TS segments on the persistent HTTP/1.1 ingest.**
+  Segment bodies stream to the demuxer instead of downloading whole first, the 45 s ceiling covers
+  only the wait for a response head, and a body ends on its size or on 30 s without a byte (typed
+  `.stalled` rather than the socket's Code=60). One request per origin at a time, so a seek never
+  opens a second connection beside a response in flight (#732).
+- **The relay admits only http and https origins.** A playlist naming another scheme (`file://`
+  included) answers 404 instead of reaching URLSession.
+
 ## [7.39.0] - 2026-10-17
 
 **Not built by default any more: TrueHD Atmos and DTS:X object rendering, Profile 7 FEL dual-layer

From aef8fdbcadc827ec6827b6537bb42ad7f115f668 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 13:55:46 +0200
Subject: [PATCH 128/132] feat: DTS:X in its standard presentation only, one to
 one into 7.1.4 or 9.1.6

With LibDTSX 3.0 the heights are removed from the 7.1 bed by the
standard's own constant fold rather than the gains the stream's metadata
states, and presentations with objects are refused, so they keep the
channel bridge and play as 7.1. DTS:X is now rendered only into the
layouts that carry its bed and four heights one to one (7.1.4, 9.1.6);
any other layout keeps the channel bridge with a log line saying so.
The decoder accepts the twelve standard channels and nothing else, so
no DTS:X channel is ever panned.

Docs, changelog and tests follow; the object tests are gone and the
alternate sample's verdict is now a refusal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  7 +++
 Package.swift                                 |  8 +--
 README.md                                     |  2 +-
 .../Spatial/DTSXObjectAudioDecoder.swift      | 48 +++++++---------
 .../Audio/Spatial/SpatialSpeakerLayout.swift  | 10 ++++
 .../Video/HLSVideoEngine+SpatialAudio.swift   | 17 +++++-
 .../DTSXObjectMetadataMappingTests.swift      | 57 +++++++------------
 Tests/AetherEngineTests/DTSXSampleTests.swift | 41 +++----------
 .../SpatialAudioBridgeTests.swift             |  7 +++
 docs/api.md                                   |  2 +-
 docs/cli.md                                   |  2 +-
 docs/formats.md                               | 12 ++--
 12 files changed, 102 insertions(+), 111 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5ef8073c..f409c4759 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,13 @@ the public-API contract.
   layout's rears as well as its sides, and the split's 2048-frame latency is drained at the end of
   input and before every encoder restart. The exact render it is measured against is only built with
   the measurement-only `TrueHDReferenceRender` trait (#731).
+- **DTS:X plays its standard presentation only, into 7.1.4 or 9.1.6.** With LibDTSX 3.0, the heights
+  are removed from the 7.1 bed by the standard's own constant (each at -3 dB in the speaker under it)
+  instead of the gains the stream's metadata states, which is no longer read; on twelve DTS:X tracks
+  every frame stated exactly that fold, so the output is bit-identical. The alternate presentations,
+  which carry objects (some IMAX-labelled streams), are refused and play as 7.1, and DTS:X is rendered
+  only into the two layouts that carry the bed and the four heights one to one; any other layout
+  keeps the channel bridge. The object position mapping and the fold renderer are gone (#744).
 - **The documentation no longer says TrueHD Atmos objects are always lost.** The Known limitations
   entry in `docs/formats.md`, the `AudioDelivery.bridged` reference and the channel bridge's notes
   predate `objectAudioRendering` (#731) and said objects and heights never survive. They now say the
diff --git a/Package.swift b/Package.swift
index c3a4a3520..492f82b5e 100644
--- a/Package.swift
+++ b/Package.swift
@@ -44,7 +44,7 @@ let package = Package(
         ),
         .trait(
             name: "DTSXObjectAudio",
-            description: "Link LibDTSX and the object renderer, so objectAudioRendering can render DTS:X heights and objects to APAC."
+            description: "Link LibDTSX and the object renderer, so objectAudioRendering can render DTS:X heights to APAC."
         ),
         .trait(
             name: "DualLayerDolbyVision",
@@ -87,9 +87,9 @@ let package = Package(
         // `objectAudioRendering` (#731). The Rust `truehd` crate (Apache-2.0) behind a C API, prebuilt
         // as an xcframework like LibDovi so consumers need no Rust. Pinned to the minor for the same reason.
         .package(url: "https://github.com/superuser404notfound/LibTrueHD", .upToNextMinor(from: "2.3.1")),  // 2.3.1: truehd_atmos_version_string() names the truehd commit actually built in (read from Cargo.lock, LibTrueHD#2), same decoder; 2.3.0: decodes about a third faster again (harletty's truehd speed work: blocks decoded in place, table-driven Huffman, vectorised prediction filters, whole-block matrices; truehdd#42 included), byte-identical output; 2.2.1: rust_eh_personality exported weak, so it coalesces with LibDovi's copy and a host with its own Objective-C and C++ stays within compact unwind's three personality routines (#752); same decoder; 2.2.0: decodes about 30% faster (the truehd crate with its block and PCM buffers sized to the samples they hold, truehdd#42, from a fork of upstream main until that is merged), byte-identical output; 2.1.0: x86_64 in the iOS simulator slice, so a generic iOS Simulator build of a host links; same decoder; 2.0.0: transferred from Silo-Server/SiloObjectAudio and renamed (product TrueHD), rebuilt from source; same decoder as SiloObjectAudio 1.0.0
-        // DTS:X decoder for `objectAudioRendering`: lossless DTS-HD MA with the encoder's height and object
-        // folds removed from the bed, the fixed heights, and the alternate presentations' objects placed in
-        // the same room coordinates as LibTrueHD's. The Rust `dca` crate behind a C API, a port of FFmpeg's
+        // DTS:X decoder for `objectAudioRendering`: lossless DTS-HD MA in its standard presentation, the
+        // four fixed heights removed from the 7.1 bed by the standard's constant fold and returned on their
+        // own channels; presentations with objects are refused. The Rust `dca` crate behind a C API, a port of FFmpeg's
         // LGPL-2.1-or-later dca decoder, so the built library is LGPL-3.0-or-later and ships as a dynamic
         // framework the app embeds, like FFmpegBuild's (#798). Pinned to the minor for the same reason.
         .package(url: "https://github.com/superuser404notfound/LibDTSX", .upToNextMinor(from: "2.0.0")),  // 2.0.0: DTSX.framework, dynamic, exporting only the C API, with dSYMs; NOTICE states the LGPL; same decoder, bit-identical output (#798); 1.0.1: rust_eh_personality weak (#752); dca 0.8.0 (harletty-bridge a717bae); the first two frames after a start or seek only prime the decoder
diff --git a/README.md b/README.md
index 228747877..695b4d9bb 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ A scannable summary; the depth for each row lives in **[docs/formats.md](docs/fo
 | 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 on the native route as single-layer 8.1 (HDR10 base layer on a display without Dolby Vision), or composed dual-layer on Metal with per-frame DV metadata for FEL when `preferDualLayerDolbyVision` is set, the `DualLayerDolbyVision` trait is on and VideoToolbox decodes HEVC in hardware, 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) except the opt-in Profile 7 FEL dual-layer route (`preferDualLayerDolbyVision`, `DualLayerDolbyVision` trait), which runs on the software host and plays an E-AC-3 JOC track as its 5.1 / 7.1 bed without the objects. 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. TrueHD Atmos keeps its heights too, opt-in through `LoadOptions.objectAudioRendering` in a build with the `TrueHDObjectAudio` trait ([Optional components](#optional-components)): the engine decodes the Atmos objects, renders them into a speaker bed and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio ([details](docs/formats.md#truehd-atmos-with-heights)). DTS:X takes the same route with the `DTSXObjectAudio` trait, its heights and objects unfolded from the compatible 7.1 ([details](docs/formats.md#dtsx-with-heights)) |
+| Dolby Atmos | EAC3+JOC stream-copied on every route (HDMI MAT 2.0, AirPods spatial, BT downmix) except the opt-in Profile 7 FEL dual-layer route (`preferDualLayerDolbyVision`, `DualLayerDolbyVision` trait), which runs on the software host and plays an E-AC-3 JOC track as its 5.1 / 7.1 bed without the objects. 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. TrueHD Atmos keeps its heights too, opt-in through `LoadOptions.objectAudioRendering` in a build with the `TrueHDObjectAudio` trait ([Optional components](#optional-components)): the engine decodes the Atmos objects, renders them into a speaker bed and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio ([details](docs/formats.md#truehd-atmos-with-heights)). DTS:X takes the same route with the `DTSXObjectAudio` trait, its four heights unfolded from the compatible 7.1 into 7.1.4 or 9.1.6 ([details](docs/formats.md#dtsx-with-heights)) |
 | Surround | 5.1 / 7.1 with correct `AudioChannelLayout` |
 | Audio-only | `LoadOptions.audioOnly`: lean pipeline, no video machinery, system Now-Playing on tvOS / iOS |
 | Background audio | Audio keeps playing when the app backgrounds on iOS: native AVPlayer stays alive, the software path drops video and keeps decoding audio (`backgroundPlaybackEnabled` / `pictureInPictureActive`); a paused session survives quick app switches for a grace window (`backgroundTeardownGraceSeconds`, default 15 s) before the wedge-safe teardown runs. tvOS tears down immediately (wedge-safe) unless a PiP window is active, which keeps the pipeline and loopback server alive; with PiP the software path keeps decoding video too (the window needs frames). Hosts gate corrective actions on the published `isSessionReady` |
diff --git a/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift b/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
index 324cbe74b..66d60cd16 100644
--- a/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/Spatial/DTSXObjectAudioDecoder.swift
@@ -4,12 +4,11 @@ import Foundation
 import DTSX
 
 /// DTS:X decoder over the LibDTSX library (the Rust `dca` crate behind a C API): lossless decode of
-/// the DTS-HD Master Audio stream DTS:X is carried on, returned the way `TrueHDObjectAudioDecoder`
-/// returns an Atmos presentation. The library does the DTS-specific work: it removes the heights
-/// and objects the encoder folded into the compatible 7.1 bed, so the bed, the four fixed heights
-/// and any objects play side by side, and it places DTS:X's angular object positions in the room
-/// coordinates this renderer and LibTrueHD use (x left→right and y front→back on 0...1, z 0 ear
-/// level to 1 ceiling). What is left here is naming the channels.
+/// the DTS-HD Master Audio stream DTS:X is carried on, in its standard presentation only. The
+/// library removes the four heights from the compatible 7.1 bed, where the encoder folded each at
+/// -3 dB into the speaker under it, and refuses the alternate presentations, which carry objects.
+/// What is left here is naming the twelve channels, each of which plays on its own speaker of a
+/// 7.1.4 or 9.1.6 layout.
 final class DTSXObjectAudioDecoder: ObjectAudioDecoding {
 
     struct DecoderError: Error, CustomStringConvertible {
@@ -98,8 +97,16 @@ final class DTSXObjectAudioDecoder: ObjectAudioDecoding {
 
         let channels = Int(block.channel_count)
         if rolesSerial != block.layout_serial {
+            var named: [ObjectAudioRole] = []
+            for c in 0..<channels {
+                guard let role = Self.role(forSpeaker: block.speakers[c]) else {
+                    throw DecoderError(status: DTSX_ERR_UNSUPPORTED,
+                                       message: "channel with speaker code \(block.speakers[c]) outside DTS:X's 7.1.4")
+                }
+                named.append(role)
+            }
+            roles = named
             rolesSerial = block.layout_serial
-            roles = (0..<channels).map { Self.role(forSpeaker: block.speakers[$0]) }
         }
         planes.removeAll(keepingCapacity: true)
         for c in 0..<channels { planes.append(UnsafePointer(block.channels[c]!)) }
@@ -144,14 +151,11 @@ final class DTSXObjectAudioDecoder: ObjectAudioDecoding {
 
     // MARK: - Mapping
 
-    /// The speaker codes are LibTrueHD's. A DTS:X bed is 7.1 (5.1 under one alternate presentation),
-    /// its four fixed heights are the top front and top back pairs, and the codes beyond those only
-    /// occur in beds no DTS:X stream tested had; each sits at its nominal position, as in
-    /// `TrueHDObjectAudioDecoder`. Objects, and a bed speaker the API has no code for, are
-    /// positioned by metadata.
-    static func role(forSpeaker code: UInt8) -> ObjectAudioRole {
+    /// The speaker codes are LibTrueHD's: the standard presentation's 7.1 bed and its top front and
+    /// top back pairs, each on its own speaker. LibDTSX outputs no other channel.
+    static func role(forSpeaker code: UInt8) -> ObjectAudioRole? {
         switch code {
-        case DTSX_SPEAKER_LFE, DTSX_SPEAKER_LFE2: return .lfe
+        case DTSX_SPEAKER_LFE: return .lfe
         case DTSX_SPEAKER_L: return .bed(.left)
         case DTSX_SPEAKER_R: return .bed(.right)
         case DTSX_SPEAKER_C: return .bed(.center)
@@ -159,27 +163,15 @@ final class DTSXObjectAudioDecoder: ObjectAudioDecoding {
         case DTSX_SPEAKER_RS: return .bed(.sideRight)
         case DTSX_SPEAKER_LB: return .bed(.rearLeft)
         case DTSX_SPEAKER_RB: return .bed(.rearRight)
-        case DTSX_SPEAKER_LW: return .bed(.wideLeft)
-        case DTSX_SPEAKER_RW: return .bed(.wideRight)
         case DTSX_SPEAKER_TFL: return .bed(.topFrontLeft)
         case DTSX_SPEAKER_TFR: return .bed(.topFrontRight)
-        case DTSX_SPEAKER_TSL: return .bed(.topMiddleLeft)
-        case DTSX_SPEAKER_TSR: return .bed(.topMiddleRight)
         case DTSX_SPEAKER_TBL: return .bed(.topRearLeft)
         case DTSX_SPEAKER_TBR: return .bed(.topRearRight)
-        case DTSX_SPEAKER_LSC: return .fixed(SIMD3(0.25, 0, 0))
-        case DTSX_SPEAKER_RSC: return .fixed(SIMD3(0.75, 0, 0))
-        case DTSX_SPEAKER_CB: return .fixed(SIMD3(0.5, 1, 0))
-        case DTSX_SPEAKER_LSD: return .fixed(SpatialSpeaker.sideLeft.position)
-        case DTSX_SPEAKER_RSD: return .fixed(SpatialSpeaker.sideRight.position)
-        case DTSX_SPEAKER_TC: return .fixed(SIMD3(0.5, 0.5, 1))
-        // On the front-top row, where LibTrueHD's TFC and the ceiling pair since #742 sit.
-        case DTSX_SPEAKER_TFC: return .fixed(SIMD3(0.5, 0.25, 1))
-        default: return .object
+        default: return nil
         }
     }
 
-    /// DTS:X states no object gain, size or zone: an element is its room position.
+    /// A channel's element: its speaker's position, playing at unity.
     static func state(for element: DTSXElement) -> ObjectAudioElementState {
         let p = element.position
         return ObjectAudioElementState(
diff --git a/Sources/AetherEngine/Audio/Spatial/SpatialSpeakerLayout.swift b/Sources/AetherEngine/Audio/Spatial/SpatialSpeakerLayout.swift
index b2004ab78..4ca86e774 100644
--- a/Sources/AetherEngine/Audio/Spatial/SpatialSpeakerLayout.swift
+++ b/Sources/AetherEngine/Audio/Spatial/SpatialSpeakerLayout.swift
@@ -37,6 +37,16 @@ public enum SpatialSpeakerLayout: String, Sendable, CaseIterable, Codable {
 
     public var channelCount: Int { speakers.count }
 
+    /// Whether every channel of DTS:X's standard presentation, the 7.1 bed and the four heights, has
+    /// a speaker of its own here, so each plays where it was authored and nothing is re-panned or
+    /// folded: 7.1.4 and 9.1.6.
+    var carriesDTSXOneToOne: Bool {
+        let standard: [SpatialSpeaker] = [.left, .right, .center, .lfe, .sideLeft, .sideRight,
+                                          .rearLeft, .rearRight, .topFrontLeft, .topFrontRight,
+                                          .topRearLeft, .topRearRight]
+        return standard.allSatisfy(speakers.contains)
+    }
+
     /// CoreAudio's tag for this bed. The comments in CoreAudioBaseTypes.h spell the order
     /// `speakers` mirrors.
     public var channelLayoutTag: AudioChannelLayoutTag {
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index 26b45321d..9d5a5a08a 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -61,7 +61,9 @@ extension HLSVideoEngine {
     /// markers, so the label misses some DTS:X, and a DTS-HD MA track that turns out not to be DTS:X
     /// is refused before the bridge is built (`buildSpatialAudioProducerIfEligible`). 48 kHz, or not
     /// yet known, since TrueHD reports its rate from the first frame and both formats are only ever
-    /// authored at 48 kHz. Nil as well when the build lacks the source's decoder trait.
+    /// authored at 48 kHz. Nil as well when the build lacks the source's decoder trait, and for DTS
+    /// when the layout does not carry DTS:X's 7.1 bed and four heights one to one (see
+    /// `SpatialSpeakerLayout.carriesDTSXOneToOne`).
     static func spatialRenderingLayout(
         rendering: ObjectAudioRendering,
         codecID: AVCodecID,
@@ -72,6 +74,10 @@ extension HLSVideoEngine {
               objectAudioSource(codecID: codecID, profile: profile)?.isBuiltIn == true,
               sampleRate == 0 || sampleRate == Int32(ObjectAudioRendering.sampleRate)
         else { return nil }
+        if objectAudioSource(codecID: codecID, profile: profile) == .dtsHDMasterAudio,
+           !layout.carriesDTSXOneToOne {
+            return nil
+        }
         return layout
     }
 
@@ -163,6 +169,13 @@ extension HLSVideoEngine {
                         category: .session
                     )
                 }
+            } else if par.codec_id == AV_CODEC_ID_DTS, let layout = objectAudioRendering.layout,
+                      !layout.carriesDTSXOneToOne {
+                EngineLog.emit(
+                    "[HLSVideoEngine] DTS:X is rendered into 7.1.4 or 9.1.6 only, not \(layout.rawValue); "
+                    + "keeping the channel bridge",
+                    category: .session
+                )
             } else if par.codec_id == AV_CODEC_ID_DTS, objectAudioRendering != .off {
                 // Lossy DTS has no DTS:X to render; only the lossless profiles are offered to LibDTSX.
                 EngineLog.emit(
@@ -310,7 +323,7 @@ extension HLSVideoEngine {
             case .trueHDAtmos:
                 rendering = "channel presentation split into \(layout.rawValue) by the objects' energy"
             case .dtsHDMasterAudio:
-                rendering = "bed, heights and objects rendered into \(layout.rawValue)"
+                rendering = "bed and heights routed one to one into \(layout.rawValue)"
             }
             EngineLog.emit(
                 "[HLSVideoEngine] \(source.name): \(rendering), delivered as \(bridge.hlsCodecs) (lossy)",
diff --git a/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift b/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
index 8670baf8d..17b91506d 100644
--- a/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
+++ b/Tests/AetherEngineTests/DTSXObjectMetadataMappingTests.swift
@@ -5,13 +5,13 @@ import Foundation
 import DTSX
 @testable import AetherEngine
 
-/// LibDTSX places DTS:X in the renderer's room itself; `DTSXObjectAudioDecoder` only names the
+/// LibDTSX returns DTS:X's standard presentation only, and `DTSXObjectAudioDecoder` names its
 /// channels. These pin what a listener would hear wrong: a bed or height channel on the wrong
-/// speaker, or an object somewhere other than where the library put it.
-@Suite("DTS:X metadata maps onto the renderer's room")
+/// speaker, or a channel outside the twelve slipping through to be panned.
+@Suite("DTS:X channels map onto the renderer's speakers")
 struct DTSXObjectMetadataMappingTests {
 
-    @Test("bed and fixed-height speaker codes route to the matching speaker, LFE to LFE, objects are positioned")
+    @Test("bed and height speaker codes route to the matching speaker, LFE to LFE, nothing else is taken")
     func speakerRoles() {
         // The standard DTS:X presentation: a 7.1 bed and the top front and top back pairs.
         let standard: [(UInt8, ObjectAudioRole)] = [
@@ -24,49 +24,34 @@ struct DTSXObjectMetadataMappingTests {
         for (code, role) in standard {
             #expect(DTSXObjectAudioDecoder.role(forSpeaker: code) == role, "speaker \(code)")
         }
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_LW) == .bed(.wideLeft))
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_TSR) == .bed(.topMiddleRight))
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_TFC) == .fixed(SIMD3(0.5, 0.25, 1)))
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_LSD) == .fixed(SpatialSpeaker.sideLeft.position))
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_RSD) == .fixed(SpatialSpeaker.sideRight.position))
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_OBJECT) == .object)
-        #expect(DTSXObjectAudioDecoder.role(forSpeaker: DTSX_SPEAKER_UNKNOWN) == .object)
+        for code in [DTSX_SPEAKER_OBJECT, DTSX_SPEAKER_UNKNOWN, DTSX_SPEAKER_LW, DTSX_SPEAKER_TSR,
+                     DTSX_SPEAKER_TFC, DTSX_SPEAKER_CB, DTSX_SPEAKER_LFE2] {
+            #expect(DTSXObjectAudioDecoder.role(forSpeaker: code) == nil, "speaker \(code)")
+        }
+    }
+
+    @Test("the standard channels play one to one on 7.1.4 and 9.1.6, and only there")
+    func oneToOneLayouts() {
+        for layout in SpatialSpeakerLayout.allCases {
+            #expect(layout.carriesDTSXOneToOne == (layout == .l714 || layout == .l916), "\(layout.rawValue)")
+        }
     }
 
-    @Test("an object keeps the room position the library gave it, at its gain")
-    func object() {
+    @Test("a channel plays at unity while active")
+    func channelState() {
         var element = DTSXElement()
-        element.kind = DTSX_ELEMENT_OBJECT
-        element.speaker = DTSX_SPEAKER_OBJECT
+        element.kind = DTSX_ELEMENT_BED
+        element.speaker = DTSX_SPEAKER_TFL
         element.flags = DTSX_ELEMENT_ACTIVE
-        element.position = (1, 0.0375, 0.2667)
+        element.position = (0, 0, 1)
         element.gain = 1
         let state = DTSXObjectAudioDecoder.state(for: element)
-        #expect(state.position == SIMD3(1, 0.0375, 0.2667))
+        #expect(state.position == SIMD3(0, 0, 1))
         #expect(state.gain == 1)
-        #expect(state.size == 0 && !state.snap && state.excluded.isEmpty)
-
         element.flags = 0
         #expect(DTSXObjectAudioDecoder.state(for: element).gain == 0)
     }
 
-    @Test("an IMAX front object at 34.5°, 12° up plays mostly from its front speaker, partly from the top front")
-    func imaxFrontObjectThroughThePanner() {
-        // Independence Day's DTS:X carries two static objects at azimuth ±34.5°, elevation 12°.
-        // LibDTSX places the right one on the right wall 0.0375 of the way back, 12/45 up; panned,
-        // the floor gets cos and the ceiling sin of 12/45 of a quarter turn, as by angle.
-        let layout = SpatialSpeakerLayout.l714
-        var gains: [Float] = []
-        AllocentricPanner(layout: layout).objectGains(
-            position: SIMD3(1, 0.0375, 12.0 / 45), size: 0, snap: false, into: &gains)
-        let gain = { (speaker: SpatialSpeaker) in gains[layout.speakers.firstIndex(of: speaker)!] }
-        let floor = cos(Float(12.0 / 45) * .pi / 2), ceiling = sin(Float(12.0 / 45) * .pi / 2)
-        #expect(abs(gain(.right) - floor * cos(0.075 * .pi / 2)) < 1e-4)
-        #expect(abs(gain(.sideRight) - floor * sin(0.075 * .pi / 2)) < 1e-4)
-        #expect(gain(.topFrontRight) > 0.95 * ceiling)
-        #expect(gain(.left) == 0 && gain(.topFrontLeft) == 0 && gain(.rearRight) == 0)
-    }
-
     @Test("the decoder opens, takes input and asks for more")
     func decoderLifecycle() throws {
         let decoder = try DTSXObjectAudioDecoder()
diff --git a/Tests/AetherEngineTests/DTSXSampleTests.swift b/Tests/AetherEngineTests/DTSXSampleTests.swift
index 7acde0cfa..3b93ad865 100644
--- a/Tests/AetherEngineTests/DTSXSampleTests.swift
+++ b/Tests/AetherEngineTests/DTSXSampleTests.swift
@@ -9,7 +9,8 @@ import AetherLibavutil
 /// End to end on real DTS-HD elementary streams: verdict, decode, render, encode. The samples are
 /// not in the repository, so each test runs only when its variable names a `.dts` file:
 /// `AE_DTSX_SAMPLE` the "DTS:X Object Emulator" demo (standard 7.1.4, 95 s),
-/// `AE_DTSX_ALTERNATE_SAMPLE` Trinnov's "Experience" trailer (7.1.4 plus five moving objects, 44 s),
+/// `AE_DTSX_ALTERNATE_SAMPLE` Trinnov's "Experience" trailer (7.1.4 plus five moving objects, 44 s,
+/// refused),
 /// `AE_DTS_HD_MA_SAMPLE` a DTS-HD Master Audio stream without DTS:X (FFmpeg's FATE
 /// `dts/master_audio_7.1_24bit.dts`). LibDTSX's README says where to get them.
 @Suite("DTS:X samples, decode to APAC")
@@ -35,13 +36,18 @@ struct DTSXSampleTests {
         }
     }
 
-    @Test("DTS:X is recognised on its head and plain DTS-HD MA is refused")
+    @Test("DTS:X is recognised on its head; objects and plain DTS-HD MA are refused")
     func verdicts() throws {
         if let data = Self.sample("AE_DTSX_SAMPLE") {
             #expect(try Self.verdict(data.prefix(1 << 20)) == .renders("7.1.4"))
         }
         if let data = Self.sample("AE_DTSX_ALTERNATE_SAMPLE") {
-            #expect(try Self.verdict(data.prefix(1 << 20)) == .renders("7.1.4+5"))
+            let verdict = try Self.verdict(data.prefix(1 << 20))
+            guard case .refused(let reason) = verdict else {
+                Issue.record("the alternate presentation was not refused: \(String(describing: verdict))")
+                return
+            }
+            #expect(reason.contains("7.1.4+5"), "\(reason)")
         }
         if let data = Self.sample("AE_DTS_HD_MA_SAMPLE") {
             let verdict = try Self.verdict(data.prefix(1 << 20))
@@ -116,35 +122,6 @@ struct DTSXSampleTests {
         }
     }
 
-    @Test("alternate-presentation objects move, and render where LibDTSX placed them")
-    func alternateObjectsMove() throws {
-        guard let data = Self.sample("AE_DTSX_ALTERNATE_SAMPLE") else { return }
-        let decoder = try DTSXObjectAudioDecoder()
-        var objects = 0, ramps = 0, positions = Set<SIMD3<Float>>()
-        try data.withUnsafeBytes { raw in
-            var offset = 0
-            while offset < raw.count {
-                let n = min(65536, raw.count - offset)
-                try decoder.push(UnsafeRawBufferPointer(rebasing: raw[offset..<offset + n]))
-                offset += n
-                while let block = try decoder.nextBlock() {
-                    objects = block.roles.filter { $0 == .object }.count
-                    for update in block.updates {
-                        if update.rampFrames == block.frameCount { ramps += 1 }
-                        for (i, state) in update.states.enumerated() where block.roles[i] == .object {
-                            if let state { positions.insert(state.position) }
-                        }
-                    }
-                }
-            }
-        }
-        print("[DTSXSample] alternate: \(objects) objects, \(ramps) ramped updates, \(positions.count) positions")
-        #expect(objects == 5)
-        #expect(ramps > 900, "moving objects ramp over the frame that moves them")
-        #expect(positions.count > 1000)
-        #expect(positions.allSatisfy { p in (0...1).contains(p.x) && (0...1).contains(p.y) && (0...1).contains(p.z) })
-    }
-
     @Test("the bridge turns the whole standard sample into contiguous APAC packets")
     func bridgesToAPAC() throws {
         guard let data = Self.sample("AE_DTSX_SAMPLE") else { return }
diff --git a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
index 2db79ee2f..5673847d9 100644
--- a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
@@ -178,6 +178,13 @@ struct SpatialAudioBridgeTests {
             #expect(HLSVideoEngine.spatialRenderingLayout(rendering: on, codecID: AV_CODEC_ID_DTS, profile: profile, sampleRate: 48_000) == .l714)
             #expect(HLSVideoEngine.objectAudioSource(codecID: AV_CODEC_ID_DTS, profile: profile) == .dtsHDMasterAudio)
         }
+        // Only layouts that carry the 7.1 bed and the four heights one to one.
+        for layout in SpatialSpeakerLayout.allCases {
+            let expected: SpatialSpeakerLayout? = layout == .l714 || layout == .l916 ? layout : nil
+            #expect(HLSVideoEngine.spatialRenderingLayout(
+                rendering: .apac(layout), codecID: AV_CODEC_ID_DTS, profile: AV_PROFILE_DTS_HD_MA_X,
+                sampleRate: 48_000) == expected, "\(layout.rawValue)")
+        }
         for profile in [AV_PROFILE_DTS, AV_PROFILE_DTS_ES, AV_PROFILE_DTS_HD_HRA, AV_PROFILE_DTS_EXPRESS] {
             #expect(HLSVideoEngine.spatialRenderingLayout(rendering: on, codecID: AV_CODEC_ID_DTS, profile: profile, sampleRate: 48_000) == nil)
         }
diff --git a/docs/api.md b/docs/api.md
index 16362779c..6c9cd68e0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1299,7 +1299,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `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. |
-| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731), in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default, [README › Optional components](../README.md#optional-components)); without a codec's trait the option is accepted and that codec keeps `audioBridgeMode`. `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights and objects, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X on its first frames (whatever FFmpeg's label), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Without a codec's trait that codec keeps the channel bridge and the automatic audio pick does not prefer it; `AetherEngine.OptionalComponent` tells a host which codecs a build renders. |
+| `objectAudioRendering` | `.off` | TrueHD Atmos and DTS:X with heights (#731), in a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` package traits (off by default, [README › Optional components](../README.md#optional-components)); without a codec's trait the option is accepted and that codec keeps `audioBridgeMode`. `.apac(SpatialSpeakerLayout)` decodes the Atmos objects, or DTS:X's heights, renders them into that bed (`.l512`, `.l514`, `.l712`, `.l714`, `.l916`) and delivers Apple Positional Audio, which tvOS sends to an Atmos receiver as Dolby MAT and iOS plays as Spatial Audio. Lossy (320 kbps per bed channel) in place of the lossless 7.1 the bridge delivers, so it is the host's choice. Only TrueHD that FFmpeg marks Atmos, and DTS-HD Master Audio that LibDTSX confirms as DTS:X in its standard presentation on its first frames (whatever FFmpeg's label; DTS:X only into `.l714` or `.l916`), at 48 kHz, on OS 26+; anything else, or any failure to start, keeps `audioBridgeMode`. With it on, the automatic audio pick prefers a TrueHD Atmos or DTS:X-labelled track over the other tracks of the same language (of the `preferredAudioLanguages` match, or of the default track when no preference decides), never across a language or dub and never over `audioSourceStreamIndexOverride`, and only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later). `SpatialSpeaker` names the positions. See [formats.md](formats.md#truehd-atmos-with-heights) and [DTS:X](formats.md#dtsx-with-heights). Without a codec's trait that codec keeps the channel bridge and the automatic audio pick does not prefer it; `AetherEngine.OptionalComponent` tells a host which codecs a build renders. |
 | `confirmAtmos` | false | Background per-track JOC confirmation, republishing `audioTracks` as tracks confirm. Never on the start path; skipped for live and forward-only readers. |
 | `preferredAudioLanguages` | empty | First-frame audio pick from the engine's single probe. Ordered BCP-47 / ISO 639 tags; region and script are normalized and rank within one preference (#590). An explicit `audioSourceStreamIndex` still wins. |
 | `preferredSubtitleLanguages` | empty | Post-load subtitle activation on the host-overlay path. Ranks language specificity (an explicitly opposite script is rejected, not demoted) before the descriptor axis. Pure convenience: no reload and no pre-probe, unlike the audio equivalent. |
diff --git a/docs/cli.md b/docs/cli.md
index d37a9b40b..3bb45fbcc 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -75,7 +75,7 @@ open 'http://127.0.0.1:<port>/<token>/master.m3u8'   # macOS QuickTime
 
 `--start-position S` starts the session at S seconds, the resume anchor a host passes to `load(url:startPosition:)`. Also available on `play`.
 
-`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: channel presentation split into … by the objects' energy` (or `DTS:X: bed, heights and objects rendered into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`. In a build with the `TrueHDReferenceRender` trait (and a LibTrueHD built with `matrix-interpolation`), `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment decodes the TrueHD track exactly and mixes its objects through the renderer instead (`… objects rendered into 7.1.4 (reference render, …)`), the reference the split is measured against: serve the file both ways, decode each APAC track to PCM and compare per channel.
+`--atmos-bed <layout>` is `LoadOptions.objectAudioRendering = .apac(layout)` (`5.1.2`, `5.1.4`, `7.1.2`, `7.1.4` or `9.1.6`, #731, #744), rendered only by a build with the `TrueHDObjectAudio` / `DTSXObjectAudio` traits: a TrueHD Atmos or DTS:X track is rendered into that bed and served as APAC, so a master reads `CODECS="…,apac.31.03"` (up to 12 channels) or `apac.31.04` (16), and the log carries `TrueHD Atmos: channel presentation split into … by the objects' energy` (or `DTS:X: bed and heights routed one to one into …`) and the `[SpatialAudioBridge] bed levels` lines. A DTS-HD MA track that LibDTSX does not confirm as DTS:X logs `DTS-HD MA track is not DTS:X LibDTSX renders (…); keeping the channel bridge` instead. `--audio-index <n>` serves source stream `n`, as a host's audio picker would. Dolby's Unfold demo, whose TrueHD Atmos track is stream 1: `serve --no-dv --atmos-bed 7.1.4 --audio-index 1 unfold.m2ts`. In a build with the `TrueHDReferenceRender` trait (and a LibTrueHD built with `matrix-interpolation`), `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment decodes the TrueHD track exactly and mixes its objects through the renderer instead (`… objects rendered into 7.1.4 (reference render, …)`), the reference the split is measured against: serve the file both ways, decode each APAC track to PCM and compare per channel.
 
 `--audio-delay <ms>` parks the server with the AE#464 audio offset already in its muxer, which is how the DELIVERED offset is measured rather than argued about: fetch the media playlist and walk its segments, then read the first audio and video packet timestamps out of `init.mp4` + a segment with `ffprobe -show_entries packet=stream_index,pts_time`. On a 30 fps H.264 + AAC fixture the source's own alignment is +21.8 ms, `--audio-delay 200` reads +221.8 ms and `--audio-delay -150` reads -128.2 ms, i.e. exactly the offset asked for, with the video timestamp unchanged in every arm.
 
diff --git a/docs/formats.md b/docs/formats.md
index 27a3b5993..f1b795966 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -352,7 +352,7 @@ Apple TV cannot bitstream TrueHD, and no Apple platform hands a third-party app
 
 **How the bed is built.** Every output is a share of the stream's channel presentation (`BedSplitter`). Per STFT bin (2048-frame Hann windows, 512-frame hop), each of its channels is divided between the floor speakers it covers and the heights, in proportion to how much of that bin's energy comes from objects at each place: an object's part is its spectral energy times its ear-level gain into the channel, and it goes up in proportion to its layout gains above ear level. The objects only say where energy lies; no object signal reaches an output, so they are decoded without the stream's matrix interpolation values (LibTrueHD's `set_ignore_interpolation`, the channel presentation comes from the same access units through `set_bed_companion`) and taken as plain points at their positions, without size, snap, zones, screen anchoring or the elevation switch. Two corrections keep the estimate honest. Per band, an object holds no more than twice the energy its bed channels allow it, which keeps the decoding residue in quiet objects from pulling a quiet channel's content up or sideways. And per output and band, an output the split leaves short of the energy a direct render would give it is raised towards it (smoothed over about 200 ms, at most 6 dB), and one the split leaves above it is lowered by only a third of the gap in dB: objects carrying the same signal add up to more in a mix than their energies do, so a lower estimate is mostly the estimate's shortfall. A 7.1 bed maps one to one onto a 7.1 floor, a 5.1 bed's surrounds cover a 7.1 layout's sides and rears, a 7.1 bed's rears fold onto a 5.1 floor, and the LFE is the bed's own. The split runs 2048 frames behind its input: the bridge starts its output that much later after every reset and drains it before the encoder restarts elsewhere and at the end of input, so nothing moves against the picture and nothing is cut off. The exact decode mixed by the renderer, which the split is measured against, is only built with the `TrueHDReferenceRender` package trait and a LibTrueHD built with its `matrix-interpolation` feature (measurement builds, never shipped); `AETHER_TRUEHD_REFERENCE_RENDER=1` in the environment then selects it. A shipped build contains neither the interpolating decode nor the size, snap, zone, screen and elevation mapping for TrueHD.
 
-The renderer, which gives the split its object gains and mixes DTS:X directly, is allocentric, the model Atmos metadata is authored in: the room is a unit cube, and an object is balanced constant-power between the two speaker planes that bracket its height, the two rows that bracket its depth and the two speakers that bracket its width, so moving an object never changes its loudness. Ceiling speakers sit where ETSI TS 103 448 puts them, a quarter of the room in from each wall rather than in its corners, so an object on the ceiling a third of the way back plays mostly from the front tops, as Apple's own Atmos render places it. A 5.1 bed's surrounds sit halfway down the side walls, also as TS 103 448 places them, so on 5.1.2 and 5.1.4 an object at the back wall stays on them. For DTS:X, object size spreads it over a grid of points summed by power, snap sends it to the nearest speaker, zone masks keep it off the speakers they exclude, and an object without elevation stays off the ceiling. Bed channels the layout has route discretely, LFE goes to the LFE channel, and metadata updates ramp gains sample-accurately as the stream specifies. After a seek, decoding resumes at the next major sync, and the stream's first object metadata follows it up to 32 ms later; the decoder holds the audio in between and plays it at that metadata's positions, rather than leaving every object silent until it arrives (it waits at most 100 ms).
+The renderer, which gives the split its object gains and routes DTS:X's channels, is allocentric, the model Atmos metadata is authored in: the room is a unit cube, and an object is balanced constant-power between the two speaker planes that bracket its height, the two rows that bracket its depth and the two speakers that bracket its width, so moving an object never changes its loudness. Ceiling speakers sit where ETSI TS 103 448 puts them, a quarter of the room in from each wall rather than in its corners, so an object on the ceiling a third of the way back plays mostly from the front tops, as Apple's own Atmos render places it. A 5.1 bed's surrounds sit halfway down the side walls, also as TS 103 448 places them, so on 5.1.2 and 5.1.4 an object at the back wall stays on them. In the `TrueHDReferenceRender` measurement build, object size spreads an object over a grid of points summed by power, snap sends it to the nearest speaker, zone masks keep it off the speakers they exclude, and an object without elevation stays off the ceiling. Bed channels the layout has route discretely, LFE goes to the LFE channel, and metadata updates ramp gains sample-accurately as the stream specifies. After a seek, decoding resumes at the next major sync, and the stream's first object metadata follows it up to 32 ms later; the decoder holds the audio in between and plays it at that metadata's positions, rather than leaving every object silent until it arrives (it waits at most 100 ms).
 
 **Track choice.** With the option on, the automatic audio pick prefers a TrueHD Atmos track over the other tracks of the same language: of the `preferredAudioLanguages` match, or of the session's default track when no preference decides it. It never crosses a language or a dub (a region or script both tags state and disagree on), never picks a commentary for it, applies only where the bed can be rendered (a VOD video session off the software path, on OS 26 or later), and an explicit `audioSourceStreamIndexOverride` still wins. Without that, a film carrying DTS-HD and TrueHD Atmos in one language usually opened on whichever the container listed first.
 
@@ -370,17 +370,17 @@ many objects play and how many overhead without reading the log.
 
 ### DTS\:X with heights
 
-DTS:X reaches the bridge the same way TrueHD Atmos does: Apple TV cannot bitstream DTS-HD, so `audioBridgeMode` decodes the lossless 7.1, and on a DTS:X track that 7.1 is a compatible downmix into which the encoder folded the four height channels and any objects. `objectAudioRendering = .apac(layout)` keeps them in a build with the `DTSXObjectAudio` package trait (off by default; without it DTS-HD keeps the channel bridge whatever the option asks, [README › Optional components](../README.md#optional-components)): a DTS-HD Master Audio track goes through [LibDTSX](https://github.com/superuser404notfound/LibDTSX) (the `dca` crate from harletty-bridge behind a C API, packaged like LibTrueHD) into the same renderer, limiter and APAC encoder. LibDTSX does the DTS-specific work, so the engine side is a speaker mapping (`DTSXObjectAudioDecoder`): it subtracts every fold the frame states (or that `dca`'s fold renderer recomputes for an object the encoder panned into the bed) from the bed, so the bed, the heights and the objects play side by side without anything playing twice, and it places DTS:X's angular object positions in LibTrueHD's room coordinates. The reference sphere is projected onto the room's boundary through the speakers' angles (centre 0°, front ±30°, wide ±60°, side ±90°, rear ±145°), the ceiling reached at the 45° of a height speaker and its centre straight overhead, so the dual-balance panner places a sound between two speakers in the same proportion an angular panner would. LibDTSX comes with the `DTSXObjectAudio` package trait, off by default, in the same way.
+DTS:X reaches the bridge the same way TrueHD Atmos does: Apple TV cannot bitstream DTS-HD, so `audioBridgeMode` decodes the lossless 7.1, and on a DTS:X track that 7.1 is a compatible downmix into which the encoder folded the four height channels. `objectAudioRendering = .apac(layout)` keeps them in a build with the `DTSXObjectAudio` package trait (off by default; without it DTS-HD keeps the channel bridge whatever the option asks, [README › Optional components](../README.md#optional-components)): a DTS-HD Master Audio track goes through [LibDTSX](https://github.com/superuser404notfound/LibDTSX) (the `dca` crate from harletty-bridge behind a C API, packaged like LibTrueHD) into the same renderer, limiter and APAC encoder, and the engine side is a speaker mapping (`DTSXObjectAudioDecoder`).
 
-The standard presentation, which every DTS:X film in SpatialAudioBridge's library census used in every frame, is a 7.1 bed and four fixed heights (top front and top back pairs), all routed discretely: rendered into 7.1.4, *8 Mile*, *The Bourne Identity* and the DTS:X Object Emulator demo give each speaker exactly its channel, bit for bit what SpatialAudioBridge's DTS:X renderer gives. The alternate presentations add one to five objects; `dca` classifies them from a corpus and calls them experimental. *Independence Day* (FFmpeg: "DTS-HD MA + DTS:X IMAX") is one: two static objects at ±34.5° and 12° up, which pan mostly into the front pair, a little into the sides and the front heights. Against SpatialAudioBridge's renderer, which pans DTS:X by angle over a bed ring and a height ring, the 7.1.4 render of a minute of it points the sound the same way within 0.07° (median of 200 ms windows, energy-weighted; 90th percentile 0.39°), and of the D4 trailer's five moving objects within 0.23° (2.3°); the floor channels correlate at 1.0000, and the ceiling's share of the energy is 0.1 to 0.2 points lower. These figures were taken against the panner before #742 moved its top speakers from the room's corners a quarter in, so the object renders now differ from them slightly; the standard presentation routes discretely and is unaffected.
+Only DTS:X's standard presentation is rendered: a 7.1 bed and four fixed heights (the top front and top back pairs), each height folded at -3 dB into the bed speaker under it (top front left into L, top back left into the left rear, and so on) so that a 7.1 decoder plays the whole soundtrack. LibDTSX subtracts exactly that constant from the bed and returns the heights on their own channels; it does not read the stream's private metadata. Every frame of twelve DTS:X tracks measured (eight *Harry Potter* films, two *Shrek* films in two languages, *Mary and the Witch's Flower*) stated this same fold, so the result is bit-identical to subtracting what each frame states. The bed and the heights route discretely, one channel per speaker, so DTS:X is rendered into the two layouts that carry all twelve one to one, 7.1.4 and 9.1.6; any other layout keeps the channel bridge, and so does a track in one of the alternate presentations, which add one to five objects (some IMAX-labelled streams, Trinnov's "Experience" trailer): LibDTSX refuses those on their first frame, and they play as the 7.1 their compatible bed is.
 
-**Which tracks.** FFmpeg names only two of DTS:X's markers, so it labels some DTS:X plain "DTS-HD MA" (Trinnov's "Experience" trailer, with five moving objects, is one), and a track it does label DTS:X can carry a presentation LibDTSX refuses. Every 48 kHz DTS-HD MA track is therefore offered to LibDTSX, which decides on the track's first three frames. The engine shows them to it through the demuxer's peek (`peekPackets`), which holds what it reads for the producer, so deciding costs no extra read and no seek: on a resume the demuxer is put where the first producer starts before the peek, not after it, and the frames there decide. The peek holds at most 512 packets or 24 MiB, every stream's included, and gives up without a verdict past either. A refused track, or one without a verdict, keeps `audioBridgeMode` with its lossless 7.1 as before, and a stream that turns out not to be 48 kHz is refused on its first block. Lossy DTS (core, ES, 96/24, High Resolution) is never offered. The automatic audio pick prefers a track FFmpeg labels DTS:X the way it prefers TrueHD Atmos; a plain-labelled DTS:X track is rendered when it is the track that plays, but cannot be ranked before playback.
+**Which tracks.** FFmpeg names only two of DTS:X's markers, so it labels some DTS:X plain "DTS-HD MA" (Trinnov's "Experience" trailer is one), and a track it does label DTS:X can carry a presentation LibDTSX refuses. Every 48 kHz DTS-HD MA track is therefore offered to LibDTSX, which decides on the track's first three frames. The engine shows them to it through the demuxer's peek (`peekPackets`), which holds what it reads for the producer, so deciding costs no extra read and no seek: on a resume the demuxer is put where the first producer starts before the peek, not after it, and the frames there decide. The peek holds at most 512 packets or 24 MiB, every stream's included, and gives up without a verdict past either. A refused track, or one without a verdict, keeps `audioBridgeMode` with its lossless 7.1 as before, and a stream that turns out not to be 48 kHz is refused on its first block. Lossy DTS (core, ES, 96/24, High Resolution) is never offered. The automatic audio pick prefers a track FFmpeg labels DTS:X the way it prefers TrueHD Atmos; a plain-labelled DTS:X track is rendered when it is the track that plays, but cannot be ranked before playback.
 
 **Seeks.** A DTS-HD Master Audio frame is lossless only against the core decoder's filter and predictor history, which a stream entered mid-way does not have: the first frame after a seek decodes distorted (over 120 seeks into five DTS:X streams, its error a median 2.7 dB below the signal) and the next can still err by -16 dBFS. LibDTSX decodes the first two frames after a start or seek without output and counts them on its input timeline, so the bridge's first encoded frame sits 21 ms after the segment's start, where those frames end, and nothing fills the gap; the first block then differs from a continuous decode by at most -33 dBFS, and the output is bit-identical again within about ten frames.
 
-**On the receiver.** Over Jellyfin on an Apple TV 4K (tvOS 27.2), *8 Mile*, *The Bourne Identity* and *Independence Day* played as APAC with the soundbar showing Atmos, from the middle of the film and across seeks (back to playing in 0.7 to 2.2 s), with the same `AtmosOutputActivator` TrueHD Atmos uses; *Arrival*, plain DTS-HD MA, was refused on its first frame and showed PCM.
+**On the receiver.** Over Jellyfin on an Apple TV 4K (tvOS 27.2), *8 Mile* and *The Bourne Identity* played as APAC with the soundbar showing Atmos, from the middle of the film and across seeks (back to playing in 0.7 to 2.2 s), with the same `AtmosOutputActivator` TrueHD Atmos uses; *Arrival*, plain DTS-HD MA, was refused on its first frame and showed PCM. Those runs predate the standard-only decoder, whose output for these films is the same bit for bit.
 
-**What the session log says.** `[HLSVideoEngine] DTS-HD MA track is DTS:X 7.1.4 (LibDTSX, 3 ms)` names the presentation the verdict found (`7.1.4+2` for *Independence Day*), and a refusal names its reason (`lossless DTS-HD Master Audio without a DTS:X extension`). The `object configuration` and `bed levels` lines are the same as for TrueHD Atmos. The 1200-packet silence report is too: at 512 samples a DTS frame that is 12.8 s of DTS, against a second of TrueHD.
+**What the session log says.** `[HLSVideoEngine] DTS-HD MA track is DTS:X 7.1.4 (LibDTSX, 3 ms)` names the presentation the verdict found, and a refusal names its reason (`lossless DTS-HD Master Audio without a DTS:X extension`, or for *Independence Day* `DTS:X in the 7.1.4+2 presentation, with objects: only the standard 7.1.4 presentation is rendered`). A layout other than 7.1.4 or 9.1.6 logs `DTS:X is rendered into 7.1.4 or 9.1.6 only`. The `object configuration` and `bed levels` lines are the same as for TrueHD Atmos. The 1200-packet silence report is too: at 512 samples a DTS frame that is 12.8 s of DTS, against a second of TrueHD.
 
 ## Subtitles
 

From c1dbd41d4f413c79b63a3abb271e56fa0447985f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 14:52:49 +0200
Subject: [PATCH 129/132] chore(release): prep 7.40.0 - TrueHD Atmos from the
 channel presentation, DTS:X standard presentation only

LibTrueHD 3.0.0 (bed companion, interpolation out of the default build)
and LibDTSX 3.0.0 (standard presentation, constant height fold). Version
sweep, changelog folded, README notes the pbxproj traits form.

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 +-
 Package.resolved                                | 10 +++++-----
 Package.swift                                   |  4 ++--
 README.md                                       | 10 +++++-----
 Sources/AetherEngine/AetherEngine+Version.swift |  2 +-
 6 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f409c4759..f60dfff18 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.40.0] - 2026-10-18
+
 ### Changed
 
 - **TrueHD Atmos is built from the stream's own channel presentation.** With `objectAudioRendering`
diff --git a/Examples/README.md b/Examples/README.md
index ceacda69c..36a1954d3 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.39.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.40.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/Package.resolved b/Package.resolved
index fd0a9b6c9..533276d54 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,5 +1,5 @@
 {
-  "originHash" : "856dc654c740b018d3c4a31d0d78988b4c57927f83aa3d4d22ee9c48b424e1b6",
+  "originHash" : "7816b11b113ce741ab17b588aa7b4d9eb9f27d3c190e97a227916509bcc7ba8d",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
@@ -24,8 +24,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/superuser404notfound/LibDTSX",
       "state" : {
-        "revision" : "1f0dd2daaaeb899b694e8502a5bb6f570046f4f3",
-        "version" : "2.0.0"
+        "revision" : "7d68c8bbda348a10e169b9bb9619c8b2b7a0c642",
+        "version" : "3.0.0"
       }
     },
     {
@@ -33,8 +33,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/superuser404notfound/LibTrueHD",
       "state" : {
-        "revision" : "3eab2e7c10ff1b3c2078afbab138471f2511859b",
-        "version" : "2.3.1"
+        "revision" : "aebd5ffe1046dadbea833ce87a75d00fd8b1edd1",
+        "version" : "3.0.0"
       }
     },
     {
diff --git a/Package.swift b/Package.swift
index 492f82b5e..76b34b82e 100644
--- a/Package.swift
+++ b/Package.swift
@@ -86,13 +86,13 @@ let package = Package(
         // TrueHD decoder that also decodes the Atmos object presentation (beds, objects, OAMD) for
         // `objectAudioRendering` (#731). The Rust `truehd` crate (Apache-2.0) behind a C API, prebuilt
         // as an xcframework like LibDovi so consumers need no Rust. Pinned to the minor for the same reason.
-        .package(url: "https://github.com/superuser404notfound/LibTrueHD", .upToNextMinor(from: "2.3.1")),  // 2.3.1: truehd_atmos_version_string() names the truehd commit actually built in (read from Cargo.lock, LibTrueHD#2), same decoder; 2.3.0: decodes about a third faster again (harletty's truehd speed work: blocks decoded in place, table-driven Huffman, vectorised prediction filters, whole-block matrices; truehdd#42 included), byte-identical output; 2.2.1: rust_eh_personality exported weak, so it coalesces with LibDovi's copy and a host with its own Objective-C and C++ stays within compact unwind's three personality routines (#752); same decoder; 2.2.0: decodes about 30% faster (the truehd crate with its block and PCM buffers sized to the samples they hold, truehdd#42, from a fork of upstream main until that is merged), byte-identical output; 2.1.0: x86_64 in the iOS simulator slice, so a generic iOS Simulator build of a host links; same decoder; 2.0.0: transferred from Silo-Server/SiloObjectAudio and renamed (product TrueHD), rebuilt from source; same decoder as SiloObjectAudio 1.0.0
+        .package(url: "https://github.com/superuser404notfound/LibTrueHD", .upToNextMinor(from: "3.0.0")),  // 3.0.0: API 2, the bed companion (the channel presentation decoded with the object presentation) and a per-handle interpolation switch; the interpolating decode is an opt-in build feature, off in the shipped binary (#731); 2.3.1: truehd_atmos_version_string() names the truehd commit actually built in (read from Cargo.lock, LibTrueHD#2), same decoder; 2.3.0: decodes about a third faster again (harletty's truehd speed work: blocks decoded in place, table-driven Huffman, vectorised prediction filters, whole-block matrices; truehdd#42 included), byte-identical output; 2.2.1: rust_eh_personality exported weak, so it coalesces with LibDovi's copy and a host with its own Objective-C and C++ stays within compact unwind's three personality routines (#752); same decoder; 2.2.0: decodes about 30% faster (the truehd crate with its block and PCM buffers sized to the samples they hold, truehdd#42, from a fork of upstream main until that is merged), byte-identical output; 2.1.0: x86_64 in the iOS simulator slice, so a generic iOS Simulator build of a host links; same decoder; 2.0.0: transferred from Silo-Server/SiloObjectAudio and renamed (product TrueHD), rebuilt from source; same decoder as SiloObjectAudio 1.0.0
         // DTS:X decoder for `objectAudioRendering`: lossless DTS-HD MA in its standard presentation, the
         // four fixed heights removed from the 7.1 bed by the standard's constant fold and returned on their
         // own channels; presentations with objects are refused. The Rust `dca` crate behind a C API, a port of FFmpeg's
         // LGPL-2.1-or-later dca decoder, so the built library is LGPL-3.0-or-later and ships as a dynamic
         // framework the app embeds, like FFmpegBuild's (#798). Pinned to the minor for the same reason.
-        .package(url: "https://github.com/superuser404notfound/LibDTSX", .upToNextMinor(from: "2.0.0")),  // 2.0.0: DTSX.framework, dynamic, exporting only the C API, with dSYMs; NOTICE states the LGPL; same decoder, bit-identical output (#798); 1.0.1: rust_eh_personality weak (#752); dca 0.8.0 (harletty-bridge a717bae); the first two frames after a start or seek only prime the decoder
+        .package(url: "https://github.com/superuser404notfound/LibDTSX", .upToNextMinor(from: "3.0.0")),  // 3.0.0: the standard presentation only, its heights removed by the standard's constant fold without reading the metadata, presentations with objects refused; same output for standard DTS:X (#744); 2.0.0: DTSX.framework, dynamic, exporting only the C API, with dSYMs; NOTICE states the LGPL; same decoder, bit-identical output (#798); 1.0.1: rust_eh_personality weak (#752); dca 0.8.0 (harletty-bridge a717bae); the first two frames after a start or seek only prime the decoder
     ],
     targets: [
         .target(
diff --git a/README.md b/README.md
index 695b4d9bb..6385f6447 100644
--- a/README.md
+++ b/README.md
@@ -387,7 +387,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.39.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -634,10 +634,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.39.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.39.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.40.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
@@ -672,11 +672,11 @@ These components may be subject to third-party patent licensing. Integrators who
 To enable them, list the traits on the package dependency:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.39.0",
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.0",
          traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision", "DolbyVisionStillReshaping"])
 ```
 
-In an Xcode project, a remote package's traits are set in the package dependency editor (Project › Package Dependencies), and Xcode stores them in the `.pbxproj`. XcodeGen cannot express them yet (2.45.4 drops a `traits:` key on a package without a word), so an XcodeGen project either patches the generated `.pbxproj` after each generate, or depends on a small local package that depends on AetherEngine with the traits set and re-exports it (`@_exported import AetherEngine`). [Probes/AllTraits](Probes/AllTraits/Package.swift) is that package with every trait on, and `Probes/DolbyVisionPulse/Device/PulseEngine` one with `DualLayerDolbyVision` alone. The engine itself builds with them through `swift build --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision,DolbyVisionStillReshaping` (or `--enable-all-traits`); CI builds and tests both the default and the all-traits configuration, and builds the all-traits engine for tvOS and iOS through `Probes/AllTraits`.
+In an Xcode project, a remote package's traits are set in the package dependency editor (Project › Package Dependencies), and Xcode stores them in the `.pbxproj`. XcodeGen cannot express them yet (2.45.4 drops a `traits:` key on a package without a word), so an XcodeGen project either patches the generated `.pbxproj` after each generate (a `traits = ( TrueHDObjectAudio, DTSXObjectAudio, );` list in the package's `XCRemoteSwiftPackageReference`, which Xcode 27 builds with), or depends on a small local package that depends on AetherEngine with the traits set and re-exports it (`@_exported import AetherEngine`). [Probes/AllTraits](Probes/AllTraits/Package.swift) is that package with every trait on, and `Probes/DolbyVisionPulse/Device/PulseEngine` one with `DualLayerDolbyVision` alone. The engine itself builds with them through `swift build --traits TrueHDObjectAudio,DTSXObjectAudio,DualLayerDolbyVision,DolbyVisionStillReshaping` (or `--enable-all-traits`); CI builds and tests both the default and the all-traits configuration, and builds the all-traits engine for tvOS and iOS through `Probes/AllTraits`.
 
 ## Support
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 313b75954..996db0c14 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.39.0"
+    public nonisolated static let version = "7.40.0"
 }

From eca55f0b19281b19b328c8ddca80f3943029e6a9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 15:45:30 +0200
Subject: [PATCH 130/132] fix(hls): the persistent ingest waits for room
 between segments, CI flakes fixed

The FIFO's backpressure applied only while a segment had bytes left over.
When a segment's last chunk was taken just under the ceiling, the next
request went out at once with the buffer already over it, which is what
made testFullBufferLetsTheCurrentSegmentFinishAndHoldsTheNextRequest
flaky on CI (large loopback chunks). The producer now waits for room
between segments either way; a new test builds the case deterministically
(fails 3/3 before, passes 3/3 after).

ItemSwapStillTests' fixture writer counted a starved test task as a
stalled AVAssetWriter: both tracks were ready, but the loop had not run
for the 20 s on a loaded runner. A stall now also needs 1000 idle polls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  5 ++++
 .../IO/HLSIngest/HLSVODIngestReader.swift     | 16 ++++++++++-
 .../Issue732PersistentHTTP1Tests.swift        | 27 +++++++++++++++++++
 .../ItemSwapStillTests.swift                  | 15 ++++++++---
 4 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f60dfff18..12d83a9d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -57,6 +57,11 @@ _Nothing yet._
 
 ### Fixed
 
+- **The persistent HTTP/1.1 ingest holds the next segment request whenever the buffer is full.**
+  Backpressure applied only while a segment still had bytes left over, so a segment whose last chunk
+  was taken just under the 16 MB ceiling sent the next request at once, past the ceiling. The
+  producer now waits for room between segments either way (#732; a test pins the case, and the
+  timing test that caught it on CI no longer flakes).
 - **A slow origin no longer fails large HEVC-in-TS segments on the persistent HTTP/1.1 ingest.**
   Segment bodies stream to the demuxer instead of downloading whole first, the 45 s ceiling covers
   only the wait for a response head, and a body ends on its size or on 30 s without a byte (typed
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index 989560402..160a2db39 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -542,7 +542,9 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
             throw HLSIngestError.playlistInvalid(reason: "segment body over its limit")
         }
         guard total > 0 else { throw HLSIngestError.playlistUnreachable(status: body.response.statusCode) }
-        return pending.isEmpty || append(pending, generation: generation)
+        // Between segments the ceiling holds even when the last chunk was taken just under it: the
+        // next request waits for the reader either way, not only when bytes are left over.
+        return pending.isEmpty ? waitForRoom(generation: generation) : append(pending, generation: generation)
     }
 
     private enum Offer { case taken, full, superseded }
@@ -574,6 +576,18 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         return body
     }
 
+    /// Parks until the FIFO is below its ceiling. False when the generation was superseded.
+    private func waitForRoom(generation: UInt64) -> Bool {
+        condition.lock()
+        defer { condition.unlock() }
+        while self.generation == generation,
+              !closed,
+              bufferedBytes >= Self.maximumBufferedBytes {
+            condition.wait()
+        }
+        return self.generation == generation && !closed
+    }
+
     private func append(_ data: Data, generation: UInt64) -> Bool {
         condition.lock()
         defer { condition.unlock() }
diff --git a/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift b/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
index 799ba0218..5f79be76c 100644
--- a/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
+++ b/Tests/AetherEngineTests/Issue732PersistentHTTP1Tests.swift
@@ -283,6 +283,33 @@ final class Issue732PersistentHTTP1Tests: XCTestCase {
         XCTAssertEqual(server.connectionCount, 1)
     }
 
+    func testASegmentTakenWholeJustUnderTheCeilingStillHoldsTheNextRequest() async throws {
+        let server = try XCTUnwrap(KeepAliveOrigin())
+        defer { server.stop() }
+        let segments = (0..<3).map { "seg\($0).ts" }
+        // Segment 0 stops 45 KB short of the 16 MB ceiling, so segment 1 (56 KB, one chunk) is taken
+        // whole while the FIFO is under it and lands it over: full, with nothing left in flight.
+        server.route = { path in
+            if path == "/vod.m3u8" { return .init(body: Self.mediaPlaylist(segments)) }
+            guard let index = segments.firstIndex(where: { "/" + $0 == path }) else { return .init(status: 404) }
+            return .init(body: Self.transportStream(marker: UInt8(index), packets: index == 0 ? 89_000 : 300))
+        }
+        let made = try await HLSVODIngestReader.makeIfHEVCMPEGTS(
+            playlistURL: server.url("/vod.m3u8"), httpHeaders: [:], persistentHTTP1: true)
+        let reader = try XCTUnwrap(made)
+        defer { reader.close() }
+
+        var head = [UInt8](repeating: 0, count: 188)
+        XCTAssertEqual(head.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: 188) }, 188)
+        try await waitUntil { server.completed.contains("/seg1.ts") }
+        try await Task.sleep(nanoseconds: 300_000_000)
+        XCTAssertFalse(server.requests.contains { $0.path == "/seg2.ts" }, "the next request waits for the reader")
+
+        let rest = Self.drain(reader)
+        XCTAssertEqual(188 + rest.count, (89_000 + 300 + 300) * 188)
+        XCTAssertEqual(server.connectionCount, 1)
+    }
+
     func testStalledBodyFailsWithWhatHadArrived() async throws {
         let server = try XCTUnwrap(KeepAliveOrigin())
         defer { server.stop() }
diff --git a/Tests/AetherEngineTests/ItemSwapStillTests.swift b/Tests/AetherEngineTests/ItemSwapStillTests.swift
index 4e5d1164d..86c5f4758 100644
--- a/Tests/AetherEngineTests/ItemSwapStillTests.swift
+++ b/Tests/AetherEngineTests/ItemSwapStillTests.swift
@@ -61,10 +61,13 @@ struct ItemSwapStillTests {
         var audioDone = false
         // A stall deadline, not a total one: under load the writer can be slow and still moving
         // (`video 4/120 ready=true, audio 24/40 ready=true` after a fixed 20 s on CI), and only a
-        // writer that takes nothing for 20 s is the deadlock described above.
+        // writer that takes nothing for 20 s is the deadlock described above. Both tracks reading
+        // ready at the end of such a run says the loop itself had not run: a starved task sleeps
+        // through the deadline, so a stall also needs the polls to show it.
         var lastProgress = ContinuousClock.now
+        var idlePolls = 0
         while !(videoDone && audioDone), writer.status == .writing,
-              ContinuousClock.now - lastProgress < .seconds(20) {
+              ContinuousClock.now - lastProgress < .seconds(20) || idlePolls < 1_000 {
             var fed = false
             if !videoDone, video.isReadyForMoreMediaData {
                 // Our own buffer, not one from the adaptor's pool: that pool belongs to the
@@ -112,7 +115,13 @@ struct ItemSwapStillTests {
                     audioDone = true
                 }
             }
-            if fed { lastProgress = .now } else { try await Task.sleep(for: .milliseconds(5)) }
+            if fed {
+                lastProgress = .now
+                idlePolls = 0
+            } else {
+                idlePolls += 1
+                try await Task.sleep(for: .milliseconds(5))
+            }
         }
         guard videoDone, audioDone else {
             let state = "video \(frame)/120 ready=\(video.isReadyForMoreMediaData), "

From 5e3d85fce2ec6a28f8d0469f45f756e550e470f3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 18:38:07 +0200
Subject: [PATCH 131/132] fix(audio): read TrueHD Atmos from the major sync
 when the probe never reached the track

A TrueHD track that starts after the probe window (John Wick: Chapter 2, TrueHD from 22 s,
45.8 MB in) leaves find_stream_info without a decoded frame, so the stream keeps
AV_PROFILE_UNKNOWN and objectAudioRendering played it through the channel bridge. When
object rendering is wanted and the profile is unknown, the engine now peeks the track's
packets where the first producer starts and reads the major sync the way mlpdec does (four
substreams, top bit of substream_info). Measured with the tvOS probe budget (16 MiB / 10 s):
from the start 2599 packets, 44.7 MB, 679 ms; on a resume 10 packets, 30 ms; APAC 7.1.4 in
both, where the same build without the check served E-AC-3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/Spatial/TrueHDMajorSync.swift       | 32 +++++++++
 .../Video/HLSVideoEngine+SpatialAudio.swift   | 62 +++++++++++++++++
 .../AetherEngine/Video/HLSVideoEngine.swift   |  2 +
 .../TrueHDMajorSyncTests.swift                | 66 +++++++++++++++++++
 4 files changed, 162 insertions(+)
 create mode 100644 Sources/AetherEngine/Audio/Spatial/TrueHDMajorSync.swift
 create mode 100644 Tests/AetherEngineTests/TrueHDMajorSyncTests.swift

diff --git a/Sources/AetherEngine/Audio/Spatial/TrueHDMajorSync.swift b/Sources/AetherEngine/Audio/Spatial/TrueHDMajorSync.swift
new file mode 100644
index 000000000..777f71db6
--- /dev/null
+++ b/Sources/AetherEngine/Audio/Spatial/TrueHDMajorSync.swift
@@ -0,0 +1,32 @@
+import Foundation
+
+/// Reads whether a TrueHD stream carries Atmos from the major sync in its packets, the same test
+/// FFmpeg's mlpdec applies when it sets `AV_PROFILE_TRUEHD_ATMOS`: four substreams, and the top bit
+/// of `substream_info` set (the 16-channel presentation). FFmpeg only learns it by decoding a frame
+/// during `find_stream_info`, so a track that starts after the probe window keeps an unknown profile.
+enum TrueHDMajorSync {
+    /// `format_sync` of a TrueHD (not MLP) major sync.
+    static let formatSync: [UInt8] = [0xF8, 0x72, 0x6F, 0xBA]
+    /// `signature` following `format_info`.
+    static let signature: [UInt8] = [0xB7, 0x52]
+
+    /// Walks the access units in one demuxed packet. True or false from the first major sync found,
+    /// nil when the packet holds none (a major sync recurs at least every 128 access units).
+    static func isAtmos(_ packet: UnsafeRawBufferPointer) -> Bool? {
+        var offset = 0
+        while offset + 4 <= packet.count {
+            // Access unit header: 4 bits check nibble, 12 bits length in 16-bit words, 16 bits timing.
+            let length = (Int(packet[offset] & 0x0F) << 8 | Int(packet[offset + 1])) * 2
+            guard length >= 4 else { return nil }
+            if offset + 22 <= packet.count,
+               zip(formatSync.indices, formatSync).allSatisfy({ packet[offset + 4 + $0] == $1 }),
+               packet[offset + 12] == signature[0], packet[offset + 13] == signature[1] {
+                let substreams = packet[offset + 20] >> 4
+                let substreamInfo = packet[offset + 21]
+                return substreams == 4 && substreamInfo >> 7 == 1
+            }
+            offset += length
+        }
+        return nil
+    }
+}
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
index 9d5a5a08a..f2cc7c5b4 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SpatialAudio.swift
@@ -126,6 +126,68 @@ extension HLSVideoEngine {
     }
     #endif
 
+    /// Packets `resolveUnlabelledTrueHDAtmos` may look at. Sized for a track that starts well after the
+    /// probe window: 22 s of a 4K remux interleaved with a second audio track is about 3,000 packets.
+    static let trueHDVerdictPacketBudget = 8192
+    /// Bytes it may hold. Peeked packets stay resident until the producer reads them, so this is the
+    /// worst-case extra memory of a session start; it is paid only by a TrueHD track whose profile the
+    /// probe could not read, and the measured case (TrueHD from 22 s, 45.8 MB in) fits.
+    static let trueHDVerdictByteBudget = 64 << 20
+
+    /// A TrueHD track the probe never decoded a frame of keeps `AV_PROFILE_UNKNOWN`, which reads as
+    /// "not Atmos" everywhere below. When object rendering is wanted, look at the track's own major
+    /// sync where the first producer starts, and mark the stream Atmos if it is. Peeks without
+    /// consuming (the producer reads the same packets) and leaves the demuxer at the producer start.
+    func resolveUnlabelledTrueHDAtmos(
+        audioStream: UnsafeMutablePointer<AVStream>,
+        audioDemuxer: Demuxer,
+        streamIndex: Int32
+    ) {
+        let par = audioStream.pointee.codecpar.pointee
+        guard par.codec_id == AV_CODEC_ID_TRUEHD, par.profile == AV_PROFILE_UNKNOWN,
+              objectAudioRendering.layout != nil, ObjectAudioSource.trueHDAtmos.isBuiltIn,
+              !isLiveSession
+        else { return }
+        if audioDemuxer === demuxer {
+            seekToInitialProducerStart(audioDemuxer)
+            demuxerAtInitialProducerStart = true
+        }
+        let started = DispatchTime.now()
+        var verdict: Bool?
+        var heldBytes = 0
+        var packets = 0
+        try? audioDemuxer.peekPackets(maxPackets: Self.trueHDVerdictPacketBudget) { packet in
+            packets += 1
+            heldBytes += Int(max(packet.pointee.size, 0))
+            if heldBytes > Self.trueHDVerdictByteBudget { return true }
+            guard packet.pointee.stream_index == streamIndex,
+                  let data = packet.pointee.data, packet.pointee.size > 0 else { return false }
+            verdict = TrueHDMajorSync.isAtmos(UnsafeRawBufferPointer(start: data, count: Int(packet.pointee.size)))
+            return verdict != nil
+        }
+        let ms = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1e6
+        let span = "\(packets) packets, \(heldBytes >> 10) KiB, \(String(format: "%.0f", ms)) ms"
+        switch verdict {
+        case true?:
+            audioStream.pointee.codecpar.pointee.profile = AV_PROFILE_TRUEHD_ATMOS
+            EngineLog.emit(
+                "[HLSVideoEngine] TrueHD profile was not probed; major sync says Atmos (\(span))",
+                category: .session
+            )
+        case false?:
+            EngineLog.emit(
+                "[HLSVideoEngine] TrueHD profile was not probed; major sync says no Atmos (\(span))",
+                category: .session
+            )
+        case nil:
+            EngineLog.emit(
+                "[HLSVideoEngine] TrueHD profile was not probed and no major sync within the budget (\(span)); "
+                + "treating it as without Atmos",
+                category: .session
+            )
+        }
+    }
+
     /// Build the producer on a `SpatialAudioBridge` when the host asked for object rendering and the
     /// source qualifies. Nil means "not this route": ineligible, unsupported OS, not DTS:X, or a
     /// bridge/header failure, each logged, and the caller carries on with the ordinary bridge
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 4314ff275..09ba6a639 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1905,6 +1905,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
                     category: .session
                 )
             }
+            resolveUnlabelledTrueHDAtmos(
+                audioStream: audioStream, audioDemuxer: audioDem, streamIndex: audioStreamIndex)
             let compat = AudioCodecCompat.from(codecID)
             // HE-AAC needs bridging only when there is no ASC (live ADTS/MPEG-TS): synthesized ASC
             // would declare LC at the SBR output rate, decoded as garbage by AudioToolbox (-11821).
diff --git a/Tests/AetherEngineTests/TrueHDMajorSyncTests.swift b/Tests/AetherEngineTests/TrueHDMajorSyncTests.swift
new file mode 100644
index 000000000..4821f0d0a
--- /dev/null
+++ b/Tests/AetherEngineTests/TrueHDMajorSyncTests.swift
@@ -0,0 +1,66 @@
+import Testing
+@testable import AetherEngine
+
+// A TrueHD track that starts after the probe window keeps AV_PROFILE_UNKNOWN, so the engine reads
+// Atmos from the track's own major sync instead (John Wick: Chapter 2, TrueHD from 22 s).
+@Suite("TrueHDMajorSync Atmos detection")
+struct TrueHDMajorSyncTests {
+
+    /// First 32 bytes of an access unit carrying a major sync, from a TrueHD Atmos remux:
+    /// four substreams, substream_info 0xFC.
+    static let atmosHead: [UInt8] = bytes("630fe8daf8726fba0017804fb752100000008a2a43fc00364aefe307e3011fc6")
+
+    /// The same from FFmpeg's own TrueHD encoder (5.1, no Atmos): two substreams, substream_info 0x3C.
+    static let plainHead: [UInt8] = bytes("d063ffd8f8726fba0007800fb752000000008c7f203c0000000000000000e4d1")
+
+    /// An access unit without a major sync, eight bytes long (length field 4 words).
+    static let syncless: [UInt8] = [0x20, 0x04, 0xE9, 0x28, 0x70, 0x23, 0x60, 0x7F]
+
+    static func bytes(_ hex: String) -> [UInt8] {
+        var out: [UInt8] = []
+        var index = hex.startIndex
+        while index < hex.endIndex {
+            let next = hex.index(index, offsetBy: 2)
+            out.append(UInt8(hex[index..<next], radix: 16)!)
+            index = next
+        }
+        return out
+    }
+
+    static func verdict(_ packet: [UInt8]) -> Bool? {
+        packet.withUnsafeBytes { TrueHDMajorSync.isAtmos($0) }
+    }
+
+    @Test func atmosMajorSyncReadsAtmos() {
+        #expect(Self.verdict(Self.atmosHead) == true)
+    }
+
+    @Test func plainMajorSyncReadsNoAtmos() {
+        #expect(Self.verdict(Self.plainHead) == false)
+    }
+
+    @Test func majorSyncInALaterAccessUnitOfThePacketIsFound() {
+        #expect(Self.verdict(Self.syncless + Self.syncless + Self.atmosHead) == true)
+    }
+
+    @Test func packetWithoutMajorSyncHasNoVerdict() {
+        #expect(Self.verdict(Self.syncless + Self.syncless) == nil)
+        #expect(Self.verdict([]) == nil)
+    }
+
+    @Test func fourSubstreamsWithoutThePresentationBitIsNotAtmos() {
+        var head = Self.atmosHead
+        head[21] &= 0x7F
+        #expect(Self.verdict(head) == false)
+    }
+
+    @Test func brokenSignatureIsNotAMajorSync() {
+        var head = Self.atmosHead
+        head[13] ^= 0xFF
+        #expect(Self.verdict(head) == nil)
+    }
+
+    @Test func zeroLengthAccessUnitStopsTheWalk() {
+        #expect(Self.verdict([0x00, 0x00, 0x00, 0x00] + Self.atmosHead) == nil)
+    }
+}

From 4f70cfaa17f298cfffc8d5731664b9720c4b6f40 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 18 Oct 2026 18:40:44 +0200
Subject: [PATCH 132/132] chore(release): prep 7.40.1 - TrueHD Atmos read from
 the major sync when the probe misses the track

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

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 12d83a9d9..d8c710533 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,18 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.40.1] - 2026-10-18
+
+### Fixed
+
+- **TrueHD Atmos that starts after the probe window is rendered again.** A track whose first packet
+  lies beyond `find_stream_info`'s budget (John Wick: Chapter 2 carries TrueHD from 22 s, 45.8 MB
+  into the file) kept an unknown profile, so `objectAudioRendering` played it through the channel
+  bridge. With rendering requested and the profile unknown, the engine now reads the track's major
+  sync where the first producer starts, the same test mlpdec applies (four substreams, top bit of
+  `substream_info`), and renders it when it is Atmos. Costs 679 ms and 44.7 MB of held packets from
+  the start of that file at the tvOS probe budget, 30 ms on a resume; nothing for any other track.
+
 ## [7.40.0] - 2026-10-18
 
 ### Changed
diff --git a/Examples/README.md b/Examples/README.md
index 36a1954d3..091ccb5be 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.40.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.40.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 6385f6447..52126a816 100644
--- a/README.md
+++ b/README.md
@@ -387,7 +387,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.40.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -634,10 +634,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.40.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.40.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.40.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
@@ -672,7 +672,7 @@ These components may be subject to third-party patent licensing. Integrators who
 To enable them, list the traits on the package dependency:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.0",
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.40.1",
          traits: ["TrueHDObjectAudio", "DTSXObjectAudio", "DualLayerDolbyVision", "DolbyVisionStillReshaping"])
 ```
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 996db0c14..6c193d416 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.40.0"
+    public nonisolated static let version = "7.40.1"
 }