WP-5b: FSEvents ReturnWatcher per SPEC-A1c with review corrections

Sources/ShotdeckCore/Capture/CaptureRegion.swift

@@ -0,0 +1,58 @@
+import Foundation
+import AppKit  // NSScreen, NSDeviceDescriptionKey — macOS-only target, no portability concern
+
+/// A remembered rectangle, in CoreGraphics global display coordinates (origin top-left,
+/// y increasing downward — see the conversion note below).
+public struct CaptureRegion: Codable, Sendable, Equatable {
+    public let displayID: CGDirectDisplayID
+    public let rect: CGRect
+    public let capturedScale: CGFloat
+
+    public init(displayID: CGDirectDisplayID, rect: CGRect, capturedScale: CGFloat) {
+        self.displayID = displayID
+        self.rect = rect
+        self.capturedScale = capturedScale
+    }
+
+    /// Converts an AppKit rect in GLOBAL AppKit coordinates (bottom-left origin, y increasing
+    /// upward, anchored at the bottom-left of the PRIMARY screen — exactly what
+    /// `NSWindow.frame`, `NSEvent.mouseLocation` and `NSScreen.frame` already report; no
+    /// screen-local conversion is needed here) into global CoreGraphics coordinates
+    /// (top-left origin, y increasing downward, same primary-screen anchor). Both coordinate
+    /// systems share the SAME horizontal origin and the SAME anchor rectangle (the primary
+    /// screen's bounds) — only the vertical axis is mirrored around the primary's height.
+    /// That is why the flip below is correct for every attached screen, including one with a
+    /// negative AppKit x (to the left of primary) or a y that places it above the primary
+    /// (whose CG y then comes out negative): x is untouched, and the primary height is the
+    /// one fixed reference both systems agree on regardless of which physical screen the
+    /// rect is actually on.
+    public static func fromAppKit(rect: CGRect, on screen: NSScreen) -> CaptureRegion {
+        let displayID = (screen.deviceDescription[NSDeviceDescriptionKey("NSScreenNumber")]
+            as? NSNumber)?.uint32Value ?? CGMainDisplayID()
+        let primaryHeight = NSScreen.screens.first?.frame.height ?? screen.frame.height
+        return fromAppKit(rect: rect, displayID: displayID,
+                           capturedScale: screen.backingScaleFactor, primaryHeight: primaryHeight)
+    }
+
+    /// Injectable overload for deterministic geometry tests — no dependency on real attached
+    /// displays. The public overload above is a thin adapter over this.
+    static func fromAppKit(rect: CGRect, displayID: CGDirectDisplayID,
+                            capturedScale: CGFloat, primaryHeight: CGFloat) -> CaptureRegion {
+        let cgY = primaryHeight - rect.origin.y - rect.height
+        let cgRect = CGRect(x: rect.origin.x, y: cgY, width: rect.width, height: rect.height)
+        return CaptureRegion(displayID: displayID, rect: cgRect, capturedScale: capturedScale)
+    }
+
+    /// True when `displayID` is still attached AND `rect` still lies inside its current
+    /// bounds. Uses `CGDisplayIsActive` (returns 0 safely for an unknown id, never traps) and
+    /// `CGDisplayBounds` — both real CoreGraphics calls, no injection needed since this is a
+    /// live-state check by design.
+    public var isStillValid: Bool {
+        guard CGDisplayIsActive(displayID) != 0 else { return false }
+        let bounds = CGDisplayBounds(displayID)
+        return bounds.contains(rect)
+    }
+
+    /// Persisted in UserDefaults under this key BY THE APP (WP-4a), never by this type.
+    public static let defaultsKey = "ai.flowmaster.shotdeck.region"
+}

Sources/ShotdeckCore/Capture/HotkeyCenter.swift

@@ -0,0 +1,115 @@
+import Carbon.HIToolbox
+import Foundation
+
+/// Carbon's C event handler cannot capture Swift closures, so live handlers are kept in one
+/// process-wide table keyed by the numeric EventHotKeyID Carbon hands back on fire. Safe
+/// because InstallEventHandler on GetApplicationEventTarget() always delivers on the main
+/// thread, and every access here happens either from a @MainActor HotkeyCenter method or from
+/// the C callback below, which this process only ever invokes on the main run loop.
+private final class HotkeyDispatchTable: @unchecked Sendable {
+    static let shared = HotkeyDispatchTable()
+    private var handlers: [UInt32: @MainActor () -> Void] = [:]
+    private init() {}
+    func set(_ numericID: UInt32, _ handler: @escaping @MainActor () -> Void) {
+        handlers[numericID] = handler
+    }
+    func remove(_ numericID: UInt32) { handlers.removeValue(forKey: numericID) }
+    func fire(_ numericID: UInt32) { MainActor.assumeIsolated { handlers[numericID]?() } }
+}
+
+private func shotdeckCarbonHotkeyHandler(
+    _ nextHandler: EventHandlerCallRef?, _ event: EventRef?, _ userData: UnsafeMutableRawPointer?
+) -> OSStatus {
+    guard let event else { return OSStatus(eventNotHandledErr) }
+    var hotKeyID = EventHotKeyID()
+    let status = GetEventParameter(event, EventParamName(kEventParamDirectObject),
+        EventParamType(typeEventHotKeyID), nil, MemoryLayout<EventHotKeyID>.size, nil, &hotKeyID)
+    guard status == noErr else { return status }
+    HotkeyDispatchTable.shared.fire(hotKeyID.id)
+    return noErr
+}
+
+/// Four-character creator code used for every `EventHotKeyID` this process registers.
+private let shotdeckHotKeySignature: OSType = 0x53484F54 // "SHOT"
+
+@MainActor
+public final class HotkeyCenter {
+    private var bindings: [String: (ref: EventHotKeyRef, numericID: UInt32)] = [:]
+    private var nextNumericID: UInt32 = 1
+
+    private static var didInstallGlobalCarbonHandler = false
+    private static var carbonHandlerRef: EventHandlerRef?
+
+    public init() { HotkeyCenter.installGlobalCarbonHandlerIfNeeded() }
+
+    /// Registers a hotkey. `id` is a caller-chosen stable identifier. Re-registering the same
+    /// `id` first unregisters its previous binding, then attempts the new one (idempotent).
+    /// Returns false when Carbon's `RegisterEventHotKey` reports a non-`noErr` status — the
+    /// most common cause is the same keyCode+modifiers combination already being claimed
+    /// system-wide by this or another process.
+    @discardableResult
+    public func register(
+        id: String,
+        keyCode: UInt32,
+        modifiers: UInt32,
+        handler: @escaping @MainActor () -> Void
+    ) -> Bool {
+        unregister(id: id)
+
+        let hotKeyID = EventHotKeyID(signature: shotdeckHotKeySignature, id: nextNumericID)
+        var ref: EventHotKeyRef?
+        let status = RegisterEventHotKey(
+            keyCode,
+            modifiers,
+            hotKeyID,
+            GetApplicationEventTarget(),
+            0,
+            &ref
+        )
+        guard status == noErr, let ref else {
+            return false
+        }
+        bindings[id] = (ref: ref, numericID: nextNumericID)
+        HotkeyDispatchTable.shared.set(nextNumericID, handler)
+        nextNumericID += 1
+        return true
+    }
+
+    public func unregister(id: String) {
+        guard let binding = bindings.removeValue(forKey: id) else { return }
+        _ = UnregisterEventHotKey(binding.ref)
+        HotkeyDispatchTable.shared.remove(binding.numericID)
+    }
+
+    public func unregisterAll() {
+        let ids = Array(bindings.keys)
+        for id in ids {
+            unregister(id: id)
+        }
+    }
+
+    /// Installs the process-wide Carbon hot-key pressed handler exactly once.
+    private static func installGlobalCarbonHandlerIfNeeded() {
+        guard !didInstallGlobalCarbonHandler else { return }
+        didInstallGlobalCarbonHandler = true
+
+        var handlerRef: EventHandlerRef?
+        var eventTypes = [
+            EventTypeSpec(
+                eventClass: OSType(kEventClassKeyboard),
+                eventKind: OSType(kEventHotKeyPressed)
+            )
+        ]
+        let status = InstallEventHandler(
+            GetApplicationEventTarget(),
+            shotdeckCarbonHotkeyHandler,
+            1,
+            &eventTypes,
+            nil,
+            &handlerRef
+        )
+        if status == noErr {
+            carbonHandlerRef = handlerRef
+        }
+    }
+}

Sources/ShotdeckCore/Model/ShotdeckError.swift

@@ -16,7 +16,7 @@ public enum ShotdeckError: Error, LocalizedError, Sendable {
         case .screenRecordingNotGranted:
             return "Screen Recording is turned off. Grant it in System Settings to capture."
         case .noRegionRemembered:
-            return "No capture region is set. Press ⌥⇧1 to pick one."
+            return "No capture region is set. Choose 'Re-select area' from the Shotdeck menu."
         case .displayNoLongerConnected:
             return "The display used for capture is no longer connected."
         case .captureFailed(let underlying):

Sources/ShotdeckCore/Returns/AnnotationInspector.swift

@@ -0,0 +1,110 @@
+import Foundation
+import PDFKit
+
+public struct ReturnedDocument: Codable, Sendable, Identifiable, Equatable {
+    public var id: URL { fileURL }
+    public let fileURL: URL
+    /// Session UUID recovered from the PDF's subject attribute, when present and valid.
+    public let sessionID: UUID?
+    public let pageCount: Int
+    /// 1-based page numbers that carry at least one human mark, ascending, no duplicates.
+    public let annotatedPages: [Int]
+    public let detectedAt: Date
+    public var isCommented: Bool { !annotatedPages.isEmpty }
+
+    public init(
+        fileURL: URL,
+        sessionID: UUID?,
+        pageCount: Int,
+        annotatedPages: [Int],
+        detectedAt: Date
+    ) {
+        self.fileURL = fileURL
+        self.sessionID = sessionID
+        self.pageCount = pageCount
+        self.annotatedPages = annotatedPages
+        self.detectedAt = detectedAt
+    }
+}
+
+public enum AnnotationInspector {
+    private static let humanMarkTypes: Set<String> = [
+        PDFAnnotationSubtype.ink.rawValue,
+        PDFAnnotationSubtype.highlight.rawValue,
+        PDFAnnotationSubtype.underline.rawValue,
+        PDFAnnotationSubtype.strikeOut.rawValue,
+        // PDFKit has no PDFAnnotationSubtype.squiggly member (unsupported renderer),
+        // but Apple Markup still writes Adobe /Squiggly objects that we must count.
+        PDFAnnotationSubtype(rawValue: "/Squiggly").rawValue,
+        PDFAnnotationSubtype.freeText.rawValue,
+        PDFAnnotationSubtype.square.rawValue,
+        PDFAnnotationSubtype.circle.rawValue,
+        PDFAnnotationSubtype.line.rawValue,
+        PDFAnnotationSubtype.stamp.rawValue,
+        PDFAnnotationSubtype.text.rawValue,
+    ]
+
+    // .link ignored: a PDF hyperlink is structural, not a human mark.
+    // .popup ignored: it is always the companion of another annotation; counting it
+    //   would double-count a single human mark as two.
+    // .widget ignored: a form field. Shotdeck's own PASS/FAIL boxes are page content
+    //   (drawn by WP-2), never PDFAnnotation objects — a widget seen here can only be
+    //   introduced by a third-party tool flattening/reopening the file, and is not a
+    //   human mark either way.
+
+    /// PDFKit's `PDFAnnotation.type` may omit the leading slash that
+    /// `PDFAnnotationSubtype.rawValue` includes; compare against the slash form.
+    private static func pdfTypeName(_ type: String) -> String {
+        type.hasPrefix("/") ? type : "/" + type
+    }
+
+    private static func isHumanMark(_ annotation: PDFAnnotation) -> Bool {
+        guard let raw = annotation.type else { return false }
+        let type = pdfTypeName(raw)
+        guard humanMarkTypes.contains(type) else { return false }
+        if type == PDFAnnotationSubtype.ink.rawValue {
+            let b = annotation.bounds
+            return b.width > 0 && b.height > 0   // zero-area ink = an undone stroke, not a mark
+        }
+        return true
+    }
+
+    /// Opens the PDF at fileURL and reports which pages carry a genuine human mark.
+    /// Throws ShotdeckError.manifestCorrupt(path: fileURL.path) if PDFDocument cannot open it.
+    /// File modification date is never consulted; only persisted PDFAnnotation objects count.
+    public static func inspect(fileURL: URL) throws -> ReturnedDocument {
+        guard let document = PDFDocument(url: fileURL) else {
+            throw ShotdeckError.manifestCorrupt(path: fileURL.path)
+        }
+        var annotatedPages: [Int] = []
+        for index in 0..<document.pageCount {
+            guard let page = document.page(at: index) else { continue }
+            if page.annotations.contains(where: isHumanMark) {
+                annotatedPages.append(index + 1)   // 1-based
+            }
+        }
+        var sessionID: UUID?
+        if let subject = document.documentAttributes?[PDFDocumentAttribute.subjectAttribute] as? String {
+            sessionID = UUID(uuidString: subject)   // nil (not thrown) if it doesn't parse
+        }
+        return ReturnedDocument(
+            fileURL: fileURL, sessionID: sessionID, pageCount: document.pageCount,
+            annotatedPages: annotatedPages, detectedAt: Date()
+        )
+    }
+
+    /// True when this PDF was produced by Shotdeck. Creator attribute is authoritative;
+    /// the filename fallback applies ONLY when the creator attribute is absent.
+    public static func isShotdeckDocument(_ document: PDFDocument) -> Bool {
+        if let creator = document.documentAttributes?[PDFDocumentAttribute.creatorAttribute] as? String {
+            return creator == "Shotdeck"          // present creator is authoritative, full stop
+        }
+        // Creator ABSENT (some apps rewrite metadata on save) -> filename fallback only here.
+        guard let name = document.documentURL?.lastPathComponent else { return false }
+        // .lastPathComponent on a file URL is already percent-decoded; do not use .absoluteString.
+        return name.wholeMatch(of: /^Shotdeck-\d{8}-\d{6}( \d+)?\.pdf$/) != nil
+        // Case-sensitive by construction (Swift Regex literals are case-sensitive by default).
+        // The optional "( \d+)?" is macOS's duplicate-name suffix AirDrop adds when a file of
+        // the same name already exists in the watch folder — the normal case for a return.
+    }
+}

Sources/ShotdeckCore/Returns/ReturnLedger.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+public actor ReturnLedger {
+    private let fileURL: URL
+    private var entries: [URL: ReturnedDocument]
+
+    /// Loads `returns.json` under paths.root if it exists; starts empty otherwise.
+    /// A file that cannot be decoded is renamed (never deleted) and the ledger starts empty.
+    public init(paths: AppSupportPaths) throws {
+        self.fileURL = paths.root.appendingPathComponent("returns.json")
+        if FileManager.default.fileExists(atPath: fileURL.path) {
+            let data = try Data(contentsOf: fileURL)
+            do {
+                let decoded = try JSONDecoder().decode([ReturnedDocument].self, from: data)
+                entries = Dictionary(decoded.map { ($0.fileURL, $0) }, uniquingKeysWith: { _, new in new })
+            } catch {
+                let stamp = DubaiTime.fileStamp(Date())
+                let corruptURL = fileURL.deletingLastPathComponent()
+                    .appendingPathComponent("returns.json.corrupt-\(stamp)")
+                try FileManager.default.moveItem(at: fileURL, to: corruptURL)
+                Log.returns.error(
+                    "returns.json could not be decoded; moved to \(corruptURL.path, privacy: .public): \(error.localizedDescription, privacy: .public)"
+                )
+                entries = [:]
+            }
+        } else {
+            entries = [:]
+        }
+    }
+
+    /// Upserts by fileURL — recording the same URL again replaces the prior entry
+    /// (the most recently recorded call wins, regardless of its detectedAt value).
+    public func record(_ document: ReturnedDocument) throws {
+        entries[document.fileURL] = document
+        try persist()
+    }
+
+    /// Every recorded return, newest detectedAt first.
+    public func all() throws -> [ReturnedDocument] {
+        entries.values.sorted { $0.detectedAt > $1.detectedAt }
+    }
+
+    /// Commented returns (isCommented == true), newest detectedAt first.
+    public func commented() throws -> [ReturnedDocument] {
+        try all().filter(\.isCommented)
+    }
+
+    /// Absolute POSIX paths of commented returns, newest first, one per line, no
+    /// trailing newline. Throws ShotdeckError.noCommentedReturns when commented() is empty.
+    public func clipboardText() throws -> String {
+        let paths = try commented().map { $0.fileURL.path }
+        guard !paths.isEmpty else { throw ShotdeckError.noCommentedReturns }
+        return paths.joined(separator: "\n")
+    }
+
+    private func persist() throws {
+        let data = try JSONEncoder().encode(Array(entries.values))
+        try AtomicFile.write(data, to: fileURL)
+    }
+}

Sources/ShotdeckCore/Returns/ReturnWatcher.swift

@@ -0,0 +1,154 @@
+import Foundation
+import PDFKit
+import CoreServices   // FSEventStream* APIs; system framework, no Package.swift change needed
+
+public actor ReturnWatcher {
+    private let ledger: ReturnLedger
+    private var watchFolder: URL
+    private var onChange: (@Sendable ([ReturnedDocument]) -> Void)?
+    private var stream: FSEventStreamRef?
+    private var bridge: FSEventBridge?
+    private var pendingScanTask: Task<Void, Never>?
+    private let eventQueue = DispatchQueue(label: "ai.flowmaster.shotdeck.returns.fsevents")
+
+    /// Watch folder is `paths.watchFolder`, which production constructs from
+    /// `FolderSettings.resolve().watch`. This type never calls FolderSettings;
+    /// `updateWatchFolder` is invoked by the UI layer only.
+    public init(paths: AppSupportPaths, ledger: ReturnLedger) {
+        self.ledger = ledger
+        self.watchFolder = paths.watchFolder   // never a literal "~/Downloads" here
+    }
+
+    /// Starts watching paths.watchFolder for returned PDFs. Performs one immediate
+    /// scanNow() before returning, then calls onChange after every subsequent debounced
+    /// batch (even if that batch's result is empty — the caller decides what to do).
+    public func start(onChange: @escaping @Sendable ([ReturnedDocument]) -> Void) async throws {
+        self.onChange = onChange
+        try startStream(on: watchFolder)
+        let found = try await scanNow()
+        onChange(found)
+    }
+
+    /// Idempotent. Stops and releases the FSEventStream if one is running; safe to call
+    /// when never started or already stopped. Cancels any pending debounced scan.
+    public func stop() {
+        // Idempotent: nil stream / already-stopped is a no-op; never started is the same.
+        pendingScanTask?.cancel()
+        pendingScanTask = nil
+        if let stream {
+            FSEventStreamStop(stream)
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+        }
+        stream = nil
+        bridge = nil
+    }
+
+    /// Called by whoever owns the Settings "Choose..." folder action (WP-4c) after the user
+    /// picks a new watch folder. If the watcher was running, stops the old FSEventStream,
+    /// switches to the new folder, restarts, and performs one immediate scanNow (reporting
+    /// through the same onChange callback given to start()). If the watcher was never
+    /// started, only updates the stored folder for the next start() call.
+    public func updateWatchFolder(_ url: URL) async throws {
+        let wasRunning = stream != nil
+        stop()
+        watchFolder = url
+        guard wasRunning else { return }
+        try startStream(on: url)
+        let found = try await scanNow()
+        onChange?(found)
+    }
+
+    /// Scans the watch folder once, immediately, without waiting for an event. Every
+    /// recognized, stable, openable Shotdeck PDF present is (re-)inspected and (re-)recorded
+    /// into the ledger; returns exactly the documents processed in this call.
+    @discardableResult
+    public func scanNow() async throws -> [ReturnedDocument] {
+        let fm = FileManager.default
+        let candidates = (try? fm.contentsOfDirectory(
+            at: watchFolder, includingPropertiesForKeys: nil
+        )) ?? []
+        var results: [ReturnedDocument] = []
+        for url in candidates.sorted(by: { $0.lastPathComponent < $1.lastPathComponent }) {
+            let name = url.lastPathComponent
+            // ".pdf.inprogress" already fails hasSuffix(".pdf") -> naturally skipped.
+            guard name.hasSuffix(".pdf"), !name.hasPrefix(".") else { continue }
+            guard await isStableAndReadable(url) else { continue }   // leave for next event
+            guard let document = PDFDocument(url: url),
+                  AnnotationInspector.isShotdeckDocument(document) else { continue }
+            guard let inspected = try? AnnotationInspector.inspect(fileURL: url) else { continue }
+            try await ledger.record(inspected)
+            results.append(inspected)
+        }
+        return results
+    }
+
+    /// Size-stable: two equal byte counts 250 ms apart AND PDFDocument opens;
+    /// otherwise leave the file for the next event.
+    private func isStableAndReadable(_ url: URL) async -> Bool {
+        let fm = FileManager.default
+        guard let size1 = try? fm.attributesOfItem(atPath: url.path)[.size] as? Int else { return false }
+        try? await Task.sleep(for: .milliseconds(250))
+        guard let size2 = try? fm.attributesOfItem(atPath: url.path)[.size] as? Int else { return false }
+        guard size1 == size2, size1 > 0 else { return false }
+        return PDFDocument(url: url) != nil
+    }
+
+    private func startStream(on folder: URL) throws {
+        let bridge = FSEventBridge { [weak self] in
+            guard let self else { return }
+            Task { await self.scheduleDebouncedScan() }
+        }
+        self.bridge = bridge
+        var context = FSEventStreamContext()
+        context.version = 0
+        context.info = Unmanaged.passUnretained(bridge).toOpaque()
+        context.retain = nil
+        context.release = nil
+        context.copyDescription = nil
+        guard let stream = FSEventStreamCreate(
+            kCFAllocatorDefault, shotdeckFSEventsCallback, &context,
+            [folder.path] as CFArray, FSEventStreamEventId(kFSEventStreamEventIdSinceNow),
+            0.0,
+            FSEventStreamCreateFlags(kFSEventStreamCreateFlagFileEvents | kFSEventStreamCreateFlagNoDefer)
+        ) else {
+            throw ShotdeckError.captureFailed(underlying: "could not create FSEventStream for \(folder.path)")
+        }
+        // Dispatch queue, not a run loop: this actor has no run loop of its own, and
+        // FSEventStreamSetDispatchQueue is the modern replacement for
+        // FSEventStreamScheduleWithRunLoop. One dedicated serial queue per watcher.
+        FSEventStreamSetDispatchQueue(stream, eventQueue)
+        guard FSEventStreamStart(stream) else {
+            FSEventStreamInvalidate(stream)
+            FSEventStreamRelease(stream)
+            throw ShotdeckError.captureFailed(underlying: "FSEventStreamStart failed for \(folder.path)")
+        }
+        self.stream = stream
+    }
+
+    private func scheduleDebouncedScan() async {
+        pendingScanTask?.cancel()
+        pendingScanTask = Task {
+            try? await Task.sleep(for: .milliseconds(400))   // coalesce AirDrop's write+rename burst
+            guard !Task.isCancelled else { return }
+            guard let found = try? await self.scanNow() else { return }
+            // One in-flight debounced callback may land after stop(); it is a
+            // harmless read-only rescan (ledger upsert, no watch-folder mutation).
+            self.onChange?(found)
+        }
+    }
+}
+
+/// Non-actor bridge because FSEventStreamCallback is a @convention(c) function pointer and
+/// cannot capture actor-isolated state directly; it hops back onto the actor via Task.
+private final class FSEventBridge: @unchecked Sendable {
+    // @unchecked is safe: `notify` is a let, set once at init, never mutated after — the
+    // type is immutable for its entire lifetime.
+    let notify: @Sendable () -> Void
+    init(notify: @escaping @Sendable () -> Void) { self.notify = notify }
+}
+
+private let shotdeckFSEventsCallback: FSEventStreamCallback = { _, info, _, _, _, _ in
+    guard let info else { return }
+    Unmanaged<FSEventBridge>.fromOpaque(info).takeUnretainedValue().notify()
+}

Sources/ShotdeckCore/Support/AtomicFile.swift

@@ -0,0 +1,104 @@
+import Foundation
+import Darwin
+
+public enum AtomicFile {
+    /// Writes `data` to `url` durably: writes to `<url>.tmp` in the SAME directory as `url`,
+    /// fsyncs that file descriptor, closes it, rename()s it onto `url` (atomic same-volume
+    /// rename), then opens `url`'s containing directory and fsyncs THAT too (a rename is only
+    /// durable once its directory entry is flushed). Never uses `Data.write(to:)` — that call
+    /// does not fsync.
+    public static func write(_ data: Data, to url: URL) throws {
+        let finalPath = url.path
+        let directoryURL = url.deletingLastPathComponent()
+        let tmpURL = directoryURL.appendingPathComponent(url.lastPathComponent + ".tmp")
+        let tmpPath = tmpURL.path
+
+        // Clear a stale .tmp left by a previous crash. ENOENT (nothing to clear) is fine.
+        if unlink(tmpPath) != 0 && errno != ENOENT {
+            throw ShotdeckError.spoolWriteFailed(
+                path: finalPath,
+                underlying: "could not clear a stale temp file: \(String(cString: strerror(errno)))")
+        }
+
+        let fd = open(tmpPath, O_WRONLY | O_CREAT | O_TRUNC, 0o644)
+        guard fd >= 0 else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: finalPath, underlying: "open failed: \(String(cString: strerror(errno)))")
+        }
+
+        var writeFailure: String?
+        data.withUnsafeBytes { (raw: UnsafeRawBufferPointer) in
+            var remaining = raw.count
+            var pointer = raw.baseAddress
+            while remaining > 0 {
+                let n = Darwin.write(fd, pointer, remaining)
+                if n < 0 {
+                    if errno == EINTR { continue }
+                    writeFailure = "write failed: \(String(cString: strerror(errno)))"
+                    break
+                }
+                if n == 0 { break }
+                remaining -= n
+                pointer = pointer?.advanced(by: n)
+            }
+        }
+        if let writeFailure {
+            close(fd)
+            _ = unlink(tmpPath)
+            throw ShotdeckError.spoolWriteFailed(path: finalPath, underlying: writeFailure)
+        }
+        if fsync(fd) != 0 {
+            let message = "fsync failed: \(String(cString: strerror(errno)))"
+            close(fd)
+            _ = unlink(tmpPath)
+            throw ShotdeckError.spoolWriteFailed(path: finalPath, underlying: message)
+        }
+        if close(fd) != 0 {
+            _ = unlink(tmpPath)
+            throw ShotdeckError.spoolWriteFailed(
+                path: finalPath, underlying: "close failed: \(String(cString: strerror(errno)))")
+        }
+        if rename(tmpPath, finalPath) != 0 {
+            let message = "rename failed: \(String(cString: strerror(errno)))"
+            _ = unlink(tmpPath)
+            throw ShotdeckError.spoolWriteFailed(path: finalPath, underlying: message)
+        }
+        try fsyncDirectory(at: directoryURL)
+    }
+
+    /// Encodes `value` with `JSONEncoder` (`.sortedKeys, .prettyPrinted`,
+    /// `.dateEncodingStrategy = .iso8601`) and writes it through `write(_:to:)`.
+    public static func writeJSON<T: Encodable>(_ value: T, to url: URL) throws {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys, .prettyPrinted]
+        encoder.dateEncodingStrategy = .iso8601
+        let data: Data
+        do {
+            data = try encoder.encode(value)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: url.path, underlying: "JSON encoding failed: \(error.localizedDescription)")
+        }
+        try write(data, to: url)
+    }
+
+    /// Opens `url` (must be an existing directory) and fsyncs it. Used after any directory-
+    /// level `rename()` (moving/renaming a whole session directory) — the same durability
+    /// requirement as the internal directory-fsync inside `write(_:to:)`, exposed for callers
+    /// that rename directories themselves (SpoolStore).
+    public static func fsyncDirectory(at url: URL) throws {
+        let fd = open(url.path, O_RDONLY | O_DIRECTORY)
+        guard fd >= 0 else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: url.path,
+                underlying: "could not open directory for fsync: \(String(cString: strerror(errno)))")
+        }
+        let result = fsync(fd)
+        close(fd)
+        if result != 0 {
+            throw ShotdeckError.spoolWriteFailed(
+                path: url.path,
+                underlying: "directory fsync failed: \(String(cString: strerror(errno)))")
+        }
+    }
+}

Sources/ShotdeckCore/Support/FolderSettings.swift

@@ -0,0 +1,111 @@
+import Foundation
+
+/// User-configurable overrides for the outbox (PDF send destination) and watch folder
+/// (AirDrop return), backed by UserDefaults. Shotdeck is NOT App-Sandboxed (no
+/// `com.apple.security.app-sandbox` entitlement in this build — it is a plain, unsandboxed
+/// SwiftPM executable). Security-scoped bookmarks exist to let a SANDBOXED app retain access
+/// to a user-picked file/folder outside its container across relaunches; an unsandboxed
+/// process already has the invoking user's own filesystem permissions on every launch, so a
+/// plain absolute path stored in UserDefaults is sufficient — including for a mounted network
+/// share, which resolves by path the same as any local folder for as long as it is mounted.
+public enum FolderSettings {
+    public static let outboxDefaultsKey = "ai.flowmaster.shotdeck.outbox"
+    public static let watchFolderDefaultsKey = "ai.flowmaster.shotdeck.watchFolder"
+
+    /// Raw stored path (or nil if never set / cleared). For display in Settings — does NOT
+    /// validate that the path still exists.
+    public static func storedOutboxPath(defaults: UserDefaults = .standard) -> String? {
+        defaults.string(forKey: outboxDefaultsKey)
+    }
+
+    public static func storedWatchFolderPath(defaults: UserDefaults = .standard) -> String? {
+        defaults.string(forKey: watchFolderDefaultsKey)
+    }
+
+    /// Persists a user-chosen folder as its absolute POSIX path.
+    public static func setOutbox(_ url: URL, defaults: UserDefaults = .standard) {
+        defaults.set(url.path, forKey: outboxDefaultsKey)
+    }
+
+    public static func setWatchFolder(_ url: URL, defaults: UserDefaults = .standard) {
+        defaults.set(url.path, forKey: watchFolderDefaultsKey)
+    }
+
+    /// Removes the override; resolve() falls back to the default again.
+    public static func resetOutbox(defaults: UserDefaults = .standard) {
+        defaults.removeObject(forKey: outboxDefaultsKey)
+    }
+
+    public static func resetWatchFolder(defaults: UserDefaults = .standard) {
+        defaults.removeObject(forKey: watchFolderDefaultsKey)
+    }
+
+    /// Resolves both folders. A stored override wins only if it is set AND the directory it
+    /// names still exists; otherwise falls back to the default (Desktop / Downloads). Never
+    /// throws — a missing/bad override is logged via `Log.ui` and silently replaced.
+    public static func resolve(
+        defaults: UserDefaults = .standard,
+        fileManager: FileManager = .default
+    ) -> (outbox: URL, watch: URL) {
+        let outbox = resolveOne(
+            storedPath: storedOutboxPath(defaults: defaults),
+            fallback: defaultOutbox(fileManager: fileManager),
+            label: "outbox", fileManager: fileManager)
+        let watch = resolveOne(
+            storedPath: storedWatchFolderPath(defaults: defaults),
+            fallback: defaultWatchFolder(fileManager: fileManager),
+            label: "watch", fileManager: fileManager)
+        return (outbox, watch)
+    }
+
+    /// Builds an `AppSupportPaths` using `root` (defaults to the standard
+    /// `~/Library/Application Support/Shotdeck`, computed the same way
+    /// `AppSupportPaths.standard()` does, when `root` is nil) plus whatever `resolve()`
+    /// returns for outbox/watch. This is the ONLY place that combines FolderSettings with
+    /// AppSupportPaths — call this everywhere in the app instead of `AppSupportPaths.standard()`.
+    /// `root` is exposed purely so tests can point it at a temporary directory instead of the
+    /// user's real Application Support folder.
+    public static func resolvedAppSupportPaths(
+        root: URL? = nil,
+        defaults: UserDefaults = .standard,
+        fileManager: FileManager = .default
+    ) throws -> AppSupportPaths {
+        let resolvedRoot: URL
+        if let root {
+            resolvedRoot = root
+        } else {
+            let appSupportParent = try fileManager.url(
+                for: .applicationSupportDirectory, in: .userDomainMask,
+                appropriateFor: nil, create: true)
+            resolvedRoot = appSupportParent.appendingPathComponent("Shotdeck", isDirectory: true)
+        }
+        let folders = resolve(defaults: defaults, fileManager: fileManager)
+        return try AppSupportPaths(root: resolvedRoot, outbox: folders.outbox, watchFolder: folders.watch)
+    }
+
+    private static func defaultOutbox(fileManager: FileManager) -> URL {
+        fileManager.urls(for: .desktopDirectory, in: .userDomainMask).first
+            ?? fileManager.homeDirectoryForCurrentUser.appendingPathComponent("Desktop", isDirectory: true)
+    }
+
+    private static func defaultWatchFolder(fileManager: FileManager) -> URL {
+        fileManager.urls(for: .downloadsDirectory, in: .userDomainMask).first
+            ?? fileManager.homeDirectoryForCurrentUser.appendingPathComponent("Downloads", isDirectory: true)
+    }
+
+    private static func resolveOne(
+        storedPath: String?,
+        fallback: URL,
+        label: String,
+        fileManager: FileManager
+    ) -> URL {
+        guard let storedPath else { return fallback }
+        var isDirectory: ObjCBool = false
+        let exists = fileManager.fileExists(atPath: storedPath, isDirectory: &isDirectory)
+        guard exists, isDirectory.boolValue else {
+            Log.ui.warning("Configured \(label, privacy: .public) folder \(storedPath, privacy: .public) no longer exists; falling back to the default.")
+            return fallback
+        }
+        return URL(fileURLWithPath: storedPath, isDirectory: true)
+    }
+}

Sources/ShotdeckCore/Support/Log.swift

@@ -0,0 +1,9 @@
+import os
+
+public enum Log {
+    public static let spool = Logger(subsystem: "ai.flowmaster.shotdeck", category: "spool")
+    public static let pdf = Logger(subsystem: "ai.flowmaster.shotdeck", category: "pdf")
+    public static let capture = Logger(subsystem: "ai.flowmaster.shotdeck", category: "capture")
+    public static let returns = Logger(subsystem: "ai.flowmaster.shotdeck", category: "returns")
+    public static let ui = Logger(subsystem: "ai.flowmaster.shotdeck", category: "ui")
+}

Tests/ShotdeckCoreTests/AnnotationInspectorTests.swift

@@ -0,0 +1,412 @@
+import AppKit
+import Foundation
+import PDFKit
+import Testing
+import ShotdeckCore
+
+private let pageBounds = CGRect(x: 0, y: 0, width: 600, height: 800)
+
+private func makeAnnotation(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect = CGRect(x: 100, y: 100, width: 80, height: 40),
+    contents: String? = nil
+) -> PDFAnnotation {
+    let annotation = PDFAnnotation(
+        bounds: bounds,
+        forType: subtype,
+        withProperties: nil
+    )
+    annotation.contents = contents
+    return annotation
+}
+
+private func makePDF(
+    at url: URL,
+    pageCount: Int,
+    creator: String? = "Shotdeck",
+    subject: String? = nil,
+    annotations: [(page: Int, annotation: PDFAnnotation)] = []
+) throws {
+    let document = PDFDocument()
+    for index in 0..<pageCount {
+        let page = PDFPage()
+        page.setBounds(pageBounds, for: .mediaBox)
+        document.insert(page, at: index)
+    }
+
+    var attributes = [PDFDocumentAttribute: Any]()
+    if let creator { attributes[.creatorAttribute] = creator }
+    if let subject { attributes[.subjectAttribute] = subject }
+    document.documentAttributes = attributes
+
+    for item in annotations {
+        guard let page = document.page(at: item.page) else {
+            throw NSError(domain: "WP5Test", code: 1)
+        }
+        page.addAnnotation(item.annotation)
+    }
+
+    guard document.write(to: url) else {
+        throw NSError(domain: "WP5Test", code: 2)
+    }
+}
+
+private func makeCasePaths() throws -> (paths: AppSupportPaths, cleanup: URL) {
+    let cleanup = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-wp5a-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: cleanup.appendingPathComponent("root", isDirectory: true),
+        outbox: cleanup.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: cleanup.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (paths, cleanup)
+}
+
+@Test("I-1 Untouched PDF is clean")
+func i1_untouchedPDFIsClean() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134200.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        creator: "Shotdeck",
+        subject: "11111111-1111-1111-1111-111111111111"
+    )
+
+    var calendar = Calendar(identifier: .gregorian)
+    calendar.timeZone = try #require(TimeZone(identifier: "Asia/Dubai"))
+    let firstMTime = try #require(calendar.date(from: DateComponents(
+        year: 2026, month: 8, day: 30, hour: 13, minute: 42, second: 0
+    )))
+    let secondMTime = try #require(calendar.date(from: DateComponents(
+        year: 2026, month: 8, day: 30, hour: 13, minute: 43, second: 0
+    )))
+    try FileManager.default.setAttributes([.modificationDate: firstMTime], ofItemAtPath: pdfURL.path)
+    try FileManager.default.setAttributes([.modificationDate: secondMTime], ofItemAtPath: pdfURL.path)
+
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.fileURL == pdfURL)
+    #expect(inspected.sessionID == UUID(uuidString: "11111111-1111-1111-1111-111111111111"))
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [])
+    #expect(inspected.isCommented == false)
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(inspected)
+    let all = try await ledger.all()
+    #expect(all.count == 1)
+    #expect(all[0].fileURL == pdfURL)
+    #expect(try await ledger.commented() == [])
+    let clipboardError = try await #require(throws: ShotdeckError.self) {
+        try await ledger.clipboardText()
+    }
+    guard case .noCommentedReturns = clipboardError else {
+        Issue.record("expected noCommentedReturns, got \(clipboardError)")
+        return
+    }
+}
+
+@Test("I-2 Ink is a mark")
+func i2_inkIsAMark() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134201.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        annotations: [(page: 1, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 120, y: 240, width: 140, height: 60)
+        ))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [2])
+    #expect(inspected.isCommented == true)
+}
+
+@Test("I-3 Highlight is a mark")
+func i3_highlightIsAMark() throws {
+    try expectSinglePageMark(
+        .highlight,
+        bounds: CGRect(x: 80, y: 500, width: 300, height: 24),
+        fileName: "Shotdeck-20260830-134202.pdf"
+    )
+}
+
+@Test("I-4 Underline is a mark")
+func i4_underlineIsAMark() throws {
+    try expectSinglePageMark(
+        .underline,
+        bounds: CGRect(x: 90, y: 460, width: 280, height: 18),
+        fileName: "Shotdeck-20260830-134203.pdf"
+    )
+}
+
+@Test("I-5 Strike-out is a mark")
+func i5_strikeOutIsAMark() throws {
+    try expectSinglePageMark(
+        .strikeOut,
+        bounds: CGRect(x: 90, y: 430, width: 280, height: 18),
+        fileName: "Shotdeck-20260830-134204.pdf"
+    )
+}
+
+@Test("I-6 Squiggly is a mark")
+func i6_squigglyIsAMark() throws {
+    try expectSinglePageMark(
+        PDFAnnotationSubtype(rawValue: "/Squiggly"),
+        bounds: CGRect(x: 90, y: 400, width: 280, height: 18),
+        fileName: "Shotdeck-20260830-134205.pdf"
+    )
+}
+
+@Test("I-7 Free-text is a mark")
+func i7_freeTextIsAMark() throws {
+    try expectSinglePageMark(
+        .freeText,
+        bounds: CGRect(x: 140, y: 300, width: 220, height: 80),
+        contents: "Typed review note",
+        fileName: "Shotdeck-20260830-134206.pdf"
+    )
+}
+
+@Test("I-8 Square is a mark")
+func i8_squareIsAMark() throws {
+    try expectSinglePageMark(
+        .square,
+        bounds: CGRect(x: 160, y: 250, width: 100, height: 100),
+        fileName: "Shotdeck-20260830-134207.pdf"
+    )
+}
+
+@Test("I-9 Circle is a mark")
+func i9_circleIsAMark() throws {
+    try expectSinglePageMark(
+        .circle,
+        bounds: CGRect(x: 280, y: 250, width: 100, height: 100),
+        fileName: "Shotdeck-20260830-134208.pdf"
+    )
+}
+
+@Test("I-10 Line is a mark")
+func i10_lineIsAMark() throws {
+    try expectSinglePageMark(
+        .line,
+        bounds: CGRect(x: 100, y: 180, width: 320, height: 8),
+        fileName: "Shotdeck-20260830-134209.pdf"
+    )
+}
+
+@Test("I-11 Stamp is a mark")
+func i11_stampIsAMark() throws {
+    try expectSinglePageMark(
+        .stamp,
+        bounds: CGRect(x: 180, y: 500, width: 120, height: 60),
+        contents: "Approved",
+        fileName: "Shotdeck-20260830-134210.pdf"
+    )
+}
+
+@Test("I-12 Sticky text is a mark")
+func i12_stickyTextIsAMark() throws {
+    try expectSinglePageMark(
+        .text,
+        bounds: CGRect(x: 420, y: 620, width: 28, height: 28),
+        contents: "Look here",
+        fileName: "Shotdeck-20260830-134211.pdf"
+    )
+}
+
+@Test("I-13 Link alone is not a mark")
+func i13_linkAloneIsNotAMark() throws {
+    try expectSinglePageIgnored(
+        .link,
+        bounds: CGRect(x: 80, y: 700, width: 160, height: 20),
+        fileName: "Shotdeck-20260830-134212.pdf"
+    )
+}
+
+@Test("I-14 Popup alone is not a mark")
+func i14_popupAloneIsNotAMark() throws {
+    try expectSinglePageIgnored(
+        .popup,
+        bounds: CGRect(x: 450, y: 600, width: 100, height: 60),
+        fileName: "Shotdeck-20260830-134213.pdf"
+    )
+}
+
+@Test("I-15 Widget alone is not a mark")
+func i15_widgetAloneIsNotAMark() throws {
+    try expectSinglePageIgnored(
+        .widget,
+        bounds: CGRect(x: 100, y: 100, width: 140, height: 32),
+        fileName: "Shotdeck-20260830-134214.pdf"
+    )
+}
+
+@Test("I-16 Zero-area ink is not a mark")
+func i16_zeroAreaInkIsNotAMark() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134215.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 240, y: 240, width: 0, height: 0)
+        ))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.annotatedPages == [])
+    #expect(inspected.isCommented == false)
+}
+
+@Test("I-17 Ignored objects plus one real mark count once")
+func i17_ignoredObjectsPlusOneRealMarkCountOnce() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134216.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        annotations: [
+            (page: 1, annotation: makeAnnotation(.link, bounds: CGRect(x: 20, y: 20, width: 40, height: 20))),
+            (page: 1, annotation: makeAnnotation(.popup, bounds: CGRect(x: 70, y: 20, width: 40, height: 20))),
+            (page: 1, annotation: makeAnnotation(.widget, bounds: CGRect(x: 120, y: 20, width: 40, height: 20))),
+            (page: 1, annotation: makeAnnotation(.ink, bounds: CGRect(x: 200, y: 200, width: 120, height: 50))),
+        ]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [2])
+    #expect(inspected.isCommented == true)
+}
+
+@Test("I-18 Page numbers are 1-based and ascending")
+func i18_pageNumbersAre1BasedAndAscending() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134217.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 3,
+        annotations: [
+            (page: 0, annotation: makeAnnotation(.circle, bounds: CGRect(x: 260, y: 200, width: 70, height: 70))),
+            (page: 1, annotation: makeAnnotation(.link, bounds: CGRect(x: 80, y: 700, width: 160, height: 20))),
+            (page: 2, annotation: makeAnnotation(.ink, bounds: CGRect(x: 100, y: 100, width: 90, height: 40))),
+        ]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 3)
+    #expect(inspected.annotatedPages == [1, 3])
+    #expect(inspected.isCommented == true)
+}
+
+@Test("I-19 Session UUID recovery and invalid-subject tolerance")
+func i19_sessionUUIDRecoveryAndInvalidSubjectTolerance() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let validURL = paths.watchFolder.appendingPathComponent("valid-subject.pdf")
+    let invalidURL = paths.watchFolder.appendingPathComponent("invalid-subject.pdf")
+    let missingURL = paths.watchFolder.appendingPathComponent("missing-subject.pdf")
+
+    try makePDF(
+        at: validURL,
+        pageCount: 1,
+        creator: "Shotdeck",
+        subject: "22222222-2222-2222-2222-222222222222"
+    )
+    try makePDF(
+        at: invalidURL,
+        pageCount: 1,
+        creator: "Shotdeck",
+        subject: "not-a-uuid"
+    )
+    try makePDF(
+        at: missingURL,
+        pageCount: 1,
+        creator: "Shotdeck",
+        subject: nil
+    )
+
+    let valid = try AnnotationInspector.inspect(fileURL: validURL)
+    #expect(valid.sessionID == UUID(uuidString: "22222222-2222-2222-2222-222222222222"))
+    #expect(valid.pageCount == 1)
+    #expect(valid.annotatedPages == [])
+    #expect(valid.isCommented == false)
+
+    let invalid = try AnnotationInspector.inspect(fileURL: invalidURL)
+    #expect(invalid.sessionID == nil)
+    #expect(invalid.annotatedPages == [])
+    #expect(invalid.isCommented == false)
+
+    let missing = try AnnotationInspector.inspect(fileURL: missingURL)
+    #expect(missing.sessionID == nil)
+    #expect(missing.annotatedPages == [])
+    #expect(missing.isCommented == false)
+}
+
+@Test("I-19b Present non-Shotdeck creator beats a matching filename")
+func i19b_presentNonShotdeckCreatorBeatsMatchingFilename() throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134218.pdf")
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        creator: "Preview",
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+        ))]
+    )
+    let reopened = try #require(PDFDocument(url: pdfURL))
+    #expect(AnnotationInspector.isShotdeckDocument(reopened) == false)
+}
+
+private func expectSinglePageMark(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect,
+    contents: String? = nil,
+    fileName: String
+) throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent(fileName)
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        annotations: [(page: 0, annotation: makeAnnotation(subtype, bounds: bounds, contents: contents))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.pageCount == 1)
+    #expect(inspected.annotatedPages == [1])
+    #expect(inspected.isCommented == true)
+}
+
+private func expectSinglePageIgnored(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect,
+    fileName: String
+) throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let pdfURL = paths.watchFolder.appendingPathComponent(fileName)
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        annotations: [(page: 0, annotation: makeAnnotation(subtype, bounds: bounds))]
+    )
+    let inspected = try AnnotationInspector.inspect(fileURL: pdfURL)
+    #expect(inspected.annotatedPages == [])
+    #expect(inspected.isCommented == false)
+}

Tests/ShotdeckCoreTests/AtomicFileTests.swift

@@ -0,0 +1,178 @@
+import Foundation
+import Testing
+import ShotdeckCore
+
+@Test
+func atomicWriteProducesByteIdenticalFileAndLeavesNoTmp() throws {
+    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-write")
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let url = directory.appendingPathComponent("payload.bin")
+    let data = Data("shotdeck-durable-bytes".utf8)
+
+    try AtomicFile.write(data, to: url)
+
+    let onDisk = try Data(contentsOf: url)
+    #expect(onDisk == data)
+    #expect(!FileManager.default.fileExists(atPath: url.path + ".tmp"))
+}
+
+@Test
+func atomicWriteToTheSameURLTwiceKeepsTheSecondPayload() throws {
+    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-rewrite")
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let url = directory.appendingPathComponent("payload.bin")
+    let first = Data("first-pass".utf8)
+    let second = Data("second-pass-wins".utf8)
+
+    try AtomicFile.write(first, to: url)
+    try AtomicFile.write(second, to: url)
+
+    let onDisk = try Data(contentsOf: url)
+    #expect(onDisk == second)
+    #expect(!FileManager.default.fileExists(atPath: url.path + ".tmp"))
+}
+
+@Test
+func atomicWriteThrowsWhenParentDirectoryDoesNotExist() throws {
+    let missingParent = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-atomic-missing-\(UUID().uuidString)", isDirectory: true)
+    let url = missingParent.appendingPathComponent("payload.bin")
+    let data = Data("never-written".utf8)
+
+    let error = try #require(throws: ShotdeckError.self) {
+        try AtomicFile.write(data, to: url)
+    }
+    guard case .spoolWriteFailed(let path, _) = error else {
+        Issue.record("expected spoolWriteFailed, got \(error)")
+        return
+    }
+    #expect(path == url.path)
+    #expect(!FileManager.default.fileExists(atPath: url.path))
+}
+
+@Test
+func atomicWriteClearsAStaleTmpAndWritesTheNewPayload() throws {
+    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-stale-tmp")
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let url = directory.appendingPathComponent("payload.bin")
+    let tmpURL = directory.appendingPathComponent(url.lastPathComponent + ".tmp")
+    let garbage = Data("stale-crash-garbage".utf8)
+    let newData = Data("recovered-payload".utf8)
+
+    try garbage.write(to: tmpURL)
+    #expect(FileManager.default.fileExists(atPath: tmpURL.path))
+
+    try AtomicFile.write(newData, to: url)
+
+    let onDisk = try Data(contentsOf: url)
+    #expect(onDisk == newData)
+    #expect(!FileManager.default.fileExists(atPath: tmpURL.path))
+}
+
+@Test
+func writeJSONSortsKeysPrettyPrintsAndEncodesDatesAsISO8601() throws {
+    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-json-format")
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let url = directory.appendingPathComponent("session.json")
+    let date = try iso8601Date(year: 2026, month: 8, day: 30, hour: 9, minute: 42, second: 5)
+    let value = JSONProbe(zebra: "last", apple: 7, capturedAt: date)
+
+    try AtomicFile.writeJSON(value, to: url)
+
+    let raw = try Data(contentsOf: url)
+    let text = try #require(String(data: raw, encoding: .utf8))
+
+    let apple = try #require(text.range(of: "\"apple\""))
+    let capturedAt = try #require(text.range(of: "\"capturedAt\""))
+    let zebra = try #require(text.range(of: "\"zebra\""))
+    #expect(apple.lowerBound < capturedAt.lowerBound)
+    #expect(capturedAt.lowerBound < zebra.lowerBound)
+    #expect(text.contains("\n"))
+    #expect(text.contains("  \"apple\""))
+    #expect(text.contains("2026-08-30T09:42:05Z"))
+    #expect(!text.contains("\(date.timeIntervalSinceReferenceDate)"))
+    #expect(!FileManager.default.fileExists(atPath: url.path + ".tmp"))
+}
+
+@Test
+func writeJSONRoundTripsThroughISO8601Decoder() throws {
+    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-json-roundtrip")
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    let url = directory.appendingPathComponent("session.json")
+    let date = try iso8601Date(year: 2026, month: 8, day: 31, hour: 13, minute: 5, second: 9)
+    let original = JSONProbe(zebra: "keep", apple: 42, capturedAt: date)
+
+    try AtomicFile.writeJSON(original, to: url)
+
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    let decoded = try decoder.decode(JSONProbe.self, from: Data(contentsOf: url))
+    #expect(decoded == original)
+}
+
+@Test
+func fsyncDirectorySucceedsOnADirectoryAndThrowsOnMissingOrFilePaths() throws {
+    let directory = try makeTemporaryDirectory(prefix: "shotdeck-atomic-fsync-dir")
+    defer { try? FileManager.default.removeItem(at: directory) }
+
+    try AtomicFile.fsyncDirectory(at: directory)
+
+    let missing = directory.appendingPathComponent("does-not-exist", isDirectory: true)
+    let missingError = try #require(throws: ShotdeckError.self) {
+        try AtomicFile.fsyncDirectory(at: missing)
+    }
+    guard case .spoolWriteFailed = missingError else {
+        Issue.record("expected spoolWriteFailed for a missing path, got \(missingError)")
+        return
+    }
+
+    let fileURL = directory.appendingPathComponent("not-a-directory.bin")
+    try AtomicFile.write(Data("file".utf8), to: fileURL)
+    let fileError = try #require(throws: ShotdeckError.self) {
+        try AtomicFile.fsyncDirectory(at: fileURL)
+    }
+    guard case .spoolWriteFailed = fileError else {
+        Issue.record("expected spoolWriteFailed for a file path, got \(fileError)")
+        return
+    }
+}
+
+private struct JSONProbe: Codable, Equatable {
+    var zebra: String
+    var apple: Int
+    var capturedAt: Date
+}
+
+private func makeTemporaryDirectory(prefix: String) throws -> URL {
+    let url = FileManager.default.temporaryDirectory
+        .appendingPathComponent("\(prefix)-\(UUID().uuidString)", isDirectory: true)
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+    return url
+}
+
+private func iso8601Date(
+    year: Int,
+    month: Int,
+    day: Int,
+    hour: Int,
+    minute: Int,
+    second: Int
+) throws -> Date {
+    var calendar = Calendar(identifier: .gregorian)
+    calendar.timeZone = try #require(TimeZone(secondsFromGMT: 0))
+    return try #require(
+        calendar.date(from: DateComponents(
+            year: year,
+            month: month,
+            day: day,
+            hour: hour,
+            minute: minute,
+            second: second
+        ))
+    )
+}

Tests/ShotdeckCoreTests/CaptureRegionTests.swift

@@ -0,0 +1,171 @@
+import Carbon.HIToolbox
+import Foundation
+import Testing
+@testable import ShotdeckCore
+
+@Test("GEO-1 primary-only 1080-tall screen, AppKit rect (100,100,400,300)")
+func geo1_primaryOnlyAppKitRectConvertsToExpectedCGRect() {
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 100, y: 100, width: 400, height: 300),
+        displayID: 1,
+        capturedScale: 2,
+        primaryHeight: 1080
+    )
+    #expect(region.rect == CGRect(x: 100, y: 680, width: 400, height: 300))
+}
+
+@Test("GEO-2 rect flush to AppKit bottom (y=0), h=300, primaryHeight=1080")
+func geo2_flushToAppKitBottomYieldsCGY780() {
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 50, y: 0, width: 200, height: 300),
+        displayID: 1,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect.origin.y == 780)
+}
+
+@Test("GEO-3 rect flush to AppKit top (y+h=primaryHeight), primaryHeight=1080, h=300")
+func geo3_flushToAppKitTopYieldsCGY0() {
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 50, y: 780, width: 200, height: 300),
+        displayID: 1,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect.origin.y == 0)
+}
+
+@Test("GEO-4 round-trip AppKit→CG via injectable overload, then invert recovers original")
+func geo4_invertRecoverOriginalAppKitRect() {
+    let original = CGRect(x: 100, y: 100, width: 400, height: 300)
+    let primaryHeight: CGFloat = 1080
+    let region = CaptureRegion.fromAppKit(
+        rect: original,
+        displayID: 1,
+        capturedScale: 2,
+        primaryHeight: primaryHeight
+    )
+    let appKitY = primaryHeight - region.rect.origin.y - region.rect.height
+    let recovered = CGRect(
+        x: region.rect.origin.x,
+        y: appKitY,
+        width: region.rect.width,
+        height: region.rect.height
+    )
+    #expect(recovered == original)
+}
+
+@Test("GEO-5 isStillValid for displayID 999_999 is false and does not trap")
+func geo5_unknownDisplayIsNotStillValid() {
+    let region = CaptureRegion(
+        displayID: 999_999,
+        rect: CGRect(x: 0, y: 0, width: 100, height: 100),
+        capturedScale: 1
+    )
+    #expect(region.isStillValid == false)
+}
+
+@Test("GEO-6 CaptureRegion JSONEncoder→JSONDecoder round-trip equals original")
+func geo6_codableRoundTripEqualsOriginal() throws {
+    let original = CaptureRegion(
+        displayID: 42,
+        rect: CGRect(x: 10, y: 20, width: 300, height: 400),
+        capturedScale: 2
+    )
+    let data = try JSONEncoder().encode(original)
+    let decoded = try JSONDecoder().decode(CaptureRegion.self, from: data)
+    #expect(decoded == original)
+}
+
+@Test("GEO-7 secondary screen negative x: AppKit (−1800,200,500,400) → CG (−1800,480,500,400)")
+func geo7_secondaryNegativeXLeavesXUnchanged() {
+    // Secondary AppKit frame (−1920, 0, 1920, 1080); primaryHeight=1080.
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: -1800, y: 200, width: 500, height: 400),
+        displayID: 2,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect == CGRect(x: -1800, y: 480, width: 500, height: 400))
+}
+
+@Test("GEO-8 secondary screen stacked above primary: AppKit (300,1300,600,350) → CG (300,−570,600,350)")
+func geo8_secondaryPositiveYProducesNegativeCGY() {
+    // Secondary AppKit frame (0, 1080, 1920, 1080); primaryHeight=1080.
+    let region = CaptureRegion.fromAppKit(
+        rect: CGRect(x: 300, y: 1300, width: 600, height: 350),
+        displayID: 2,
+        capturedScale: 1,
+        primaryHeight: 1080
+    )
+    #expect(region.rect == CGRect(x: 300, y: -570, width: 600, height: 350))
+}
+
+/// Carbon registrations are process-wide, so these cases must not run in parallel.
+@Suite(.serialized)
+@MainActor
+struct HotkeyCenterCarbonTests {
+    /// kVK_ANSI_2. The app registers this combo once (WP-4a); tests only exercise the registrar.
+    private let captureKeyCode: UInt32 = 19
+    private let captureModifiers = UInt32(optionKey) | UInt32(shiftKey)
+
+    @Test("HK-1 register id a with Option-Shift-2 returns true")
+    func hk1_registerReturnsTrue() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let ok = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        if !ok {
+            Issue.record("HK-1: RegisterEventHotKey returned non-noErr inside swift test (no NSApplication). Carbon registration did not function headlessly.")
+            return
+        }
+        #expect(ok)
+    }
+
+    @Test("HK-2 register same combo under a different id returns false")
+    func hk2_duplicateComboRejected() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let first = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        if !first {
+            Issue.record("HK-2: first RegisterEventHotKey failed inside swift test (no NSApplication); cannot evaluate duplicate-combo rejection.")
+            return
+        }
+        let second = center.register(id: "b", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        #expect(second == false)
+    }
+
+    @Test("HK-3 unregister frees the combination so a later register succeeds")
+    func hk3_unregisterFreesCombination() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let first = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        if !first {
+            Issue.record("HK-3: first RegisterEventHotKey failed inside swift test (no NSApplication); cannot evaluate unregister.")
+            return
+        }
+        center.unregister(id: "a")
+        let again = center.register(id: "c", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        #expect(again)
+    }
+
+    @Test("HK-4 unregisterAll frees combinations so a later register succeeds")
+    func hk4_unregisterAllFreesCombinations() {
+        let center = HotkeyCenter()
+        defer { center.unregisterAll() }
+        let first = center.register(id: "a", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        let other = center.register(
+            id: "other",
+            keyCode: UInt32(kVK_ANSI_3),
+            modifiers: captureModifiers
+        ) {}
+        if !first {
+            Issue.record("HK-4: RegisterEventHotKey failed inside swift test (no NSApplication); cannot evaluate unregisterAll.")
+            return
+        }
+        _ = other
+        center.unregisterAll()
+        let again = center.register(id: "c", keyCode: captureKeyCode, modifiers: captureModifiers) {}
+        #expect(again)
+    }
+}

Tests/ShotdeckCoreTests/FolderSettingsTests.swift

@@ -0,0 +1,168 @@
+import Foundation
+import Testing
+import ShotdeckCore
+
+@Test
+func resolveWithoutStoredKeysReturnsDesktopAndDownloads() throws {
+    let suite = try makeDefaultsSuite()
+    defer { tearDown(suite) }
+
+    let resolved = FolderSettings.resolve(defaults: suite.defaults)
+    let expectedOutbox = try #require(
+        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
+    )
+    let expectedWatch = try #require(
+        FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
+    )
+
+    #expect(resolved.outbox.path == expectedOutbox.path)
+    #expect(resolved.watch.path == expectedWatch.path)
+}
+
+@Test
+func setOutboxToAnExistingDirectoryIsReturnedByResolve() throws {
+    let suite = try makeDefaultsSuite()
+    defer { tearDown(suite) }
+    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-outbox-set")
+    defer { try? FileManager.default.removeItem(at: outbox) }
+
+    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
+    let resolved = FolderSettings.resolve(defaults: suite.defaults)
+    let expectedWatch = try #require(
+        FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
+    )
+
+    #expect(resolved.outbox.path == outbox.path)
+    #expect(resolved.watch.path == expectedWatch.path)
+    #expect(FolderSettings.storedOutboxPath(defaults: suite.defaults) == outbox.path)
+}
+
+@Test
+func resolveFallsBackWhenTheStoredOutboxDirectoryIsGone() throws {
+    let suite = try makeDefaultsSuite()
+    defer { tearDown(suite) }
+    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-outbox-gone")
+
+    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
+    try FileManager.default.removeItem(at: outbox)
+
+    let resolved = FolderSettings.resolve(defaults: suite.defaults)
+    let expectedOutbox = try #require(
+        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
+    )
+    #expect(resolved.outbox.path == expectedOutbox.path)
+}
+
+@Test
+func setWatchFolderMirrorsOutboxOverrideAndFallbackIndependently() throws {
+    let suite = try makeDefaultsSuite()
+    defer { tearDown(suite) }
+    let watch = try makeTemporaryDirectory(prefix: "shotdeck-watch-set")
+    let expectedOutbox = try #require(
+        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
+    )
+
+    FolderSettings.setWatchFolder(watch, defaults: suite.defaults)
+    let withOverride = FolderSettings.resolve(defaults: suite.defaults)
+    #expect(withOverride.watch.path == watch.path)
+    #expect(withOverride.outbox.path == expectedOutbox.path)
+
+    try FileManager.default.removeItem(at: watch)
+    let afterDelete = FolderSettings.resolve(defaults: suite.defaults)
+    let expectedWatch = try #require(
+        FileManager.default.urls(for: .downloadsDirectory, in: .userDomainMask).first
+    )
+    #expect(afterDelete.watch.path == expectedWatch.path)
+    #expect(afterDelete.outbox.path == expectedOutbox.path)
+}
+
+@Test
+func resetOutboxClearsTheOverride() throws {
+    let suite = try makeDefaultsSuite()
+    defer { tearDown(suite) }
+    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-outbox-reset")
+    defer { try? FileManager.default.removeItem(at: outbox) }
+
+    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
+    FolderSettings.resetOutbox(defaults: suite.defaults)
+
+    let resolved = FolderSettings.resolve(defaults: suite.defaults)
+    let expectedOutbox = try #require(
+        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
+    )
+    #expect(resolved.outbox.path == expectedOutbox.path)
+    #expect(FolderSettings.storedOutboxPath(defaults: suite.defaults) == nil)
+}
+
+@Test
+func resolvedAppSupportPathsUsesTheOutboxOverrideAndCreatesSpoolArchive() throws {
+    let suite = try makeDefaultsSuite()
+    defer { tearDown(suite) }
+    let root = try makeTemporaryDirectory(prefix: "shotdeck-paths-root")
+    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-paths-outbox")
+    defer {
+        try? FileManager.default.removeItem(at: root)
+        try? FileManager.default.removeItem(at: outbox)
+    }
+
+    FolderSettings.setOutbox(outbox, defaults: suite.defaults)
+    let paths = try FolderSettings.resolvedAppSupportPaths(root: root, defaults: suite.defaults)
+
+    #expect(paths.outbox.path == outbox.path)
+    #expect(directoryExists(paths.spool))
+    #expect(directoryExists(paths.archive))
+    #expect(paths.spool.deletingLastPathComponent().path == root.path)
+    #expect(paths.archive.deletingLastPathComponent().path == root.path)
+}
+
+@Test
+func userDefaultsSuitesDoNotLeakFolderOverrides() throws {
+    let suiteA = try makeDefaultsSuite()
+    let suiteB = try makeDefaultsSuite()
+    defer {
+        tearDown(suiteA)
+        tearDown(suiteB)
+    }
+    let outbox = try makeTemporaryDirectory(prefix: "shotdeck-suite-a-outbox")
+    defer { try? FileManager.default.removeItem(at: outbox) }
+
+    FolderSettings.setOutbox(outbox, defaults: suiteA.defaults)
+
+    let resolvedA = FolderSettings.resolve(defaults: suiteA.defaults)
+    let resolvedB = FolderSettings.resolve(defaults: suiteB.defaults)
+    let expectedOutbox = try #require(
+        FileManager.default.urls(for: .desktopDirectory, in: .userDomainMask).first
+    )
+
+    #expect(resolvedA.outbox.path == outbox.path)
+    #expect(resolvedB.outbox.path == expectedOutbox.path)
+}
+
+private struct DefaultsSuite {
+    let name: String
+    let defaults: UserDefaults
+}
+
+private func makeDefaultsSuite() throws -> DefaultsSuite {
+    let name = "shotdeck-test-\(UUID().uuidString)"
+    let defaults = try #require(UserDefaults(suiteName: name))
+    defaults.removePersistentDomain(forName: name)
+    return DefaultsSuite(name: name, defaults: defaults)
+}
+
+private func tearDown(_ suite: DefaultsSuite) {
+    suite.defaults.removePersistentDomain(forName: suite.name)
+}
+
+private func makeTemporaryDirectory(prefix: String) throws -> URL {
+    let url = FileManager.default.temporaryDirectory
+        .appendingPathComponent("\(prefix)-\(UUID().uuidString)", isDirectory: true)
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+    return url
+}
+
+private func directoryExists(_ url: URL) -> Bool {
+    var isDirectory: ObjCBool = false
+    let exists = FileManager.default.fileExists(atPath: url.path, isDirectory: &isDirectory)
+    return exists && isDirectory.boolValue
+}

Tests/ShotdeckCoreTests/ReturnLedgerTests.swift

@@ -0,0 +1,200 @@
+import Foundation
+import Testing
+import ShotdeckCore
+
+private func makeCasePaths() throws -> (paths: AppSupportPaths, cleanup: URL) {
+    let cleanup = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-wp5a-ledger-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: cleanup.appendingPathComponent("root", isDirectory: true),
+        outbox: cleanup.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: cleanup.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (paths, cleanup)
+}
+
+private func document(
+    path: String,
+    annotatedPages: [Int],
+    detectedAt: Date,
+    sessionID: UUID? = nil,
+    pageCount: Int = 1
+) -> ReturnedDocument {
+    ReturnedDocument(
+        fileURL: URL(fileURLWithPath: path),
+        sessionID: sessionID,
+        pageCount: pageCount,
+        annotatedPages: annotatedPages,
+        detectedAt: detectedAt
+    )
+}
+
+@Test("L-1 commented() returns only commented entries, newest first")
+func l1_commentedReturnsOnlyCommentedNewestFirst() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let newer = document(
+        path: "/tmp/shotdeck-returns/newer.pdf",
+        annotatedPages: [1, 2],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_200)
+    )
+    let older = document(
+        path: "/tmp/shotdeck-returns/older.pdf",
+        annotatedPages: [3],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_100)
+    )
+    let clean = document(
+        path: "/tmp/shotdeck-returns/clean.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_300)
+    )
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(older)
+    try await ledger.record(newer)
+    try await ledger.record(clean)
+
+    let commented = try await ledger.commented()
+    #expect(commented.map(\.fileURL) == [newer.fileURL, older.fileURL])
+    #expect(commented.map(\.annotatedPages) == [[1, 2], [3]])
+}
+
+@Test("L-2 clipboardText() exact format")
+func l2_clipboardTextExactFormat() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let newer = document(
+        path: "/tmp/shotdeck-returns/newer.pdf",
+        annotatedPages: [1, 2],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_200)
+    )
+    let older = document(
+        path: "/tmp/shotdeck-returns/older.pdf",
+        annotatedPages: [3],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_100)
+    )
+    let clean = document(
+        path: "/tmp/shotdeck-returns/clean.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_300)
+    )
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(older)
+    try await ledger.record(newer)
+    try await ledger.record(clean)
+
+    let text = try await ledger.clipboardText()
+    #expect(text == newer.fileURL.path + "\n" + older.fileURL.path)
+    #expect(text.hasSuffix("\n") == false)
+}
+
+@Test("L-3 Re-recording the same URL upserts")
+func l3_rerecordingTheSameURLUpserts() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let url = URL(fileURLWithPath: "/tmp/shotdeck-returns/same.pdf")
+    let first = ReturnedDocument(
+        fileURL: url,
+        sessionID: nil,
+        pageCount: 1,
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_400)
+    )
+    let second = ReturnedDocument(
+        fileURL: url,
+        sessionID: UUID(uuidString: "11111111-1111-1111-1111-111111111111"),
+        pageCount: 1,
+        annotatedPages: [1],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_100)
+    )
+
+    let ledger = try ReturnLedger(paths: paths)
+    try await ledger.record(first)
+    try await ledger.record(second)
+
+    let all = try await ledger.all()
+    #expect(all.count == 1)
+    #expect(all[0].fileURL == url)
+    #expect(all[0].annotatedPages == [1])
+    #expect(all[0].isCommented == true)
+    #expect(all[0].sessionID == UUID(uuidString: "11111111-1111-1111-1111-111111111111"))
+}
+
+@Test("L-4 clipboardText() throws when nothing is commented")
+func l4_clipboardTextThrowsWhenNothingIsCommented() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let emptyError = try await #require(throws: ShotdeckError.self) {
+        try await ledger.clipboardText()
+    }
+    guard case .noCommentedReturns = emptyError else {
+        Issue.record("expected noCommentedReturns on an empty ledger, got \(emptyError)")
+        return
+    }
+
+    try await ledger.record(document(
+        path: "/tmp/shotdeck-returns/clean-only.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_500)
+    ))
+    let cleanError = try await #require(throws: ShotdeckError.self) {
+        try await ledger.clipboardText()
+    }
+    guard case .noCommentedReturns = cleanError else {
+        Issue.record("expected noCommentedReturns with only clean returns, got \(cleanError)")
+        return
+    }
+}
+
+@Test("L-5 Ledger survives reopening from disk")
+func l5_ledgerSurvivesReopeningFromDisk() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let first = document(
+        path: "/tmp/shotdeck-returns/a.pdf",
+        annotatedPages: [1],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_700),
+        sessionID: UUID(uuidString: "11111111-1111-1111-1111-111111111111")
+    )
+    let second = document(
+        path: "/tmp/shotdeck-returns/b.pdf",
+        annotatedPages: [],
+        detectedAt: Date(timeIntervalSince1970: 1_777_000_600)
+    )
+
+    do {
+        let ledger = try ReturnLedger(paths: paths)
+        try await ledger.record(first)
+        try await ledger.record(second)
+    }
+
+    let reopened = try ReturnLedger(paths: paths)
+    let all = try await reopened.all()
+    #expect(all == [first, second])
+}
+
+@Test("L-6 Corrupt returns.json is renamed and the ledger starts empty")
+func l6_corruptReturnsJSONIsRenamedAndStartsEmpty() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let returnsURL = paths.root.appendingPathComponent("returns.json")
+    try Data("{not-json".utf8).write(to: returnsURL)
+    #expect(FileManager.default.fileExists(atPath: returnsURL.path))
+
+    let ledger = try ReturnLedger(paths: paths)
+    #expect(try await ledger.all() == [])
+    #expect(FileManager.default.fileExists(atPath: returnsURL.path) == false)
+
+    let names = try FileManager.default.contentsOfDirectory(atPath: paths.root.path)
+    let corrupt = names.filter { $0.hasPrefix("returns.json.corrupt-") }
+    #expect(corrupt.count == 1)
+    #expect(corrupt[0].contains(DubaiTime.fileStamp(Date()).prefix(8)))
+}

Tests/ShotdeckCoreTests/ReturnWatcherTests.swift

@@ -0,0 +1,173 @@
+import AppKit
+import Foundation
+import PDFKit
+import Testing
+import ShotdeckCore
+
+private let pageBounds = CGRect(x: 0, y: 0, width: 600, height: 800)
+
+private func makeAnnotation(
+    _ subtype: PDFAnnotationSubtype,
+    bounds: CGRect = CGRect(x: 100, y: 100, width: 80, height: 40),
+    contents: String? = nil
+) -> PDFAnnotation {
+    let annotation = PDFAnnotation(
+        bounds: bounds,
+        forType: subtype,
+        withProperties: nil
+    )
+    annotation.contents = contents
+    return annotation
+}
+
+private func makePDF(
+    at url: URL,
+    pageCount: Int,
+    creator: String? = "Shotdeck",
+    subject: String? = nil,
+    annotations: [(page: Int, annotation: PDFAnnotation)] = []
+) throws {
+    let document = PDFDocument()
+    for index in 0..<pageCount {
+        let page = PDFPage()
+        page.setBounds(pageBounds, for: .mediaBox)
+        document.insert(page, at: index)
+    }
+
+    var attributes = [PDFDocumentAttribute: Any]()
+    if let creator { attributes[.creatorAttribute] = creator }
+    if let subject { attributes[.subjectAttribute] = subject }
+    document.documentAttributes = attributes
+
+    for item in annotations {
+        guard let page = document.page(at: item.page) else {
+            throw NSError(domain: "WP5Test", code: 1)
+        }
+        page.addAnnotation(item.annotation)
+    }
+
+    guard document.write(to: url) else {
+        throw NSError(domain: "WP5Test", code: 2)
+    }
+}
+
+private func makeCasePaths() throws -> (paths: AppSupportPaths, cleanup: URL) {
+    let cleanup = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-wp5b-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: cleanup.appendingPathComponent("root", isDirectory: true),
+        outbox: cleanup.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: cleanup.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (paths, cleanup)
+}
+
+/// Guards `confirmation(expectedCount: 1)` against a create+rename double-event.
+private final class ConfirmOnce: @unchecked Sendable {
+    private let lock = NSLock()
+    private var fired = false
+    func run(_ body: () -> Void) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard !fired else { return }
+        fired = true
+        body()
+    }
+}
+
+@Test("W-25 Duplicate-name suffix is the normal AirDrop return (scanNow)")
+func w25_duplicateNameSuffixIsRecognizedByScanNow() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let watcher = ReturnWatcher(paths: paths, ledger: ledger)
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134205 2.pdf")
+
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        creator: nil,
+        subject: "33333333-3333-3333-3333-333333333333",
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+        ))]
+    )
+
+    let found = try await watcher.scanNow()
+    #expect(found.count == 1)
+    let doc = try #require(found.first)
+    #expect(doc.fileURL.lastPathComponent == "Shotdeck-20260830-134205 2.pdf")
+    #expect(doc.fileURL.resolvingSymlinksInPath().path == pdfURL.resolvingSymlinksInPath().path)
+    #expect(doc.pageCount == 1)
+    #expect(doc.annotatedPages == [1])
+    #expect(doc.isCommented == true)
+
+    let commented = try await ledger.commented()
+    #expect(commented.count == 1)
+    #expect(commented[0].fileURL.lastPathComponent == pdfURL.lastPathComponent)
+    #expect(commented[0].fileURL.resolvingSymlinksInPath().path == pdfURL.resolvingSymlinksInPath().path)
+}
+
+@Test("W-26 Creator provenance negative at the scan level")
+func w26_presentNonShotdeckCreatorIsIgnoredByScanNow() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let watcher = ReturnWatcher(paths: paths, ledger: ledger)
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-134218.pdf")
+
+    try makePDF(
+        at: pdfURL,
+        pageCount: 1,
+        creator: "Preview",
+        annotations: [(page: 0, annotation: makeAnnotation(
+            .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+        ))]
+    )
+
+    let found = try await watcher.scanNow()
+    #expect(found.isEmpty)
+    let all = try await ledger.all()
+    #expect(all.isEmpty)
+}
+
+@Test("W-27 FSEvents live callback fires on a real file arrival")
+func w27_fsEventsCallbackFiresOnRealArrival() async throws {
+    let (paths, cleanup) = try makeCasePaths()
+    defer { try? FileManager.default.removeItem(at: cleanup) }
+
+    let ledger = try ReturnLedger(paths: paths)
+    let watcher = ReturnWatcher(paths: paths, ledger: ledger)
+    let pdfURL = paths.watchFolder.appendingPathComponent("Shotdeck-20260830-140000.pdf")
+    let once = ConfirmOnce()
+
+    try await confirmation("watcher reports the arrived PDF", expectedCount: 1) { confirm in
+        do {
+            try await watcher.start { docs in
+                if docs.contains(where: { $0.fileURL.lastPathComponent == pdfURL.lastPathComponent }) {
+                    once.run { confirm() }
+                }
+            }
+            // Simulate AirDrop's own write-then-rename so the watcher must survive that pattern.
+            let tmpURL = pdfURL.appendingPathExtension("inprogress")
+            try makePDF(
+                at: tmpURL, pageCount: 1, creator: "Shotdeck",
+                annotations: [(page: 0, annotation: makeAnnotation(
+                    .ink, bounds: CGRect(x: 100, y: 100, width: 120, height: 50)
+                ))]
+            )
+            try FileManager.default.moveItem(at: tmpURL, to: pdfURL)
+        } catch {
+            print("fsEventsCallbackFiresOnRealArrival error: \(error)")
+            await watcher.stop()
+            throw error
+        }
+        // Budget: 400ms debounce + FS latency + the 250ms stability re-read + PDFKit open.
+        // 5s is a generous, fixed ceiling — never a "some time" wait.
+        try await Task.sleep(for: .seconds(5))
+        await watcher.stop()
+        await watcher.stop()
+    }
+}