Pre-push review #2: T-2138 remote stream timeout

diff --git a/prism/Services/URLDocumentLoader.swift b/prism/Services/URLDocumentLoader.swiftindex 8f7fa3e1..4974bd1d 100644--- a/prism/Services/URLDocumentLoader.swift+++ b/prism/Services/URLDocumentLoader.swift@@ -113,11 +113,16 @@ enum URLDocumentLoader {     ///   - url: The user-provided URL to load.     ///   - sessionConfiguration: Optional URLSession configuration for testing.     ///     Defaults to `.ephemeral` for production use.+    ///   - deadline: End-to-end seconds allowed for the whole download,+    ///     including redirects and streaming the body. Defaults to 30 (Req+    ///     3.1). Overridable so tests can exercise the deadline without+    ///     waiting the full production interval.     /// - Returns: A `LoadResult` with the content and URL metadata.     /// - Throws: `LoadError` for validation failures or network errors.     static func load(         from url: URL,-        sessionConfiguration: URLSessionConfiguration? = nil+        sessionConfiguration: URLSessionConfiguration? = nil,+        deadline: TimeInterval = 30     ) async throws -> LoadResult {         // Validate scheme before any network activity (Req 2.1, 7.5)         guard let scheme = url.scheme?.lowercased(),@@ -139,6 +144,13 @@ enum URLDocumentLoader {         let config = sessionConfiguration ?? .ephemeral         // Set timeout on both config (applies to redirect requests) and URLRequest (initial request).         config.timeoutIntervalForRequest = 30 // Req 3.1+        // `timeoutIntervalForRequest`/`URLRequest.timeoutInterval` are inactivity+        // timeouts only: a server trickling one byte per interval never trips+        // them. `timeoutIntervalForResource` bounds the whole task (redirects ++        // body) regardless of activity, matching the pattern already used by+        // ImageLoader/SVGSourceLoader. The explicit `deadline` race below is the+        // primary, testable enforcement; this is defense-in-depth.+        config.timeoutIntervalForResource = 30 // Req 3.1         let redirectHandler = RedirectHandler()         let session = URLSession(configuration: config, delegate: redirectHandler, delegateQueue: nil)         defer { session.invalidateAndCancel() }@@ -146,11 +158,63 @@ enum URLDocumentLoader {         var request = URLRequest(url: transformed.fetchURL)         request.timeoutInterval = 30 -        // Download with streaming to enforce size limit (Decision 8)+        // Download with streaming to enforce size limit (Decision 8), bounded+        // end-to-end by `deadline` so a slow-drip body (one byte per interval,+        // never triggering the inactivity timeouts above) cannot hold the+        // load open indefinitely (Req 3.1).+        //+        // The accumulation loop is written HERE, inside the closure, rather+        // than in the `streamDownload` helper it used to live in. That is+        // measured, not stylistic: `URLSession.AsyncBytes` yields one byte at+        // a time, so a 10 MB body is ten million suspension points, and in+        // this target's build configuration the per-suspension cost depends+        // on where the loop is written. Iterating 10,485,761 bytes served by+        // `MockURLProtocol` takes 0.87-1.34 s with the loop inline (measured+        // three times, three different closure shapes) and 86-273 s with the+        // identical body in a separate `async` helper called from this+        // closure (measured seven times, across `private`/`internal`,+        // with/without `@concurrent` on the helper and on `load`, and with+        // `Data`, `[UInt8]` and `Int`-counter accumulators). No overlap+        // between the two groups.+        //+        // The consequence is a correctness one, not a performance one: at+        // ~13 microseconds per byte the 10 MB cap below cannot be reached+        // inside the 30 s deadline at all, so an oversized body failed over+        // to `.networkError(URLError.timedOut)` and Req 3.3's limit was+        // unenforceable. `contentTooLargeViaStreaming` asserts the specific+        // `.contentTooLarge` case and is the regression detector for this.+        //+        // The underlying mechanism is NOT established — the split is+        // reproducible but the rule ("loop inline") is empirical, and the+        // slow branch's magnitude varies with host load. T-2260 tracks+        // finding the real cause and replacing this with chunked+        // accumulation, which would make the whole question moot by cutting+        // ten million suspension points down to about a hundred and sixty.         let data: Data         let response: URLResponse         do {-            (data, response) = try await streamDownload(request: request, session: session)+            (data, response) = try await withDeadline(seconds: deadline) {+                let (bytes, streamResponse) = try await session.bytes(for: request)++                // Early rejection via Content-Length header when available (Req 7.3)+                let declaredLength = (streamResponse as? HTTPURLResponse)+                    .flatMap { $0.value(forHTTPHeaderField: "Content-Length") }+                    .flatMap(Int.init)+                if let declaredLength, declaredLength > maxContentSize {+                    throw LoadError.contentTooLarge+                }++                // Stream and accumulate with size enforcement+                var body = Data()+                body.reserveCapacity(min(declaredLength ?? 65_536, maxContentSize))+                for try await byte in bytes {+                    body.append(byte)+                    if body.count > maxContentSize {+                        throw LoadError.contentTooLarge+                    }+                }+                return (body, streamResponse)+            }         } catch let error as LoadError {             throw error         } catch {@@ -190,36 +254,287 @@ enum URLDocumentLoader {         )     } -    /// Streams a download, accumulating data up to the size limit.+    /// Races `operation` against a `seconds`-second wall-clock deadline.+    ///+    /// Unlike `timeoutIntervalForRequest`/`timeoutIntervalForResource`, which+    /// depend on the URLSession/OS networking stack to fire, this deadline is+    /// enforced entirely in-process. What it actually guarantees is narrower+    /// than "the operation stops within `seconds`": it guarantees that+    /// **this function returns (or throws) within `seconds`**, regardless of+    /// what `operation` is doing at that moment. `operation` runs as an+    /// unstructured `Task`, deliberately not as a `withThrowingTaskGroup`+    /// child — a task group implicitly awaits every child before the group+    /// scope returns, even after `cancelAll()`, so a group-based race still+    /// blocks the caller until the losing child actually unwinds (T-2138+    /// review). If `operation` is slow to notice cancellation — e.g. a+    /// `URLSession.AsyncBytes` iteration reading a connection stalled at the+    /// socket level, which is the exact failure this deadline exists to+    /// bound — a task group degrades back to whatever `operation` eventually+    /// does, silently losing the "authoritative" guarantee. Racing an+    /// unstructured task via a continuation avoids that: on timeout we+    /// resume the continuation immediately, request cancellation of the+    /// losing task, and then abandon it — this function does not wait for it+    /// to finish. The loser cannot affect the result: `DeadlineGate` only+    /// honours the first resume, so anything the abandoned task later+    /// produces (success, failure, or its own cancellation) is discarded.+    /// The loser also cannot leak the connection on its own: `load`'s+    /// `defer { session.invalidateAndCancel() }` runs as soon as this+    /// function returns/throws — not once the abandoned task finishes — so+    /// the underlying `URLSessionTask` is torn down at the OS level+    /// immediately, independent of whether `AsyncBytes` ever observed+    /// cooperative cancellation.+    ///+    /// A THIRD source can end this race: the task calling `withDeadline`+    /// being cancelled — e.g. `RemoteContentCoordinator.cancelDownload()` /+    /// `RemoteRefreshFlow.cancel()` flipping their UI state immediately.+    /// Before T-2138 review round 2, that cancellation only ever reached the+    /// unstructured `workTask` through `withCheckedThrowingContinuation`'s+    /// own (nonexistent) propagation — a bare continuation does not observe+    /// the calling task's cancellation at all, so the abandoned operation+    /// kept running for up to the full `seconds` deadline even though the+    /// caller had already moved on. Wrapping the continuation in+    /// `withTaskCancellationHandler` (the project's own pattern —+    /// `ImageLoader.AsyncSemaphore.acquire`, `ImageMemoryGuard.acquire`,+    /// `MermaidRenderer.renderInternal`) fixes that: `onCancel` cancels both+    /// `workTask` and `timeoutTask` and resumes the gate with+    /// `CancellationError`, so this function returns promptly on caller+    /// cancellation instead of waiting out the remaining deadline.+    ///+    /// `operation` is `@concurrent` for a MEASURED reason: without it, an+    /// operation that suspends often is ~150x slower. This target builds with+    /// `SWIFT_APPROACHABLE_CONCURRENCY = YES`, which enables+    /// `NonisolatedNonsendingByDefault`, under which an `async` function —+    /// including an `async` function-type PARAMETER like this one — is+    /// `nonisolated(nonsending)`: it runs on its CALLER's executor rather+    /// than off-actor. The unstructured `Task` does NOT change that on its+    /// own; the closure carries the caller's isolation into the task, so+    /// every suspension inside it hops back to that executor. `load`'s+    /// per-byte `AsyncBytes` loop is ten million suspensions over a 10 MB+    /// body, and both production call sites (`RemoteContentCoordinator`,+    /// `RemoteRefreshFlow`) are `@MainActor`, so without `@concurrent` that+    /// executor is the main one.+    ///+    /// Measured on this project's own build, iterating 10,485,761 bytes+    /// served by `MockURLProtocol`: 0.88 s inline, and 0.88 s inside an+    /// unstructured `Task`, a detached task, or a task group — but 133 s+    /// through this function without `@concurrent`, and 0.88 s with it.+    /// Byte-identical code compiled into the TEST target (which does not+    /// enable the feature) ran at 0.88 s in every shape, which is what+    /// isolates the cause to the isolation-inheriting parameter rather than+    /// to `AsyncBytes`, to `Data.append`, or to the shape of the race.+    ///+    /// The attribute is necessary but not sufficient: see the note at+    /// `load`'s `withDeadline` call for why the accumulation loop is written+    /// inside the closure. The consequence of getting either wrong is+    /// correctness, not speed — the 10 MB cap becomes unreachable within the+    /// deadline and an oversized body surfaces as a timeout instead+    /// (T-2260).+    ///+    /// `RenderingUtilities.withTimeout` is the same idea in the+    /// `withThrowingTaskGroup` shape this comment argues against, and it is+    /// deliberately NOT changed here. Its exposure is tracked separately as+    /// T-2134 (SVG snapshot timeout can hang past its deadline), and its+    /// operation is a `@MainActor` `WKWebView` call holding a `WebViewPool`+    /// slot, so abandoning the loser there leaks a pool slot rather than+    /// merely a task — a different fix from this one, not a mechanical+    /// port of it.+    static func withDeadline<T: Sendable>(+        seconds: TimeInterval,+        operation: @escaping @Sendable @concurrent () async throws -> T+    ) async throws -> T {+        let gate = DeadlineGate<T>()+        return try await withTaskCancellationHandler {+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<T, Error>) in+                let workTask = Task {+                    do {+                        let value = try await operation()+                        gate.resume(returning: value)+                    } catch {+                        gate.resume(throwing: error)+                    }+                }++                let timeoutTask = Task {+                    try? await Task.sleep(nanoseconds: UInt64(max(0, seconds) * 1_000_000_000))+                    guard !Task.isCancelled else { return }+                    // Resume FIRST, cancel second. `Task.cancel()` returns+                    // immediately without waiting, so a `workTask` unwinding+                    // concurrently on another core could otherwise reach+                    // `gate.resume(throwing: URLError(.cancelled))` before+                    // this line and win the gate, flipping the surfaced error+                    // away from `.timedOut`. The cancel is cleanup, not the+                    // result, so it has no reason to go first.+                    gate.resume(throwing: URLError(.timedOut))+                    workTask.cancel()+                }++                // Registers both tasks with the gate so `onCancel` (below)+                // can reach them, and hands over the continuation. This does+                // NOT assume it wins a race against the two tasks above: a+                // freshly created `Task` body is scheduled rather than run+                // inline, but "not run inline" constrains only THIS thread —+                // another core can pick the body up and reach `gate.resume`+                // while this thread is still between statements. The gate+                // therefore latches a result that arrives before `start`+                // and `start` delivers it, exactly as it does for an early+                // `cancelFromCaller`.+                gate.start(continuation: continuation, work: workTask, timeout: timeoutTask)++                // Cleanup only: once the work task finishes on its own (before+                // the deadline), stop the now-pointless sleeping timeout task.+                // This does not gate `withDeadline`'s own return — the+                // continuation above already resumed via `gate`.+                Task {+                    _ = await workTask.result+                    timeoutTask.cancel()+                }+            }+        } onCancel: {+            gate.cancelFromCaller()+        }+    }++    /// Resumes a `CheckedContinuation` at most once, across all three+    /// possible resumers: `operation` finishing, `timeoutTask`'s deadline+    /// firing, or the calling task being cancelled.+    ///+    /// `withDeadline` races two unstructured tasks against the same+    /// continuation; whichever calls `resume` first wins, and the loser's+    /// call becomes a silent no-op instead of the double-resume trap+    /// (`CheckedContinuation` traps on a second resume). Caller cancellation+    /// is a third resumer with the same requirement, delivered via+    /// `withTaskCancellationHandler`'s `onCancel` — a plain, non-`async`+    /// closure that Swift can invoke immediately, before `withDeadline`'s+    /// `withCheckedThrowingContinuation` closure has even run, if the+    /// calling task was already cancelled at the point+    /// `withTaskCancellationHandler` was entered. That is why this is a+    /// two-phase, lock-protected class rather than an actor: `init()`+    /// creates it with nothing to cancel yet, `start` supplies the+    /// continuation and tasks once they exist, and `cancelFromCaller` can+    /// land before, during, or after `start` — a plain `NSLock` makes every+    /// method here synchronous and callable directly from `onCancel` and+    /// from the continuation closure, neither of which is `async`. Routing+    /// through an actor instead would need a `Task { await ... }` hop from+    /// each of those call sites, reopening an ordering gap between "the+    /// calling task was cancelled" and "the gate learned about it."     ///-    /// Uses `URLSession.bytes(from:)` to avoid loading oversized responses-    /// into memory. Checks `Content-Length` header for early rejection.-    private static func streamDownload(-        request: URLRequest,-        session: URLSession-    ) async throws -> (Data, URLResponse) {-        let (bytes, response) = try await session.bytes(for: request)--        // Early rejection via Content-Length header when available (Req 7.3)-        let declaredLength = (response as? HTTPURLResponse)-            .flatMap { $0.value(forHTTPHeaderField: "Content-Length") }-            .flatMap(Int.init)-        if let declaredLength, declaredLength > maxContentSize {-            throw LoadError.contentTooLarge-        }--        // Stream and accumulate with size enforcement-        var data = Data()-        data.reserveCapacity(min(declaredLength ?? 65_536, maxContentSize))--        for try await byte in bytes {-            data.append(byte)-            if data.count > maxContentSize {-                throw LoadError.contentTooLarge+    /// Every one of the three resumers can arrive before `start` has supplied+    /// the continuation, and all three are latched the same way. That+    /// symmetry is the invariant, not a refinement: latching only+    /// `cancelFromCaller` (as this class originally did) silently DROPPED an+    /// early `resume`, and the resulting hang is permanent — `start` then+    /// records a continuation nobody will ever resume again, the cleanup task+    /// sees `workTask` already finished and cancels `timeoutTask`, and+    /// `timeoutTask`'s `guard !Task.isCancelled` returns without resuming.+    /// The window is widest exactly where `operation` fails fast (an+    /// immediate throw from `session.bytes(for:)`, a `Content-Length`+    /// rejection, a mock-backed instant response), and its symptom — a load+    /// that never returns — is indistinguishable from a slow network+    /// (T-2138 review round 5).+    ///+    /// Visibility is `internal` rather than `private` so the ordering that+    /// caused that bug can be tested directly: reaching it through+    /// `withDeadline` means racing the scheduler, which is exactly what a+    /// regression test must not do.+    final class DeadlineGate<T: Sendable>: @unchecked Sendable {+        private let lock = NSLock()+        private var continuation: CheckedContinuation<T, Error>?+        private var workTask: Task<Void, Never>?+        private var timeoutTask: Task<Void, Never>?+        private var callerCancelledEarly = false+        /// The winning result, when it was produced before `start` handed+        /// over the continuation. Delivered by `start`.+        private var pendingResult: Result<T, Error>?+        /// Set by the first resumer, whether it delivered or latched. Every+        /// later resumer is a no-op, which is what keeps the single-resume+        /// guarantee across `operation`, the deadline, and caller+        /// cancellation.+        private var finished = false++        /// Wires up the continuation and the two racing tasks together.+        ///+        /// If a result already arrived — either a racing task's `resume` or+        /// an early `cancelFromCaller()`, i.e. the calling task was cancelled+        /// before `operation`/`timeoutTask` existed — it is delivered here+        /// instead of being dropped, and both tasks are cancelled rather than+        /// left running unobserved. Cancelling a task that has already+        /// produced its result is a no-op, so the two cases need no+        /// distinction.+        func start(+            continuation: CheckedContinuation<T, Error>,+            work: Task<Void, Never>,+            timeout: Task<Void, Never>+        ) {+            lock.lock()+            workTask = work+            timeoutTask = timeout+            let latched = pendingResult+            pendingResult = nil+            if latched == nil && !finished {+                self.continuation = continuation             }+            let cancelledEarly = callerCancelledEarly+            lock.unlock()++            if let latched {+                work.cancel()+                timeout.cancel()+                continuation.resume(with: latched)+                return+            }+            if cancelledEarly {+                work.cancel()+                timeout.cancel()+                deliver(.failure(CancellationError()))+            }+        }++        func resume(returning value: T) {+            deliver(.success(value))         } -        return (data, response)+        func resume(throwing error: Error) {+            deliver(.failure(error))+        }++        /// Honours the first result only. Delivers it if the continuation is+        /// already here, latches it for `start` if it is not.+        private func deliver(_ result: Result<T, Error>) {+            lock.lock()+            guard !finished else {+                lock.unlock()+                return+            }+            finished = true+            let pending = continuation+            continuation = nil+            if pending == nil {+                pendingResult = result+            }+            lock.unlock()+            // Resumed outside the lock: the continuation's resumption can run+            // arbitrary caller code, and the lock is never held across a+            // call-out.+            pending?.resume(with: result)+        }++        /// Invoked from `onCancel` when the calling task — not `operation`+        /// — is cancelled. Cancels the abandoned operation and the+        /// now-pointless timeout, then resumes with `CancellationError` so+        /// `withDeadline` returns immediately instead of waiting out the+        /// remaining deadline. If `start` hasn't run yet, `deliver` latches+        /// the result and `callerCancelledEarly` records that the tasks still+        /// need cancelling once they exist.+        func cancelFromCaller() {+            lock.lock()+            callerCancelledEarly = true+            let work = workTask+            let timeout = timeoutTask+            lock.unlock()+            work?.cancel()+            timeout?.cancel()+            deliver(.failure(CancellationError()))+        }     }      /// Validates HTTP redirects only follow http/https schemes and have no

diff --git a/prismTests/URLDocumentLoaderTests.swift b/prismTests/URLDocumentLoaderTests.swiftindex 85893f32..8a52cd8b 100644--- a/prismTests/URLDocumentLoaderTests.swift+++ b/prismTests/URLDocumentLoaderTests.swift@@ -15,10 +15,102 @@ enum MockURLProtocolResult {     case redirect(HTTPURLResponse, URLRequest)     /// Streams the body lazily: the closure is invoked repeatedly and returns     /// the next chunk until it returns `nil`. Lets tests exceed a cap without-    /// allocating the full payload up front.-    case streamed(HTTPURLResponse, () -> Data?)+    /// allocating the full payload up front. `onCancelled`, when provided, is+    /// invoked once `stopLoading()` is observed (i.e. the URL Loading System+    /// cancelled the underlying task) — tests that need to prove a load was+    /// actually torn down, rather than merely finishing on its own, use it.+    case streamed(HTTPURLResponse, () -> Data?, onCancelled: (() -> Void)? = nil) } +/// Thread-safe one-shot flag with a bounded async poll.+///+/// Used to prove a background callback (e.g. `MockURLProtocol`'s+/// `onCancelled`, invoked from `startLoading()`'s own thread) actually fired,+/// rather than inferring it indirectly from wall-clock timing.+final class CancellationRecorder: @unchecked Sendable {+    private let lock = NSLock()+    private var marked = false+    private var observedValue: Int?++    /// - Parameter value: optional payload captured at the moment the+    ///   callback fired (e.g. how many chunks the mock had emitted), read+    ///   back with `markedValue()`. The lock that publishes `marked` also+    ///   publishes this, so a reader that has seen `isMarked() == true`+    ///   sees the value that was stored with it.+    func markCancelled(value: Int? = nil) {+        lock.lock()+        marked = true+        observedValue = value+        lock.unlock()+    }++    func markedValue() -> Int? {+        lock.lock()+        defer { lock.unlock() }+        return observedValue+    }++    func isMarked() -> Bool {+        lock.lock()+        defer { lock.unlock() }+        return marked+    }++    /// Polls up to `attempts` times, `pollInterval` seconds apart, returning+    /// `true` as soon as `markCancelled()` has been observed.+    func waitUntilMarked(pollInterval: TimeInterval, attempts: Int) async -> Bool {+        for _ in 0..<attempts {+            if isMarked() { return true }+            try? await Task.sleep(nanoseconds: UInt64(pollInterval * 1_000_000_000))+        }+        return isMarked()+    }+}++/// Holds a continuation an "uncooperative operation" test suspends on, so the+/// test can resume it exactly once during teardown.+///+/// Without this, such a test leaves a `CheckedContinuation` unresumed and the+/// runtime prints `SWIFT TASK CONTINUATION MISUSE: ... leaked its+/// continuation without resuming it` into every run's log — a line that looks+/// like a production defect to anyone scanning the output.+final class ParkedContinuation: @unchecked Sendable {+    private let lock = NSLock()+    private var continuation: CheckedContinuation<Void, Never>?+    private var released = false++    /// Parks `continuation`. If `release()` already ran, resumes immediately+    /// so a late park cannot leak either.+    func park(_ continuation: CheckedContinuation<Void, Never>) {+        lock.lock()+        if released {+            lock.unlock()+            continuation.resume()+            return+        }+        self.continuation = continuation+        lock.unlock()+    }++    /// Resumes the parked continuation, if any. Idempotent.+    func release() {+        lock.lock()+        released = true+        let pending = continuation+        continuation = nil+        lock.unlock()+        pending?.resume()+    }+}++/// Resumes a `DeadlineGate` probe that would otherwise never be resumed, so a+/// regression fails in seconds instead of hanging the shared test host.+private struct GateRescueError: Error {}++/// Thrown by an operation that fails the instant it starts — the ordering+/// where a dropped early `resume` used to hang forever.+private struct ImmediateOperationFailure: Error {}+ /// A per-suite handle onto `MockURLProtocol`'s handler registry. /// /// Assign `scope.handler` exactly as a test would once have assigned@@ -83,6 +175,44 @@ final class MockURLProtocol: URLProtocol {     override static func canInit(with request: URLRequest) -> Bool { true }     override static func canonicalRequest(for request: URLRequest) -> URLRequest { request } +    /// Serial queue that runs a `.streamed` response's drip loop.+    ///+    /// The drip MUST NOT run inline in `startLoading()`. The URL Loading+    /// System delivers `startLoading()` and `stopLoading()` to a protocol+    /// instance on the SAME thread, so a drip loop that sleeps between+    /// chunks inside `startLoading()` blocks the very thread `stopLoading()`+    /// has to arrive on: `wasCancelled` cannot flip until the loop has+    /// already run to completion, and `onCancelled` therefore never fires no+    /// matter how promptly the production code tears the session down. That+    /// is exactly what T-2138 round 4 measured — `invalidateAndCancel()` ran+    /// 2 ms after the injected deadline, while `stopLoading()` was not+    /// delivered until 3.44 s later, one millisecond AFTER the loop's exit+    /// check had already read `false`. Dripping from this queue leaves the+    /// protocol thread free, which is also the more faithful model of a real+    /// trickling server (a server does not hold the client's loading thread).+    private let dripQueue = DispatchQueue(label: "MockURLProtocol.drip")++    /// Set by `stopLoading()`, checked between chunks of a `.streamed`+    /// response's drip loop so the mock can react to real cancellation+    /// (delivered by the URL Loading System when the owning `URLSessionTask`+    /// is cancelled) instead of running the drip loop to completion+    /// regardless. Guarded because `stopLoading()` is called from a+    /// different thread than the one running the drip loop.+    private let cancelLock = NSLock()+    nonisolated(unsafe) private var wasCancelled = false++    private func markCancelled() {+        cancelLock.lock()+        wasCancelled = true+        cancelLock.unlock()+    }++    private func isCancelled() -> Bool {+        cancelLock.lock()+        defer { cancelLock.unlock() }+        return wasCancelled+    }+     override func startLoading() {         let scope = request.value(forHTTPHeaderField: Self.scopeHeader) ?? ""         guard let handler = Self.handler(forScope: scope) else {@@ -99,19 +229,30 @@ final class MockURLProtocol: URLProtocol {             case .redirect(let response, let redirectedRequest):                 client?.urlProtocol(self, wasRedirectedTo: redirectedRequest, redirectResponse: response)                 client?.urlProtocolDidFinishLoading(self)-            case .streamed(let response, let nextChunk):+            case .streamed(let response, let nextChunk, let onCancelled):                 client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)-                while let chunk = nextChunk() {-                    client?.urlProtocol(self, didLoad: chunk)+                // Hand the body off to `dripQueue` and return, so the+                // protocol thread stays free to deliver `stopLoading()`+                // while the body is still trickling (see `dripQueue`).+                dripQueue.async {+                    while !self.isCancelled(), let chunk = nextChunk() {+                        self.client?.urlProtocol(self, didLoad: chunk)+                    }+                    if self.isCancelled() {+                        onCancelled?()+                    } else {+                        self.client?.urlProtocolDidFinishLoading(self)+                    }                 }-                client?.urlProtocolDidFinishLoading(self)             }         } catch {             client?.urlProtocol(self, didFailWithError: error)         }     } -    override func stopLoading() {}+    override func stopLoading() {+        markCancelled()+    } }  /// Tests for URLDocumentLoader, which downloads and validates markdown from URLs.@@ -259,12 +400,332 @@ struct URLDocumentLoaderTests {             .response(self.mockResponse(url: url), oversizedData)         } -        await #expect(throws: URLDocumentLoader.LoadError.self) {+        // Assert the CASE, not the type. `LoadError.self` is satisfied just as+        // well by `.networkError(URLError.timedOut)`, so once T-2138 added an+        // end-to-end deadline to the same call this test could no longer tell+        // the reader which mechanism fired — and it was in fact taking exactly+        // 30.002 s, a timer value (T-2138 review round 5, T-2260).+        await #expect {             _ = try await URLDocumentLoader.load(                 from: url,                 sessionConfiguration: mockSessionConfig()             )+        } throws: { error in+            guard let loadError = error as? URLDocumentLoader.LoadError,+                  case .contentTooLarge = loadError else {+                return false+            }+            return true+        }+    }++    // MARK: - End-to-End Deadline (T-2138)++    @Test("Slow-drip body bypassing inactivity timeouts is bounded by the explicit deadline")+    func slowDripBodyBoundedByDeadline() async throws {+        let url = URL(string: "https://example.com/slow.md")!+        let maxDripChunks = 60+        let counter = ChunkCounter()+        let cancellation = CancellationRecorder()+        // Each byte arrives well within any per-request inactivity timeout,+        // but the body never finishes on its own within the test's short+        // deadline — simulating a server trickling bytes to hold the+        // connection open indefinitely (the T-2138 bug shape). Bounded to+        // `maxDripChunks` (3s of real drip) so the mock protocol's drip loop+        // still terminates on its own if the deadline enforcement regresses,+        // rather than hanging the test process forever. The drip runs on+        // `MockURLProtocol`'s own queue, NOT the protocol thread — see+        // `MockURLProtocol.dripQueue`; sleeping on the protocol thread is+        // what made this test unfalsifiable in T-2138 rounds 2-4.+        mockScope.handler = { _ in+            .streamed(self.mockResponse(url: url), {+                guard counter.bytesSent < maxDripChunks else { return nil }+                counter.bytesSent += 1+                Thread.sleep(forTimeInterval: 0.05)+                return Data("a".utf8)+            }, onCancelled: {+                // Runs on the drip queue, the same queue that mutates+                // `counter`, so this read is ordered against the writes above.+                cancellation.markCancelled(value: counter.bytesSent)+            })+        }++        let start = Date()+        await #expect {+            _ = try await URLDocumentLoader.load(+                from: url,+                sessionConfiguration: mockSessionConfig(),+                deadline: 0.2+            )+        } throws: { error in+            // Assert the specific underlying error, not just the LoadError+            // case: `.networkError` also wraps ordinary connection failures,+            // so only `.timedOut` proves this was the deadline (T-2138 review).+            guard let loadError = error as? URLDocumentLoader.LoadError,+                  case .networkError(let underlying) = loadError,+                  let urlError = underlying as? URLError else {+                return false+            }+            return urlError.code == .timedOut+        }++        // Primary assertion: the mock's drip loop must actually be torn down+        // (its `stopLoading()` observed and recorded), not merely have run to+        // completion on its own schedule while `load` happened to have+        // already thrown by then. This is deterministic — it either happened+        // or it didn't — unlike a wall-clock reading, which can look "fast+        // enough" purely by coincidence on a loaded machine.+        let cancelledInTime = await cancellation.waitUntilMarked(pollInterval: 0.05, attempts: 200)+        #expect(cancelledInTime, "mock never observed stopLoading() — the drip loop ran to completion instead")++        // And the teardown must have CUT THE BODY SHORT, not merely landed+        // after it finished: the chunk count captured when `stopLoading()`+        // was observed has to be below the drip's own 60-chunk bound. Without+        // this, a mock that only ever noticed cancellation at the very end of+        // its 3s drip would still satisfy the flag above.+        let chunksAtCancellation = cancellation.markedValue()+        #expect(+            (chunksAtCancellation ?? maxDripChunks) < maxDripChunks,+            "teardown landed only after the body finished (\(chunksAtCancellation ?? -1) of \(maxDripChunks) chunks)"+        )++        // Secondary, generous guard: the production default deadline is 30s,+        // so a 10s ceiling still leaves a wide margin over the 0.2s injected+        // deadline without being a tight timing assertion on its own. The poll+        // above returns as soon as the flag is set, so this only ever fires+        // when nothing was torn down at all — it is a ceiling, not a+        // measurement of how loaded the host is.+        let elapsed = Date().timeIntervalSince(start)+        #expect(elapsed < 10.0)+    }++    @Test("withDeadline returns on time even when the operation ignores cooperative cancellation",+          .timeLimit(.minutes(1)))+    func withDeadlineReturnsWithoutWaitingForUncooperativeOperation() async throws {+        // The time limit is not decoration. The operation below never+        // completes on its own, so a regression in `withDeadline` does not+        // fail this test — it wedges the whole run. One process hosts the+        // entire unit-test target, and this project has lost whole runs to+        // exactly that (T-2219, T-2096); `WebViewPoolTests` carries the same+        // trait for the same reason.+        // An unresumed `CheckedContinuation` stands in for the review's+        // exact concern: a `URLSession.AsyncBytes` iteration reading a+        // connection stalled at the socket level, which likewise will not+        // notice Swift-level cancellation promptly. This replaces an+        // earlier version that used `Thread.sleep(forTimeInterval: 1.0)`+        // for the same purpose: `Thread.sleep` blocks a real OS thread out+        // of Swift's cooperative pool for the full second, and this suite+        // runs alongside other concurrently-executing test suites on the+        // same limited pool, so a one-second thread-block is a real cost,+        // not just a slow test (non-blocking review note, T-2138 round 2).+        // Suspending on a continuation that is deliberately never resumed+        // holds no thread and never completes on its own — a stronger proof+        // that `withDeadline` doesn't wait for the operation than a timed+        // sleep, since there's no wall-clock instant the operation could+        // ever finish by. Calling `URLDocumentLoader.withDeadline` directly+        // (rather than through the full `load`/`MockURLProtocol` path) is+        // what makes this deterministic: `MockURLProtocol` only controls+        // data delivery, not whether `URLSession.bytes(for:)`'s internal+        // cancellation plumbing is prompt, so no amount of mock cleverness+        // can otherwise prove the guarantee this test is checking.+        //+        // The continuation is parked in a holder rather than simply dropped+        // so teardown can resume it. Dropping it printed+        // "SWIFT TASK CONTINUATION MISUSE: ... leaked its continuation+        // without resuming it" into every run's log, which reads like a+        // production defect to anyone scanning the output. Releasing it after+        // the assertions changes nothing about what is proven: `withDeadline`+        // has already returned by then, and the operation's late+        // `gate.resume` is a no-op.+        let parked = ParkedContinuation()+        let start = Date()+        await #expect {+            _ = try await URLDocumentLoader.withDeadline(seconds: 0.1) {+                await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in+                    // Not resumed until teardown — for the whole duration of+                    // the deadline race the operation ignores cancellation+                    // and never completes.+                    parked.park(continuation)+                }+                return "unreachable"+            }+        } throws: { error in+            (error as? URLError)?.code == .timedOut+        }+        let elapsed = Date().timeIntervalSince(start)+        parked.release()++        // This is the assertion that actually distinguishes the fix from the+        // withThrowingTaskGroup-based implementation it replaced: a+        // group-based race implicitly awaits every child — including the+        // still-suspended one — before the group scope can return, so it+        // would hang forever here regardless of which branch "won" the race+        // internally. Any finite bound discriminates that, so the ceiling is+        // deliberately generous rather than a timing measurement: 2 s over a+        // 0.1 s deadline cannot be reached by a loaded host, only by a+        // regression.+        #expect(elapsed < 2.0)+    }++    @Test("withDeadline propagates cancellation of the calling task into the operation")+    func withDeadlinePropagatesCallerCancellation() async throws {+        // T-2138 review round 2: the unstructured `workTask` plus a bare+        // `withCheckedThrowingContinuation` did not observe cancellation of+        // the task CALLING `withDeadline` — only its own 30s deadline and+        // the operation finishing/throwing could resume it. That meant+        // `RemoteContentCoordinator.cancelDownload()` /+        // `RemoteRefreshFlow.cancel()` flipped the UI immediately while the+        // abandoned network operation kept running underneath for up to the+        // full deadline. This test calls `withDeadline` from a `Task` and+        // cancels that `Task` mid-flight — the operation is cooperative+        // (polls `Task.isCancelled`, unlike the uncooperative-operation+        // test above) specifically so this test can prove propagation, not+        // just that `withDeadline` forgets about an abandoned task.+        let operationStarted = CancellationRecorder()+        let operationObservedCancellation = CancellationRecorder()++        let task = Task {+            try await URLDocumentLoader.withDeadline(seconds: 5.0) {+                operationStarted.markCancelled() // reused as a plain "did start" flag+                // Bounded to ~3s (300 * 10ms) so a regression — cancellation+                // never reaching this operation — makes the loop exit on+                // its own bound rather than the test hanging until the 5s+                // deadline; the assertions below still correctly fail in+                // that case (elapsed and "observed" both prove the miss).+                var iterations = 0+                while !Task.isCancelled, iterations < 300 {+                    try? await Task.sleep(nanoseconds: 10_000_000)+                    iterations += 1+                }+                if Task.isCancelled {+                    operationObservedCancellation.markCancelled()+                }+                throw CancellationError()+            }+        }++        let started = await operationStarted.waitUntilMarked(pollInterval: 0.01, attempts: 100)+        #expect(started, "operation never started")++        let start = Date()+        task.cancel()++        await #expect {+            _ = try await task.value+        } throws: { error in+            error is CancellationError+        }+        let elapsed = Date().timeIntervalSince(start)++        // Must return promptly — nowhere near the 5s deadline or the+        // operation's ~3s bound — proving cancellation reached `withDeadline`+        // directly rather than falling back to either.+        #expect(elapsed < 1.0)++        let observed = await operationObservedCancellation.waitUntilMarked(pollInterval: 0.01, attempts: 100)+        #expect(observed, "operation never observed cancellation — withDeadline did not cancel workTask")+    }++    // MARK: - DeadlineGate ordering (T-2138 review round 5)++    /// Runs `body` — which must arrange for `gate` to be started — and returns+    /// its outcome, resuming the gate with `GateRescueError` after two+    /// seconds if nothing else has.+    ///+    /// The rescue is what makes these tests FAIL rather than HANG on the+    /// pre-fix gate, where `start` unconditionally stored the continuation+    /// (so a later `resume` still reaches it) but an earlier one was dropped.+    /// On the fixed gate the rescue is a no-op: the result has already been+    /// delivered and the gate honours only the first resume.+    private func gateOutcome<T: Sendable>(+        _ gate: URLDocumentLoader.DeadlineGate<T>,+        _ body: @escaping @Sendable (CheckedContinuation<T, Error>) -> Void+    ) async -> Result<T, Error> {+        let probe = Task<T, Error> {+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<T, Error>) in+                body(continuation)+            }+        }+        let rescue = Task {+            try? await Task.sleep(nanoseconds: 2_000_000_000)+            gate.resume(throwing: GateRescueError())+        }+        let outcome = await probe.result+        rescue.cancel()+        return outcome+    }++    @Test("DeadlineGate delivers a value that arrived before start",+          .timeLimit(.minutes(1)))+    func deadlineGateDeliversValueLatchedBeforeStart() async {+        // The ordering `withDeadline` cannot rule out and used to lose:+        // `workTask` reaches `gate.resume` before the creating thread reaches+        // `gate.start`. Forced here rather than raced, because racing the+        // scheduler is exactly what a regression test must not do — that+        // window is why the defect survived four review rounds.+        let gate = URLDocumentLoader.DeadlineGate<Int>()+        gate.resume(returning: 42)++        let outcome = await gateOutcome(gate) { continuation in+            gate.start(continuation: continuation, work: Task {}, timeout: Task {})+        }++        #expect(+            (try? outcome.get()) == 42,+            "gate dropped a value that arrived before start — the continuation would never be resumed"+        )+    }++    @Test("DeadlineGate delivers a failure that arrived before start",+          .timeLimit(.minutes(1)))+    func deadlineGateDeliversFailureLatchedBeforeStart() async {+        // Same ordering, failure side: the window is WIDEST when `operation`+        // fails fast (an immediate throw from `session.bytes(for:)`, a+        // Content-Length rejection, a mock-backed instant response), because+        // there is nothing to slow the work task down before it resumes.+        let gate = URLDocumentLoader.DeadlineGate<Int>()+        gate.resume(throwing: ImmediateOperationFailure())++        let outcome = await gateOutcome(gate) { continuation in+            gate.start(continuation: continuation, work: Task {}, timeout: Task {})+        }++        guard case .failure(let error) = outcome else {+            Issue.record("gate delivered a value where the operation had thrown")+            return+        }+        #expect(+            error is ImmediateOperationFailure,+            "gate dropped a failure that arrived before start (got \(error))"+        )+    }++    @Test("withDeadline returns promptly for an operation that completes immediately",+          .timeLimit(.minutes(1)))+    func withDeadlineReturnsImmediateSuccess() async throws {+        // End-to-end shape of the ordering above, at the production deadline:+        // if the early resume were dropped, nothing would ever resume the+        // continuation (the cleanup task cancels the timeout task as soon as+        // the work task finishes), so this would hang rather than time out+        // after 30 s.+        let start = Date()+        let value = try await URLDocumentLoader.withDeadline(seconds: 30) { "done" }+        #expect(value == "done")+        #expect(Date().timeIntervalSince(start) < 2.0)+    }++    @Test("withDeadline surfaces an operation that throws immediately",+          .timeLimit(.minutes(1)))+    func withDeadlineSurfacesImmediateThrow() async {+        let start = Date()+        await #expect {+            _ = try await URLDocumentLoader.withDeadline(seconds: 30) { () async throws -> String in+                throw ImmediateOperationFailure()+            }+        } throws: { error in+            error is ImmediateOperationFailure         }+        #expect(Date().timeIntervalSince(start) < 2.0)     }      // MARK: - Encoding Validation

diff --git a/prism/Services/RenderingUtilities.swift b/prism/Services/RenderingUtilities.swiftindex 87bde6f1..309a3bc3 100644--- a/prism/Services/RenderingUtilities.swift+++ b/prism/Services/RenderingUtilities.swift@@ -30,6 +30,23 @@ enum RenderingUtilities {     /// Races `operation` against a `seconds`-second timeout. If the timeout     /// fires first, the supplied `timeoutError` is thrown. The losing branch     /// is cancelled.+    ///+    /// Known limitation, deliberately not fixed here: `withThrowingTaskGroup`+    /// implicitly awaits every child before the group scope returns, even+    /// after `cancelAll()`. This therefore bounds when the WINNER is known,+    /// not when this function RETURNS — if `operation` is slow to notice+    /// cooperative cancellation, the caller waits for it anyway and the+    /// timeout degrades to whatever the operation eventually does.+    /// `URLDocumentLoader.withDeadline` (T-2138) exists because that+    /// degradation is unacceptable for a network read, and races an+    /// unstructured task through a single-resume continuation instead.+    /// That fix is NOT mechanically portable here: `operation` is a+    /// `@MainActor` `WKWebView` call holding a `WebViewPool` slot, so+    /// abandoning the loser would leak the slot rather than just the task.+    /// The exposure is tracked as T-2134 (SVG snapshot timeout can hang past+    /// its deadline), whose suggested fix bounds the operation itself — a+    /// token-validated timeout bridge inside `WebViewPool.captureSnapshot` —+    /// rather than abandoning it.     static func withTimeout<T: Sendable>(         seconds: UInt64,         timeoutError: @autoclosure @Sendable @escaping () -> any Error & Sendable,

diff --git a/prism/ViewModels/RemoteContentCoordinator.swift b/prism/ViewModels/RemoteContentCoordinator.swiftindex 8fede38a..9a9d49e5 100644--- a/prism/ViewModels/RemoteContentCoordinator.swift+++ b/prism/ViewModels/RemoteContentCoordinator.swift@@ -95,7 +95,13 @@ final class RemoteContentCoordinator {                     fragment: fragment                 )             } catch is CancellationError {-                // Silently ignore cancellation+                // Unreachable with the production loader: `URLDocumentLoader.load`+                // wraps every non-`LoadError` — including `URLError.cancelled` and+                // `CancellationError` — as `LoadError.networkError`. Kept for+                // injected loaders. Real cancellation is suppressed by the+                // `!Task.isCancelled` guard in the catch below, which is a+                // property of this caller rather than of the loader+                // (matches `RemoteRefreshFlow`).             } catch {                 guard !Task.isCancelled else { return }                 flowCoordinator.loadError = error.localizedDescription

diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bb517458..31f674e7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0  ### Fixed +- A remote document opened from a URL is no longer left downloading indefinitely against a server that trickles the body slowly enough to dodge the 30-second timeout (T-2138). The timeout applied only to network inactivity, so a byte sent just before each interval elapsed kept the load open with no end-to-end bound; the whole download is now also bounded by an explicit 30-second deadline covering redirects and streaming together. Adding that deadline also surfaced, and fixed, a far larger problem it would otherwise have masked: reading the downloaded body was running on the main thread, where it is roughly 150 times slower. Measured on this project's own build, reading a 10 MB body takes 0.88 seconds off the main thread and 133 seconds on it — which means the 10 MB size limit could not be reached within any 30-second bound at all, and a large remote document would have been abandoned as a timeout rather than downloaded. The read now genuinely runs off the main thread, so a large remote document opens in about a second instead of holding the interface still for minutes, and a file that really is over 10 MB is refused for its size, with the message that says so, rather than as a network timeout. Both the code and this entry record why that placement is load-bearing, because it is undone by an innocuous-looking change to one attribute. - An image that is tiny as a file but enormous as a picture can no longer exhaust memory or terminate Prism, whether it comes from the web, from a file beside the document, or written directly into the markdown (T-2132, T-2149, T-2151, T-1867). A picture is stored compressed, and a plain-coloured one compresses at about a thousand to one — so a 400 KB download can be a 20,000 by 20,000 image that needs about 400 MB the moment anything tries to display it, and four times that if it is in colour. Prism's limits were all written on the wrong side of that: a 50 MB cap on the download said nothing about the picture inside it, and the 2 MB cap on a local SVG was applied only after the whole file had already been read, so a very large one could freeze the app on its way to being refused. The limits that did exist covered only images fetched from the web; the same image referenced from a file next to your document, or embedded inline in the markdown, went straight to the renderer unchecked. Prism now reads the picture's dimensions from its header — a few bytes, before anything is decoded — and decides from that. An ordinary image is displayed as before. A very large one referenced from the web or from a file is scaled down to fit. One beyond any reasonable size is refused outright and shows the usual "Image failed to load" placeholder, rather than being handed to a decoder that would have to build the whole thing first. How large a picture is now also accounts for how much detail each dot of it carries: most pictures store one byte per colour, but some store two or four, and Prism previously assumed the smaller size for all of them and so under-counted the deep ones by half or three quarters. One consequence you may see: a very large deep-colour photograph that used to display at full size is now scaled down, because its true size was always above the limit and is now measured as such. Files are now read up to their limit instead of read whole and then measured — including the copy Prism keeps of a document you have not saved yet, which is restored when the app reopens. How much decoding happens at once is limited by how much memory those pictures actually need rather than by how many of them there are, so a page full of large images no longer overruns while appearing to stay within its bounds. Two things behave differently, both deliberately. An image whose file does not say how big it is, or what kind of dots it stores, now shows the "Image failed to load" placeholder instead of being displayed — there is no way to know what it would cost until it has already cost it. And an image written directly into the markdown is treated more strictly than the same image kept in a file beside the document: it is either small enough to display as it is or refused, never scaled down. That difference is about memory rather than effort. Scaling a picture that is written into the markdown means rebuilding it and writing the smaller version back into the page, where it then stays for as long as the document is open — which costs more memory, for longer, than not showing it. A picture in a file has somewhere else to keep its smaller version, so it can be scaled instead of refused. Animated images are unaffected in either case: they play as before, however many frames they have. - A verification scan that starts during the app's initial entitlement bootstrap can no longer publish a stale result while a newer scan is still in flight (T-2152). While `entitlementState` was still `.loading`, any scan's result was accepted regardless of whether a more recent scan — for example one started right after `AppStore.sync()` — was still reading the world; the older scan finishing first could briefly flip the paywall to locked (or unlocked) ahead of the newer, more current answer. An older result that arrives while a newer scan is still outstanding is now held back rather than published. If the newer scan goes on to answer, its fresher result is published and the held-back one is simply dropped; if instead it is cancelled without ever answering, the held-back result is released, so a cancelled scan cannot leave the paywall stranded on `.loading`. The trade is that the brief loading state now ends when the last overlapping scan answers rather than the first, so it can last marginally longer; every control it gates is disabled meanwhile, so nothing silently does nothing. - Saving a pasted document to a file no longer disturbs whatever document you opened next (T-2213). A save finishes in two parts: the file is written straight away, but the document only becomes that file once its notes have been moved across, and on a slow iCloud connection that second part can still be running after you have closed the document or opened another one. When it finished late, it acted on the document then on screen instead of the one it had saved: the pasted text of that other document was deleted from the place Prism keeps unsaved documents — so it could no longer be recovered after a relaunch — its entry in Recent Files was labelled with the wrong document's title, and an action you had queued behind its own Save prompt could run without you confirming it. A save that failed to move its notes also raised an alert naming a file you were no longer looking at. Each of these now belongs to the document that was actually saved, and the document on screen is left alone. Its Recent Files entry is labelled with its own title rather than the other document's. Where that other document had itself started saving in the meantime, the late save no longer takes over the shortcut that document had prepared for its own file, which can leave the saved file without a Recent Files entry of its own. The file is saved either way, and can be opened from the Files app.