WP-1: durable SpoolStore with crash reconciliation and removed/ per SPEC-A1a

.gitignore

@@ -0,0 +1,8 @@
+.build/
+.swiftpm/
+Packages/
+*.xcodeproj
+xcuserdata/
+DerivedData/
+.DS_Store
+.netrc

Info.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleIdentifier</key>
+	<string>ai.flowmaster.shotdeck</string>
+	<key>CFBundleName</key>
+	<string>Shotdeck</string>
+	<key>CFBundleExecutable</key>
+	<string>Shotdeck</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>0.1.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>LSUIElement</key>
+	<true/>
+	<key>LSMinimumSystemVersion</key>
+	<string>14.0</string>
+	<key>NSHumanReadableCopyright</key>
+	<string>Copyright © 2026 Flowmaster FZC LLC. All rights reserved.</string>
+</dict>
+</plist>

Package.swift

@@ -0,0 +1,31 @@
+// swift-tools-version: 6.0
+
+import PackageDescription
+
+let package = Package(
+    name: "Shotdeck",
+    platforms: [
+        .macOS(.v14),
+    ],
+    products: [
+        .library(name: "ShotdeckCore", targets: ["ShotdeckCore"]),
+        .executable(name: "Shotdeck", targets: ["Shotdeck"]),
+    ],
+    dependencies: [],
+    targets: [
+        .target(
+            name: "ShotdeckCore",
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+        .executableTarget(
+            name: "Shotdeck",
+            dependencies: ["ShotdeckCore"],
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+        .testTarget(
+            name: "ShotdeckCoreTests",
+            dependencies: ["ShotdeckCore"],
+            swiftSettings: [.swiftLanguageMode(.v6)]
+        ),
+    ]
+)

README.md

@@ -1,3 +1,22 @@
-# shotdeck
+# Shotdeck
 
-macOS menu-bar app: hotkey region capture into a review PDF with PASS/FAIL boxes, AirDrop send, annotation-return tracking
+A macOS menu-bar app that captures a remembered screen region, builds a one-screenshot-per-page PDF, AirDrops it to an iPad for markup, then watches for the annotated file to come back.
+
+## Hotkeys
+
+- **⌥⇧1** — pick a new region, then capture it.
+- **⌥⇧2** — capture the remembered region instantly (no picker).
+
+## Screen Recording permission
+
+On first launch macOS asks once for Screen Recording. Grant it at **System Settings > Privacy & Security > Screen Recording**. You never have to do this again as long as the app is not re-signed with a different identity.
+
+The grant is bound to the bundle identifier `ai.flowmaster.shotdeck` plus the code signature. Changing either one forces a fresh prompt.
+
+## Build
+
+```bash
+swift build && swift test
+./scripts/build-app.sh          # signed .app for daily use
+open .build/Shotdeck.app
+```

Sources/Shotdeck/main.swift

@@ -0,0 +1,6 @@
+import AppKit
+
+// WP-4 replaces this body with the real menu-bar UI.
+let application = NSApplication.shared
+application.setActivationPolicy(.accessory)
+application.run()

Sources/ShotdeckCore/Model/Capture.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+/// One screenshot plus everything needed to place it on a PDF page.
+public struct Capture: Codable, Sendable, Identifiable, Equatable {
+    public let id: UUID
+    /// 1-based position within its session. Stable; never renumbered on delete.
+    public let sequence: Int
+    /// File name only (e.g. "001-A1B2C3D4.png"), never a path.
+    /// The directory is always the owning session's directory.
+    public let fileName: String
+    /// Pixel dimensions of the PNG on disk.
+    public let pixelWidth: Int
+    public let pixelHeight: Int
+    /// Backing scale the capture was taken at (2.0 on Retina). Needed so the PDF
+    /// composer lays the image out at its true point size, not its pixel size.
+    public let scale: CGFloat
+    /// When the screenshot was taken. Always stored as an absolute instant;
+    /// rendered in Asia/Dubai wherever a human sees it.
+    public let capturedAt: Date
+
+    public init(
+        id: UUID,
+        sequence: Int,
+        fileName: String,
+        pixelWidth: Int,
+        pixelHeight: Int,
+        scale: CGFloat,
+        capturedAt: Date
+    ) {
+        self.id = id
+        self.sequence = sequence
+        self.fileName = fileName
+        self.pixelWidth = pixelWidth
+        self.pixelHeight = pixelHeight
+        self.scale = scale
+        self.capturedAt = capturedAt
+    }
+
+    /// True when the image is wider than it is tall. Drives page orientation.
+    public var isLandscape: Bool {
+        pixelWidth > pixelHeight
+    }
+}

Sources/ShotdeckCore/Model/CaptureSession.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+public enum SessionState: String, Codable, Sendable {
+    case open      // accepting captures
+    case archived  // its PDF has been built and sent; kept forever, never deleted
+}
+
+/// The manifest persisted as session.json alongside the PNGs.
+public struct CaptureSession: Codable, Sendable, Identifiable, Equatable {
+    public let id: UUID
+    public let createdAt: Date
+    public private(set) var state: SessionState
+    public private(set) var captures: [Capture]
+    /// Set when the PDF is built, so a re-send reuses the same file.
+    public private(set) var pdfFileName: String?
+
+    public init(
+        id: UUID,
+        createdAt: Date,
+        state: SessionState,
+        captures: [Capture],
+        pdfFileName: String?
+    ) {
+        self.id = id
+        self.createdAt = createdAt
+        self.state = state
+        self.captures = captures
+        self.pdfFileName = pdfFileName
+    }
+
+    public var isEmpty: Bool {
+        captures.isEmpty
+    }
+
+    /// max(sequence)+1, or 1 when empty.
+    public var nextSequence: Int {
+        (captures.map(\.sequence).max() ?? 0) + 1
+    }
+
+    /// Value-semantic: returns a new session; does not mutate `self`.
+    public func appending(_ capture: Capture) -> CaptureSession {
+        CaptureSession(
+            id: id,
+            createdAt: createdAt,
+            state: state,
+            captures: captures + [capture],
+            pdfFileName: pdfFileName
+        )
+    }
+
+    /// Value-semantic: returns a new session; does not mutate `self`.
+    /// Sequence numbers of remaining captures are left unchanged.
+    public func removing(captureID: UUID) -> CaptureSession {
+        CaptureSession(
+            id: id,
+            createdAt: createdAt,
+            state: state,
+            captures: captures.filter { $0.id != captureID },
+            pdfFileName: pdfFileName
+        )
+    }
+
+    /// Value-semantic: returns a new session; does not mutate `self`.
+    public func markArchived(pdfFileName: String) -> CaptureSession {
+        CaptureSession(
+            id: id,
+            createdAt: createdAt,
+            state: .archived,
+            captures: captures,
+            pdfFileName: pdfFileName
+        )
+    }
+}

Sources/ShotdeckCore/Model/ShotdeckError.swift

@@ -0,0 +1,36 @@
+import Foundation
+
+public enum ShotdeckError: Error, LocalizedError, Sendable {
+    case screenRecordingNotGranted
+    case noRegionRemembered
+    case displayNoLongerConnected(displayID: UInt32)
+    case captureFailed(underlying: String)
+    case spoolWriteFailed(path: String, underlying: String)
+    case manifestCorrupt(path: String)
+    case pdfCompositionFailed(reason: String)
+    case airDropUnavailable
+    case noCommentedReturns
+
+    public var errorDescription: String? {
+        switch self {
+        case .screenRecordingNotGranted:
+            return "Screen Recording is turned off. Grant it in System Settings to capture."
+        case .noRegionRemembered:
+            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):
+            return "The screenshot could not be taken. \(underlying)"
+        case .spoolWriteFailed(_, let underlying):
+            return "The screenshot could not be saved. \(underlying)"
+        case .manifestCorrupt:
+            return "This session's file is damaged and cannot be opened."
+        case .pdfCompositionFailed(let reason):
+            return "The PDF could not be built. \(reason)"
+        case .airDropUnavailable:
+            return "AirDrop is not available right now."
+        case .noCommentedReturns:
+            return "None of the returned PDFs have comments on them."
+        }
+    }
+}

Sources/ShotdeckCore/Spool/SpoolStore.swift

@@ -0,0 +1,418 @@
+import Foundation
+import ImageIO
+import CoreGraphics
+import Darwin
+
+public actor SpoolStore {
+    private let paths: AppSupportPaths
+    private var openSession: CaptureSession
+
+    public init(paths: AppSupportPaths) throws {
+        self.paths = paths
+        let fm = FileManager.default
+        try Self.supersedeSpoolArchiveOverlaps(paths: paths, fileManager: fm)
+        try Self.finishInterruptedArchives(paths: paths, fileManager: fm)
+        let remainingIDs = try Self.listUUIDDirectories(in: paths.spool, fileManager: fm)
+        if remainingIDs.isEmpty {
+            self.openSession = try Self.createFreshSession(paths: paths)
+        } else {
+            var candidates: [CaptureSession] = []
+            for id in remainingIDs {
+                let dir = paths.sessionDirectory(id)
+                candidates.append(
+                    try Self.reconcileSessionDirectory(
+                        at: dir, id: id, assumedStateIfRebuilt: .open, fileManager: fm))
+            }
+            self.openSession = Self.pickNewest(first: candidates[0], rest: Array(candidates.dropFirst()))
+        }
+    }
+
+    /// The session currently accepting captures. Cheap accessor — all reconciliation already
+    /// happened once, inside init.
+    public func currentSession() throws -> CaptureSession {
+        openSession
+    }
+
+    /// Writes `pngData` to disk and fsyncs it BEFORE the manifest is touched, then updates and
+    /// durably writes the manifest. Order is non-negotiable: image durable -> manifest durable
+    /// -> return. Uses AtomicFile.write/writeJSON for both writes — never Data.write(to:).
+    public func append(
+        pngData: Data, pixelWidth: Int, pixelHeight: Int,
+        scale: CGFloat, capturedAt: Date
+    ) throws -> Capture {
+        let captureID = UUID()
+        let sequence = openSession.nextSequence
+        let fileName = "\(String(format: "%03d", sequence))-\(Self.hexSuffix(captureID)).png"
+        let sessionDir = paths.sessionDirectory(openSession.id)
+        let fileURL = sessionDir.appendingPathComponent(fileName)
+        try AtomicFile.write(pngData, to: fileURL)
+        let capture = Capture(
+            id: captureID, sequence: sequence, fileName: fileName,
+            pixelWidth: pixelWidth, pixelHeight: pixelHeight,
+            scale: scale, capturedAt: capturedAt)
+        let updated = openSession.appending(capture)
+        try AtomicFile.writeJSON(updated, to: sessionDir.appendingPathComponent("session.json"))
+        openSession = updated
+        return capture
+    }
+
+    /// D-11: moves the capture's PNG into `<sessionDir>/removed/` (created lazily) and drops
+    /// its manifest entry. NEVER unlinks/deletes a user PNG. Throws (no filesystem change) if
+    /// `captureID` is not present in the open session.
+    public func remove(captureID: UUID) throws -> CaptureSession {
+        guard let capture = openSession.captures.first(where: { $0.id == captureID }) else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: paths.sessionDirectory(openSession.id).path,
+                underlying: "capture \(captureID) is not in the open session")
+        }
+        let sessionDir = paths.sessionDirectory(openSession.id)
+        let removedDir = sessionDir.appendingPathComponent("removed", isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: removedDir, withIntermediateDirectories: true)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(path: removedDir.path, underlying: error.localizedDescription)
+        }
+        let sourceURL = sessionDir.appendingPathComponent(capture.fileName)
+        let destURL = removedDir.appendingPathComponent(capture.fileName)
+        guard rename(sourceURL.path, destURL.path) == 0 else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: destURL.path,
+                underlying: "could not move the capture into removed/: \(String(cString: strerror(errno)))")
+        }
+        try AtomicFile.fsyncDirectory(at: removedDir)
+        let updated = openSession.removing(captureID: captureID)
+        try AtomicFile.writeJSON(updated, to: sessionDir.appendingPathComponent("session.json"))
+        openSession = updated
+        return updated
+    }
+
+    /// Closes the open session (must be non-empty), moves its directory under archive/, records
+    /// pdfFileName, and starts a fresh empty open session. Returns the archived one.
+    public func archiveCurrent(pdfFileName: String) throws -> CaptureSession {
+        guard !openSession.isEmpty else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: paths.sessionDirectory(openSession.id).path,
+                underlying: "cannot archive an empty session")
+        }
+        let archived = openSession.markArchived(pdfFileName: pdfFileName)
+        let sessionDir = paths.sessionDirectory(openSession.id)
+        try AtomicFile.writeJSON(archived, to: sessionDir.appendingPathComponent("session.json"))
+        let archiveDir = paths.archiveDirectory(openSession.id)
+        guard rename(sessionDir.path, archiveDir.path) == 0 else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: sessionDir.path,
+                underlying: "could not move the session into archive/: \(String(cString: strerror(errno)))")
+        }
+        try AtomicFile.fsyncDirectory(at: paths.archive)
+        let fresh = try Self.createFreshSession(paths: paths)
+        openSession = fresh
+        return archived
+    }
+
+    /// Abandons the open session only if it is empty (mints a new id/dir/manifest); throws,
+    /// with no filesystem change, if the open session has captures.
+    public func startNewSession() throws -> CaptureSession {
+        guard openSession.isEmpty else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: paths.sessionDirectory(openSession.id).path,
+                underlying: "cannot start a new session: \(openSession.captures.count) capture(s) present in the open session")
+        }
+        let fresh = try Self.createFreshSession(paths: paths)
+        openSession = fresh
+        return fresh
+    }
+
+    /// Absolute URL of a capture's PNG, in whichever top-level directory its session lives
+    /// (spool/ if session.state == .open, archive/ if .archived).
+    public func imageURL(for capture: Capture, in session: CaptureSession) -> URL {
+        let dir = session.state == .open ? paths.sessionDirectory(session.id) : paths.archiveDirectory(session.id)
+        return dir.appendingPathComponent(capture.fileName)
+    }
+
+    /// Archived sessions, newest createdAt first. Lazily reconciles each archive/ directory
+    /// the same way init reconciles spool/ candidates (orphan recovery, missing-drop, corrupt
+    /// rebuild) — an archived session's manifest can degrade too and must self-heal without
+    /// ever losing a PNG.
+    public func archivedSessions() throws -> [CaptureSession] {
+        let ids = try Self.listUUIDDirectories(in: paths.archive, fileManager: .default)
+        var sessions: [CaptureSession] = []
+        for id in ids {
+            sessions.append(
+                try Self.reconcileSessionDirectory(
+                    at: paths.archiveDirectory(id), id: id, assumedStateIfRebuilt: .archived, fileManager: .default))
+        }
+        return sessions.sorted { ($0.createdAt, $0.id.uuidString) > ($1.createdAt, $1.id.uuidString) }
+    }
+
+    // MARK: - Reconciliation (static so they can run inside init)
+
+    private static func listUUIDDirectories(in parent: URL, fileManager: FileManager) throws -> [UUID] {
+        let entries: [URL]
+        do {
+            entries = try fileManager.contentsOfDirectory(
+                at: parent,
+                includingPropertiesForKeys: [.isDirectoryKey],
+                options: [])
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(path: parent.path, underlying: error.localizedDescription)
+        }
+        var ids: [UUID] = []
+        for url in entries {
+            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
+            guard isDirectory else { continue }
+            if let id = UUID(uuidString: url.lastPathComponent) {
+                ids.append(id)
+            }
+        }
+        return ids
+    }
+
+    private static func supersedeSpoolArchiveOverlaps(paths: AppSupportPaths, fileManager: FileManager) throws {
+        let spoolIDs = Set(try listUUIDDirectories(in: paths.spool, fileManager: fileManager))
+        let archiveIDs = Set(try listUUIDDirectories(in: paths.archive, fileManager: fileManager))
+        for id in spoolIDs.intersection(archiveIDs) {
+            let spoolDir = paths.sessionDirectory(id)
+            let supersededDir = paths.spool.appendingPathComponent(
+                "\(id.uuidString).superseded-\(DubaiTime.fileStamp(Date()))", isDirectory: true)
+            guard rename(spoolDir.path, supersededDir.path) == 0 else {
+                throw ShotdeckError.spoolWriteFailed(
+                    path: spoolDir.path,
+                    underlying: "could not supersede a duplicate spool copy: \(String(cString: strerror(errno)))")
+            }
+            try AtomicFile.fsyncDirectory(at: paths.spool)
+            Log.spool.warning("Found session \(id.uuidString, privacy: .public) in both spool/ and archive/; kept the archive copy and superseded the spool copy — nothing was deleted.")
+        }
+    }
+
+    private static func finishInterruptedArchives(paths: AppSupportPaths, fileManager: FileManager) throws {
+        for id in try listUUIDDirectories(in: paths.spool, fileManager: fileManager) {
+            let spoolDir = paths.sessionDirectory(id)
+            let manifestURL = spoolDir.appendingPathComponent("session.json")
+            guard let data = try? Data(contentsOf: manifestURL),
+                  let decoded = try? decodeSession(from: data),
+                  decoded.id == id, decoded.state == .archived
+            else { continue }
+            let archiveDir = paths.archiveDirectory(id)
+            guard rename(spoolDir.path, archiveDir.path) == 0 else {
+                throw ShotdeckError.spoolWriteFailed(
+                    path: spoolDir.path,
+                    underlying: "could not complete an interrupted archive move: \(String(cString: strerror(errno)))")
+            }
+            try AtomicFile.fsyncDirectory(at: paths.archive)
+            Log.spool.warning("Completed an archive move for \(id.uuidString, privacy: .public) that was interrupted before this launch.")
+        }
+    }
+
+    private static func reconcileSessionDirectory(
+        at dir: URL,
+        id: UUID,
+        assumedStateIfRebuilt: SessionState,
+        fileManager: FileManager
+    ) throws -> CaptureSession {
+        let manifestURL = dir.appendingPathComponent("session.json")
+        let decoded: CaptureSession?
+        if let data = try? Data(contentsOf: manifestURL),
+           let session = try? decodeSession(from: data),
+           session.id == id {
+            decoded = session
+        } else {
+            decoded = nil
+        }
+
+        guard let session = decoded else {
+            return try rebuildManifest(
+                at: dir,
+                id: id,
+                assumedState: assumedStateIfRebuilt,
+                fileManager: fileManager)
+        }
+
+        var present: [Capture] = []
+        var missingCount = 0
+        for capture in session.captures {
+            let fileURL = dir.appendingPathComponent(capture.fileName)
+            if fileManager.fileExists(atPath: fileURL.path) {
+                present.append(capture)
+            } else {
+                missingCount += 1
+            }
+        }
+        let referenced = Set(session.captures.map(\.fileName))
+        let pngs = try listCapturePNGs(in: dir, fileManager: fileManager)
+        var recoveredOrphans: [Capture] = []
+        for pngURL in pngs where !referenced.contains(pngURL.lastPathComponent) {
+            if let recovered = recoverCapture(from: pngURL, fileManager: fileManager) {
+                recoveredOrphans.append(recovered)
+            } else {
+                Log.spool.error("Could not decode orphan PNG at \(pngURL.path, privacy: .public); leaving it on disk.")
+            }
+        }
+        let deletedTmp = deleteStrayTmpFiles(in: dir, fileManager: fileManager)
+        if missingCount == 0 && recoveredOrphans.isEmpty && !deletedTmp {
+            return session
+        }
+        let finalCaptures = (present + recoveredOrphans).sorted { $0.sequence < $1.sequence }
+        let updated = CaptureSession(
+            id: session.id,
+            createdAt: session.createdAt,
+            state: session.state,
+            captures: finalCaptures,
+            pdfFileName: session.pdfFileName)
+        try AtomicFile.writeJSON(updated, to: manifestURL)
+        Log.spool.warning("Reconciled session \(id.uuidString, privacy: .public): dropped \(missingCount) missing PNG(s), recovered \(recoveredOrphans.count) orphan(s).")
+        return updated
+    }
+
+    private static func rebuildManifest(
+        at dir: URL,
+        id: UUID,
+        assumedState: SessionState,
+        fileManager: FileManager
+    ) throws -> CaptureSession {
+        let manifestURL = dir.appendingPathComponent("session.json")
+        if fileManager.fileExists(atPath: manifestURL.path) {
+            let corruptURL = dir.appendingPathComponent(
+                "session.json.corrupt-\(DubaiTime.fileStamp(Date()))")
+            do {
+                try fileManager.moveItem(at: manifestURL, to: corruptURL)
+            } catch {
+                throw ShotdeckError.spoolWriteFailed(
+                    path: manifestURL.path,
+                    underlying: "could not quarantine a corrupt manifest: \(error.localizedDescription)")
+            }
+        }
+
+        var recovered: [Capture] = []
+        for pngURL in try listCapturePNGs(in: dir, fileManager: fileManager) {
+            if let capture = recoverCapture(from: pngURL, fileManager: fileManager) {
+                recovered.append(capture)
+            } else {
+                Log.spool.error("Could not decode PNG at \(pngURL.path, privacy: .public) while rebuilding the manifest; leaving it on disk.")
+            }
+        }
+        _ = deleteStrayTmpFiles(in: dir, fileManager: fileManager)
+        recovered.sort { $0.sequence < $1.sequence }
+
+        let createdAt: Date
+        if let earliest = recovered.map(\.capturedAt).min() {
+            createdAt = earliest
+        } else {
+            createdAt = (try? dir.resourceValues(forKeys: [.creationDateKey]))?.creationDate ?? Date()
+        }
+
+        let rebuilt = CaptureSession(
+            id: id,
+            createdAt: createdAt,
+            state: assumedState,
+            captures: recovered,
+            pdfFileName: nil)
+        try AtomicFile.writeJSON(rebuilt, to: dir.appendingPathComponent("session.json"))
+        Log.spool.warning("Rebuilt manifest for \(id.uuidString, privacy: .public) from \(recovered.count) recovered PNG(s).")
+        if assumedState == .archived {
+            Log.spool.warning("Rebuilt an archived session \(id.uuidString, privacy: .public) from PNGs; pdfFileName could not be recovered.")
+        }
+        return rebuilt
+    }
+
+    private static func recoverCapture(from fileURL: URL, fileManager: FileManager) -> Capture? {
+        guard fileManager.fileExists(atPath: fileURL.path) else { return nil }
+        guard let source = CGImageSourceCreateWithURL(fileURL as CFURL, nil),
+              let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as NSDictionary?,
+              let width = (properties[kCGImagePropertyPixelWidth] as? NSNumber)?.intValue,
+              let height = (properties[kCGImagePropertyPixelHeight] as? NSNumber)?.intValue
+        else { return nil }
+        let name = fileURL.lastPathComponent
+        let sequence = Int(name.prefix(3)) ?? 1
+        let capturedAt = (try? fileURL.resourceValues(forKeys: [.creationDateKey]))?.creationDate ?? Date()
+        return Capture(
+            id: UUID(),
+            sequence: sequence,
+            fileName: name,
+            pixelWidth: width,
+            pixelHeight: height,
+            scale: 1.0,
+            capturedAt: capturedAt)
+    }
+
+    private static func pickNewest(first: CaptureSession, rest: [CaptureSession]) -> CaptureSession {
+        rest.reduce(first) { current, candidate in
+            let currentKey = (current.createdAt, current.id.uuidString)
+            let candidateKey = (candidate.createdAt, candidate.id.uuidString)
+            return candidateKey > currentKey ? candidate : current
+        }
+    }
+
+    private static func createFreshSession(paths: AppSupportPaths) throws -> CaptureSession {
+        let id = UUID()
+        let createdAt = Date()
+        let dir = paths.sessionDirectory(id)
+        do {
+            try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(path: dir.path, underlying: error.localizedDescription)
+        }
+        let session = CaptureSession(id: id, createdAt: createdAt, state: .open, captures: [], pdfFileName: nil)
+        try AtomicFile.writeJSON(session, to: dir.appendingPathComponent("session.json"))
+        return session
+    }
+
+    private static func hexSuffix(_ id: UUID) -> String {
+        String(id.uuidString.replacingOccurrences(of: "-", with: "").prefix(8)).uppercased()
+    }
+
+    private static func decodeSession(from data: Data) throws -> CaptureSession {
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        return try decoder.decode(CaptureSession.self, from: data)
+    }
+
+    private static func isCapturePNGName(_ name: String) -> Bool {
+        guard name.hasSuffix(".png") else { return false }
+        let stem = String(name.dropLast(4))
+        let parts = stem.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)
+        guard parts.count == 2,
+              parts[0].count == 3,
+              parts[0].allSatisfy(\.isNumber),
+              parts[1].count == 8,
+              parts[1].allSatisfy(\.isHexDigit)
+        else { return false }
+        return true
+    }
+
+    private static func listCapturePNGs(in dir: URL, fileManager: FileManager) throws -> [URL] {
+        let entries: [URL]
+        do {
+            entries = try fileManager.contentsOfDirectory(
+                at: dir,
+                includingPropertiesForKeys: [.isDirectoryKey],
+                options: [])
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(path: dir.path, underlying: error.localizedDescription)
+        }
+        return entries.filter { url in
+            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
+            guard !isDirectory else { return false }
+            return isCapturePNGName(url.lastPathComponent)
+        }
+    }
+
+    private static func deleteStrayTmpFiles(in dir: URL, fileManager: FileManager) -> Bool {
+        let entries = (try? fileManager.contentsOfDirectory(
+            at: dir,
+            includingPropertiesForKeys: [.isDirectoryKey],
+            options: [])) ?? []
+        var deleted = false
+        for url in entries {
+            guard url.lastPathComponent.hasSuffix(".tmp") else { continue }
+            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
+            guard !isDirectory else { continue }
+            do {
+                try fileManager.removeItem(at: url)
+                deleted = true
+            } catch {
+                Log.spool.error("Could not remove stray temp file at \(url.path, privacy: .public): \(error.localizedDescription, privacy: .public)")
+            }
+        }
+        return deleted
+    }
+}

Sources/ShotdeckCore/Support/AppSupportPaths.swift

@@ -0,0 +1,65 @@
+import Foundation
+
+/// The only type in the app that knows the on-disk directory layout.
+public struct AppSupportPaths: Sendable {
+    public let root: URL
+    public let spool: URL
+    public let archive: URL
+    public let outbox: URL
+    public let watchFolder: URL
+
+    /// Production paths.
+    public static func standard() throws -> AppSupportPaths {
+        let fileManager = FileManager.default
+        let appSupportParent = try fileManager.url(
+            for: .applicationSupportDirectory,
+            in: .userDomainMask,
+            appropriateFor: nil,
+            create: true
+        )
+        let desktop = try fileManager.url(
+            for: .desktopDirectory,
+            in: .userDomainMask,
+            appropriateFor: nil,
+            create: true
+        )
+        let downloads = try fileManager.url(
+            for: .downloadsDirectory,
+            in: .userDomainMask,
+            appropriateFor: nil,
+            create: true
+        )
+        let root = appSupportParent.appendingPathComponent("Shotdeck", isDirectory: true)
+        return try AppSupportPaths(root: root, outbox: desktop, watchFolder: downloads)
+    }
+
+    /// Test paths rooted anywhere. Every directory is created if missing.
+    public init(root: URL, outbox: URL, watchFolder: URL) throws {
+        self.root = root
+        self.spool = root.appendingPathComponent("spool", isDirectory: true)
+        self.archive = root.appendingPathComponent("archive", isDirectory: true)
+        self.outbox = outbox
+        self.watchFolder = watchFolder
+
+        try Self.createDirectory(self.root)
+        try Self.createDirectory(self.spool)
+        try Self.createDirectory(self.archive)
+        try Self.createDirectory(self.outbox)
+        try Self.createDirectory(self.watchFolder)
+    }
+
+    public func sessionDirectory(_ id: UUID) -> URL {
+        spool.appendingPathComponent(id.uuidString, isDirectory: true)
+    }
+
+    public func archiveDirectory(_ id: UUID) -> URL {
+        archive.appendingPathComponent(id.uuidString, isDirectory: true)
+    }
+
+    private static func createDirectory(_ url: URL) throws {
+        try FileManager.default.createDirectory(
+            at: url,
+            withIntermediateDirectories: true
+        )
+    }
+}

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/DubaiTime.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+public enum DubaiTime {
+    private static let stampFormatter = LockedDateFormatter(dateFormat: "d MMM yyyy, HH:mm 'Dubai'")
+    private static let fileStampFormatter = LockedDateFormatter(dateFormat: "yyyyMMdd-HHmmss")
+
+    public static func stamp(_ date: Date) -> String {
+        stampFormatter.string(from: date)
+    }
+
+    public static func fileStamp(_ date: Date) -> String {
+        fileStampFormatter.string(from: date)
+    }
+}
+
+/// DateFormatter is not Sendable. This holder is the only shared mutable state
+/// around a formatter: every read is serialized by the lock, so concurrent
+/// calls (one per PDF page) cannot race.
+private final class LockedDateFormatter: @unchecked Sendable {
+    private let lock = NSLock()
+    private let formatter: DateFormatter
+
+    init(dateFormat: String) {
+        let formatter = DateFormatter()
+        formatter.calendar = Calendar(identifier: .gregorian)
+        formatter.locale = Locale(identifier: "en_GB")
+        guard let dubai = TimeZone(identifier: "Asia/Dubai") else {
+            preconditionFailure("The Asia/Dubai time zone is missing from this system.")
+        }
+        formatter.timeZone = dubai
+        formatter.dateFormat = dateFormat
+        self.formatter = formatter
+    }
+
+    func string(from date: Date) -> String {
+        lock.lock()
+        defer { lock.unlock() }
+        return formatter.string(from: date)
+    }
+}

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/AppSupportPathsTests.swift

@@ -0,0 +1,75 @@
+import Foundation
+import Testing
+import ShotdeckCore
+
+@Test
+func appSupportPathsCreatesEveryNamedDirectory() throws {
+    let temporaryRoot = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-paths-\(UUID().uuidString)", isDirectory: true)
+    defer { try? FileManager.default.removeItem(at: temporaryRoot) }
+
+    let root = temporaryRoot.appendingPathComponent("root", isDirectory: true)
+    let outbox = temporaryRoot.appendingPathComponent("outbox", isDirectory: true)
+    let watchFolder = temporaryRoot.appendingPathComponent("watch", isDirectory: true)
+
+    let paths = try AppSupportPaths(root: root, outbox: outbox, watchFolder: watchFolder)
+
+    #expect(directoryExists(paths.root))
+    #expect(directoryExists(paths.spool))
+    #expect(directoryExists(paths.archive))
+    #expect(directoryExists(paths.outbox))
+    #expect(directoryExists(paths.watchFolder))
+
+    #expect(paths.spool.path == root.appendingPathComponent("spool", isDirectory: true).path)
+    #expect(paths.archive.path == root.appendingPathComponent("archive", isDirectory: true).path)
+}
+
+@Test
+func sessionAndArchiveDirectoriesAreDistinctUnderTheRightParents() throws {
+    let temporaryRoot = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-dirs-\(UUID().uuidString)", isDirectory: true)
+    defer { try? FileManager.default.removeItem(at: temporaryRoot) }
+
+    let paths = try AppSupportPaths(
+        root: temporaryRoot.appendingPathComponent("root", isDirectory: true),
+        outbox: temporaryRoot.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: temporaryRoot.appendingPathComponent("watch", isDirectory: true)
+    )
+
+    let sessionID = UUID()
+    let sessionDirectory = paths.sessionDirectory(sessionID)
+    let archiveDirectory = paths.archiveDirectory(sessionID)
+
+    #expect(sessionDirectory.path != archiveDirectory.path)
+    #expect(sessionDirectory.deletingLastPathComponent().path == paths.spool.path)
+    #expect(archiveDirectory.deletingLastPathComponent().path == paths.archive.path)
+    #expect(sessionDirectory.lastPathComponent == sessionID.uuidString)
+    #expect(archiveDirectory.lastPathComponent == sessionID.uuidString)
+}
+
+@Test
+func dubaiTimeStampRendersAKnownInstantInAsiaDubai() throws {
+    var calendar = Calendar(identifier: .gregorian)
+    let dubai = try #require(TimeZone(identifier: "Asia/Dubai"))
+    calendar.timeZone = dubai
+
+    let date = try #require(
+        calendar.date(from: DateComponents(
+            year: 2026,
+            month: 8,
+            day: 30,
+            hour: 13,
+            minute: 42,
+            second: 5
+        ))
+    )
+
+    #expect(DubaiTime.stamp(date) == "30 Aug 2026, 13:42 Dubai")
+    #expect(DubaiTime.fileStamp(date) == "20260830-134205")
+}
+
+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/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/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/SpoolStoreTests.swift

@@ -0,0 +1,590 @@
+import CoreGraphics
+import Foundation
+import ImageIO
+import Testing
+import ShotdeckCore
+
+// MARK: - 1. append writes a real, decodable PNG
+
+@Test
+func appendWritesARealDecodablePNGMatchingSourceDimensions() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let width = 12
+    let height = 7
+    let png = try makePNGData(width: width, height: height, red: 0.9, green: 0.1, blue: 0.2)
+    let store = try SpoolStore(paths: paths)
+    let capturedAt = Date(timeIntervalSince1970: 1_700_000_000)
+    let capture = try await store.append(
+        pngData: png, pixelWidth: width, pixelHeight: height, scale: 2.0, capturedAt: capturedAt)
+    let session = try await store.currentSession()
+
+    #expect(capture.pixelWidth == width)
+    #expect(capture.pixelHeight == height)
+
+    let url = await store.imageURL(for: capture, in: session)
+    let expected = paths.sessionDirectory(session.id).appendingPathComponent(capture.fileName)
+    #expect(url.path == expected.path)
+    #expect(FileManager.default.fileExists(atPath: url.path))
+
+    let onDisk = try Data(contentsOf: url)
+    #expect(onDisk == png)
+    let decoded = try #require(pngDimensions(at: url))
+    #expect(decoded.width == width)
+    #expect(decoded.height == height)
+}
+
+// MARK: - 2. remaining-manifest sequence rule (coordinator correction)
+
+@Test
+func sequencesFollowRemainingManifestMaxAndAreNotRenumbered() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let c1 = try await store.append(
+        pngData: try makePNGData(width: 4, height: 4, red: 1, green: 0, blue: 0),
+        pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
+    let c2 = try await store.append(
+        pngData: try makePNGData(width: 6, height: 4, red: 0, green: 1, blue: 0),
+        pixelWidth: 6, pixelHeight: 4, scale: 1.0, capturedAt: Date())
+    let c3 = try await store.append(
+        pngData: try makePNGData(width: 8, height: 4, red: 0, green: 0, blue: 1),
+        pixelWidth: 8, pixelHeight: 4, scale: 1.0, capturedAt: Date())
+    #expect(c1.sequence == 1)
+    #expect(c2.sequence == 2)
+    #expect(c3.sequence == 3)
+
+    _ = try await store.remove(captureID: c2.id)
+    let afterMiddle = try await store.currentSession()
+    #expect(afterMiddle.captures.map(\.sequence) == [1, 3])
+    #expect(afterMiddle.captures.map(\.id) == [c1.id, c3.id])
+
+    let c4 = try await store.append(
+        pngData: try makePNGData(width: 10, height: 4, red: 1, green: 1, blue: 0),
+        pixelWidth: 10, pixelHeight: 4, scale: 1.0, capturedAt: Date())
+    #expect(c4.sequence == 4)
+
+    _ = try await store.remove(captureID: c4.id)
+    let afterLast = try await store.currentSession()
+    #expect(afterLast.captures.map(\.sequence) == [1, 3])
+
+    let c4b = try await store.append(
+        pngData: try makePNGData(width: 12, height: 4, red: 1, green: 0, blue: 1),
+        pixelWidth: 12, pixelHeight: 4, scale: 1.0, capturedAt: Date())
+    #expect(c4b.sequence == 4)
+    #expect(c4b.fileName != c4.fileName)
+    #expect(c4b.id != c4.id)
+
+    let sessionDir = paths.sessionDirectory(afterLast.id)
+    #expect(FileManager.default.fileExists(atPath: sessionDir.appendingPathComponent(c4b.fileName).path))
+    #expect(FileManager.default.fileExists(
+        atPath: sessionDir.appendingPathComponent("removed", isDirectory: true)
+            .appendingPathComponent(c4.fileName).path))
+    #expect(!FileManager.default.fileExists(atPath: sessionDir.appendingPathComponent(c4.fileName).path))
+}
+
+// MARK: - 3. remove moves PNG into removed/
+
+@Test
+func removeMovesThePNGUnchangedIntoRemovedAndLeavesTheOriginalPathEmpty() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let png = try makePNGData(width: 8, height: 5, red: 0.2, green: 0.5, blue: 0.8)
+    let capture = try await store.append(
+        pngData: png, pixelWidth: 8, pixelHeight: 5, scale: 2.0, capturedAt: Date())
+    let session = try await store.currentSession()
+    let sessionDir = paths.sessionDirectory(session.id)
+    let originalURL = sessionDir.appendingPathComponent(capture.fileName)
+    let removedURL = sessionDir.appendingPathComponent("removed", isDirectory: true)
+        .appendingPathComponent(capture.fileName)
+
+    let updated = try await store.remove(captureID: capture.id)
+
+    #expect(updated.captures.contains(where: { $0.id == capture.id }) == false)
+    #expect(!FileManager.default.fileExists(atPath: originalURL.path))
+    #expect(FileManager.default.fileExists(atPath: removedURL.path))
+    let moved = try Data(contentsOf: removedURL)
+    #expect(moved == png)
+}
+
+// MARK: - 4. remove of unknown id throws with zero filesystem change
+
+@Test
+func removeOfUnknownIDThrowsAndLeavesDiskByteIdentical() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    _ = try await store.append(
+        pngData: try makePNGData(width: 4, height: 4, red: 0.1, green: 0.2, blue: 0.3),
+        pixelWidth: 4, pixelHeight: 4, scale: 1.0, capturedAt: Date())
+    let beforeSession = try await store.currentSession()
+    let beforeFiles = try snapshotFiles(under: root)
+
+    do {
+        _ = try await store.remove(captureID: UUID())
+        Issue.record("expected remove of an unknown id to throw")
+    } catch let error as ShotdeckError {
+        guard case .spoolWriteFailed = error else {
+            Issue.record("expected spoolWriteFailed, got \(error)")
+            return
+        }
+    } catch {
+        Issue.record("expected ShotdeckError, got \(error)")
+        return
+    }
+
+    let afterSession = try await store.currentSession()
+    #expect(afterSession == beforeSession)
+    let afterFiles = try snapshotFiles(under: root)
+    #expect(afterFiles == beforeFiles)
+}
+
+// MARK: - 5. orphan recovery
+
+@Test
+func orphanPNGWrittenBehindTheStoreIsRecoveredOnReopen() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let session = try await store.currentSession()
+    let width = 11
+    let height = 9
+    let png = try makePNGData(width: width, height: height, red: 0.4, green: 0.7, blue: 0.1)
+    let orphanName = "007-ABCD1234.png"
+    let dest = paths.sessionDirectory(session.id).appendingPathComponent(orphanName)
+    try AtomicFile.write(png, to: dest)
+
+    let reopened = try SpoolStore(paths: paths)
+    let recovered = try await reopened.currentSession()
+    let match = try #require(recovered.captures.first { $0.fileName == orphanName })
+    #expect(match.pixelWidth == width)
+    #expect(match.pixelHeight == height)
+    #expect(match.sequence == 7)
+    #expect(match.scale == 1.0)
+}
+
+// MARK: - 6. removed/ files are not resurrected
+
+@Test
+func orphanRecoveryDoesNotResurrectFilesInRemoved() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let session = try await store.currentSession()
+    let sessionDir = paths.sessionDirectory(session.id)
+    let removedDir = sessionDir.appendingPathComponent("removed", isDirectory: true)
+    try FileManager.default.createDirectory(at: removedDir, withIntermediateDirectories: true)
+    let hiddenName = "009-FEEDFACE.png"
+    try AtomicFile.write(
+        try makePNGData(width: 5, height: 5, red: 0.9, green: 0.9, blue: 0.1),
+        to: removedDir.appendingPathComponent(hiddenName))
+
+    let reopened = try SpoolStore(paths: paths)
+    let reconciled = try await reopened.currentSession()
+    #expect(reconciled.captures.contains(where: { $0.fileName == hiddenName }) == false)
+    #expect(FileManager.default.fileExists(atPath: removedDir.appendingPathComponent(hiddenName).path))
+}
+
+// MARK: - 7. missing-image drop
+
+@Test
+func missingPNGReferencedByManifestIsDroppedAndOthersSurvive() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let keep = try await store.append(
+        pngData: try makePNGData(width: 6, height: 6, red: 0.1, green: 0.8, blue: 0.2),
+        pixelWidth: 6, pixelHeight: 6, scale: 1.0, capturedAt: Date())
+    let drop = try await store.append(
+        pngData: try makePNGData(width: 7, height: 7, red: 0.8, green: 0.1, blue: 0.2),
+        pixelWidth: 7, pixelHeight: 7, scale: 1.0, capturedAt: Date())
+    let session = try await store.currentSession()
+    try FileManager.default.removeItem(
+        at: paths.sessionDirectory(session.id).appendingPathComponent(drop.fileName))
+
+    let reopened = try SpoolStore(paths: paths)
+    let reconciled = try await reopened.currentSession()
+    #expect(reconciled.captures.map(\.id) == [keep.id])
+    #expect(reconciled.captures.contains(where: { $0.id == drop.id }) == false)
+}
+
+// MARK: - 8. corrupt manifest rebuild
+
+@Test
+func corruptManifestIsQuarantinedAndPNGsAreRebuiltIntoANewManifest() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let first = try await store.append(
+        pngData: try makePNGData(width: 8, height: 6, red: 0.3, green: 0.3, blue: 0.9),
+        pixelWidth: 8, pixelHeight: 6, scale: 2.0, capturedAt: Date())
+    let second = try await store.append(
+        pngData: try makePNGData(width: 9, height: 6, red: 0.9, green: 0.3, blue: 0.3),
+        pixelWidth: 9, pixelHeight: 6, scale: 2.0, capturedAt: Date())
+    let session = try await store.currentSession()
+    let sessionDir = paths.sessionDirectory(session.id)
+    let manifestURL = sessionDir.appendingPathComponent("session.json")
+    let garbage = Data("{ not json".utf8)
+    try AtomicFile.write(garbage, to: manifestURL)
+
+    let reopened = try SpoolStore(paths: paths)
+    let rebuilt = try await reopened.currentSession()
+    #expect(rebuilt.id == session.id)
+
+    let contents = try FileManager.default.contentsOfDirectory(at: sessionDir, includingPropertiesForKeys: nil)
+    let corruptFiles = contents.filter { $0.lastPathComponent.hasPrefix("session.json.corrupt-") }
+    #expect(corruptFiles.count == 1)
+    let quarantined = try Data(contentsOf: try #require(corruptFiles.first))
+    #expect(quarantined == garbage)
+
+    let names = Set(rebuilt.captures.map(\.fileName))
+    #expect(names.contains(first.fileName))
+    #expect(names.contains(second.fileName))
+    let recoveredFirst = try #require(rebuilt.captures.first { $0.fileName == first.fileName })
+    #expect(recoveredFirst.pixelWidth == 8)
+    #expect(recoveredFirst.pixelHeight == 6)
+}
+
+// MARK: - 9. archiveCurrent moves the directory
+
+@Test
+func archiveCurrentMovesTheSessionUnderArchiveAndOpensAFreshEmptySession() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let png = try makePNGData(width: 10, height: 8, red: 0.5, green: 0.1, blue: 0.6)
+    let capture = try await store.append(
+        pngData: png, pixelWidth: 10, pixelHeight: 8, scale: 1.0, capturedAt: Date())
+    let open = try await store.currentSession()
+    let archived = try await store.archiveCurrent(pdfFileName: "shotdeck-review.pdf")
+
+    #expect(archived.state == .archived)
+    #expect(archived.pdfFileName == "shotdeck-review.pdf")
+    #expect(archived.id == open.id)
+    #expect(!FileManager.default.fileExists(atPath: paths.sessionDirectory(open.id).path))
+
+    let archivedPNG = paths.archiveDirectory(open.id).appendingPathComponent(capture.fileName)
+    #expect(FileManager.default.fileExists(atPath: archivedPNG.path))
+    #expect(try Data(contentsOf: archivedPNG) == png)
+
+    let current = try await store.currentSession()
+    #expect(current.id != open.id)
+    #expect(current.isEmpty)
+    #expect(current.state == .open)
+    #expect(FileManager.default.fileExists(
+        atPath: paths.sessionDirectory(current.id).appendingPathComponent("session.json").path))
+}
+
+// MARK: - 10. archiveCurrent on empty throws
+
+@Test
+func archiveCurrentOnEmptySessionThrowsAndDoesNotMoveTheDirectory() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let session = try await store.currentSession()
+    let before = try snapshotFiles(under: root)
+
+    do {
+        _ = try await store.archiveCurrent(pdfFileName: "never.pdf")
+        Issue.record("expected archiveCurrent on an empty session to throw")
+    } catch let error as ShotdeckError {
+        guard case .spoolWriteFailed = error else {
+            Issue.record("expected spoolWriteFailed, got \(error)")
+            return
+        }
+    } catch {
+        Issue.record("expected ShotdeckError, got \(error)")
+        return
+    }
+
+    #expect(FileManager.default.fileExists(atPath: paths.sessionDirectory(session.id).path))
+    #expect(try snapshotFiles(under: root) == before)
+}
+
+// MARK: - 11. interrupted-archive, both exist
+
+@Test
+func interruptedArchiveBothExistSupersedesTheSpoolCopyAndKeepsArchive() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let png = try makePNGData(width: 8, height: 8, red: 0.2, green: 0.2, blue: 0.8)
+    let capture = try await store.append(
+        pngData: png, pixelWidth: 8, pixelHeight: 8, scale: 1.0, capturedAt: Date())
+    let archived = try await store.archiveCurrent(pdfFileName: "sent.pdf")
+    let archiveDir = paths.archiveDirectory(archived.id)
+    let spoolCopy = paths.sessionDirectory(archived.id)
+    try FileManager.default.copyItem(at: archiveDir, to: spoolCopy)
+    let archivePNGBefore = try Data(contentsOf: archiveDir.appendingPathComponent(capture.fileName))
+
+    let reopened = try SpoolStore(paths: paths)
+    _ = try await reopened.currentSession()
+
+    #expect(FileManager.default.fileExists(atPath: archiveDir.path))
+    #expect(!FileManager.default.fileExists(atPath: spoolCopy.path))
+    #expect(try Data(contentsOf: archiveDir.appendingPathComponent(capture.fileName)) == archivePNGBefore)
+
+    let spoolEntries = try FileManager.default.contentsOfDirectory(
+        at: paths.spool, includingPropertiesForKeys: [.isDirectoryKey])
+    let superseded = spoolEntries.filter {
+        $0.lastPathComponent.hasPrefix("\(archived.id.uuidString).superseded-")
+    }
+    #expect(superseded.count == 1)
+    let supersededPNG = try #require(superseded.first).appendingPathComponent(capture.fileName)
+    #expect(FileManager.default.fileExists(atPath: supersededPNG.path))
+    #expect(try Data(contentsOf: supersededPNG) == png)
+}
+
+// MARK: - 12. interrupted-archive, manifest-only
+
+@Test
+func interruptedArchiveManifestOnlyCompletesTheMoveIntoArchive() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let png = try makePNGData(width: 6, height: 8, red: 0.7, green: 0.4, blue: 0.1)
+    let capture = try await store.append(
+        pngData: png, pixelWidth: 6, pixelHeight: 8, scale: 1.0, capturedAt: Date())
+    let session = try await store.currentSession()
+    let marked = session.markArchived(pdfFileName: "partial.pdf")
+    try AtomicFile.writeJSON(
+        marked, to: paths.sessionDirectory(session.id).appendingPathComponent("session.json"))
+
+    let reopened = try SpoolStore(paths: paths)
+    let current = try await reopened.currentSession()
+    #expect(current.id != session.id)
+    #expect(!FileManager.default.fileExists(atPath: paths.sessionDirectory(session.id).path))
+    let archiveDir = paths.archiveDirectory(session.id)
+    #expect(FileManager.default.fileExists(atPath: archiveDir.path))
+    #expect(FileManager.default.fileExists(atPath: archiveDir.appendingPathComponent(capture.fileName).path))
+    #expect(try Data(contentsOf: archiveDir.appendingPathComponent(capture.fileName)) == png)
+
+    let archived = try await reopened.archivedSessions()
+    #expect(archived.contains(where: { $0.id == session.id }))
+}
+
+// MARK: - 13. archivedSessions newest createdAt first
+
+@Test
+func archivedSessionsReturnsNewestCreatedAtFirst() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let newest = UUID(uuidString: "00000000-0000-4000-8000-000000000003")!
+    let oldest = UUID(uuidString: "00000000-0000-4000-8000-000000000001")!
+    let middle = UUID(uuidString: "00000000-0000-4000-8000-000000000002")!
+    let tNewest = Date(timeIntervalSince1970: 1_700_000_200)
+    let tOldest = Date(timeIntervalSince1970: 1_700_000_000)
+    let tMiddle = Date(timeIntervalSince1970: 1_700_000_100)
+
+    try seedSession(id: newest, createdAt: tNewest, state: .archived, directory: paths.archiveDirectory(newest))
+    try seedSession(id: oldest, createdAt: tOldest, state: .archived, directory: paths.archiveDirectory(oldest))
+    try seedSession(id: middle, createdAt: tMiddle, state: .archived, directory: paths.archiveDirectory(middle))
+
+    let store = try SpoolStore(paths: paths)
+    let listed = try await store.archivedSessions()
+    #expect(listed.map(\.id) == [newest, middle, oldest])
+}
+
+// MARK: - 14. newest-session tie-break by greater UUID string
+
+@Test
+func newestSessionTieBreakPicksTheLexicographicallyGreaterUUID() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let smaller = UUID(uuidString: "AAAAAAAA-AAAA-4AAA-8AAA-AAAAAAAAAAAA")!
+    let greater = UUID(uuidString: "BBBBBBBB-BBBB-4BBB-8BBB-BBBBBBBBBBBB")!
+    let createdAt = Date(timeIntervalSince1970: 1_700_000_500)
+    try seedSession(id: smaller, createdAt: createdAt, state: .open, directory: paths.sessionDirectory(smaller))
+    try seedSession(id: greater, createdAt: createdAt, state: .open, directory: paths.sessionDirectory(greater))
+
+    let first = try SpoolStore(paths: paths)
+    let firstID = try await first.currentSession().id
+    let second = try SpoolStore(paths: paths)
+    let secondID = try await second.currentSession().id
+    #expect(firstID == greater)
+    #expect(secondID == greater)
+}
+
+// MARK: - 15. filename shape
+
+@Test
+func appendFilenameMatchesSequenceDashEightHexSuffix() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let capture = try await store.append(
+        pngData: try makePNGData(width: 4, height: 3, red: 0.1, green: 0.1, blue: 0.1),
+        pixelWidth: 4, pixelHeight: 3, scale: 1.0, capturedAt: Date())
+    let hex = String(capture.id.uuidString.replacingOccurrences(of: "-", with: "").prefix(8)).uppercased()
+    #expect(capture.fileName == "001-\(hex).png")
+    let session = try await store.currentSession()
+    let url = await store.imageURL(for: capture, in: session)
+    #expect(url.lastPathComponent == capture.fileName)
+    #expect(FileManager.default.fileExists(atPath: url.path))
+}
+
+// MARK: - 16. startNewSession
+
+@Test
+func startNewSessionThrowsWhenNonEmptyAndMintsANewIdWhenEmpty() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    _ = try await store.append(
+        pngData: try makePNGData(width: 5, height: 5, red: 0.4, green: 0.2, blue: 0.6),
+        pixelWidth: 5, pixelHeight: 5, scale: 1.0, capturedAt: Date())
+    let before = try snapshotFiles(under: root)
+    let occupied = try await store.currentSession()
+
+    do {
+        _ = try await store.startNewSession()
+        Issue.record("expected startNewSession to throw while captures are present")
+    } catch let error as ShotdeckError {
+        guard case .spoolWriteFailed = error else {
+            Issue.record("expected spoolWriteFailed, got \(error)")
+            return
+        }
+    } catch {
+        Issue.record("expected ShotdeckError, got \(error)")
+        return
+    }
+    #expect(try snapshotFiles(under: root) == before)
+    #expect(try await store.currentSession().id == occupied.id)
+
+    _ = try await store.remove(captureID: occupied.captures[0].id)
+    let emptyID = try await store.currentSession().id
+    let fresh = try await store.startNewSession()
+    #expect(fresh.id != emptyID)
+    #expect(fresh.isEmpty)
+    #expect(FileManager.default.fileExists(
+        atPath: paths.sessionDirectory(emptyID).appendingPathComponent("session.json").path))
+}
+
+// MARK: - 17. durability-ordering smoke test
+
+@Test
+func appendReturnsOnlyAfterThePNGBytesAreAlreadyOnDisk() async throws {
+    let (root, paths) = try makeIsolatedPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try SpoolStore(paths: paths)
+    let png = try makePNGData(width: 13, height: 11, red: 0.15, green: 0.55, blue: 0.95)
+    let capture = try await store.append(
+        pngData: png, pixelWidth: 13, pixelHeight: 11, scale: 2.0, capturedAt: Date())
+    let session = try await store.currentSession()
+    let url = paths.sessionDirectory(session.id).appendingPathComponent(capture.fileName)
+    let onDisk = try Data(contentsOf: url)
+    #expect(onDisk == png)
+}
+
+// MARK: - Fixtures
+
+private func makeIsolatedPaths() throws -> (root: URL, paths: AppSupportPaths) {
+    let root = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-spool-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: root,
+        outbox: root.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: root.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (root, paths)
+}
+
+private func makePNGData(
+    width: Int,
+    height: Int,
+    red: CGFloat,
+    green: CGFloat,
+    blue: CGFloat
+) throws -> Data {
+    let colorSpace = CGColorSpaceCreateDeviceRGB()
+    guard let context = CGContext(
+        data: nil,
+        width: width,
+        height: height,
+        bitsPerComponent: 8,
+        bytesPerRow: width * 4,
+        space: colorSpace,
+        bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+    ) else {
+        throw FixtureError.pngGenerationFailed
+    }
+    context.setFillColor(red: red, green: green, blue: blue, alpha: 1)
+    context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    guard let image = context.makeImage() else {
+        throw FixtureError.pngGenerationFailed
+    }
+    let buffer = NSMutableData()
+    guard let destination = CGImageDestinationCreateWithData(buffer, "public.png" as CFString, 1, nil) else {
+        throw FixtureError.pngGenerationFailed
+    }
+    CGImageDestinationAddImage(destination, image, nil)
+    guard CGImageDestinationFinalize(destination) else {
+        throw FixtureError.pngGenerationFailed
+    }
+    return buffer as Data
+}
+
+private func pngDimensions(at url: URL) -> (width: Int, height: Int)? {
+    guard let source = CGImageSourceCreateWithURL(url as CFURL, nil),
+          let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as NSDictionary?,
+          let width = (properties[kCGImagePropertyPixelWidth] as? NSNumber)?.intValue,
+          let height = (properties[kCGImagePropertyPixelHeight] as? NSNumber)?.intValue
+    else { return nil }
+    return (width, height)
+}
+
+private func seedSession(
+    id: UUID,
+    createdAt: Date,
+    state: SessionState,
+    directory: URL
+) throws {
+    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    let session = CaptureSession(id: id, createdAt: createdAt, state: state, captures: [], pdfFileName: nil)
+    try AtomicFile.writeJSON(session, to: directory.appendingPathComponent("session.json"))
+}
+
+private func snapshotFiles(under root: URL) throws -> [String: Data] {
+    let fm = FileManager.default
+    var files: [String: Data] = [:]
+    guard let enumerator = fm.enumerator(
+        at: root,
+        includingPropertiesForKeys: [.isRegularFileKey],
+        options: [.skipsHiddenFiles]
+    ) else { return files }
+    let rootPath = root.standardizedFileURL.path
+    for case let url as URL in enumerator {
+        let values = try url.resourceValues(forKeys: [.isRegularFileKey])
+        guard values.isRegularFile == true else { continue }
+        var relative = url.standardizedFileURL.path
+        if relative.hasPrefix(rootPath) {
+            relative = String(relative.dropFirst(rootPath.count))
+            if relative.hasPrefix("/") { relative = String(relative.dropFirst()) }
+        }
+        files[relative] = try Data(contentsOf: url)
+    }
+    return files
+}
+
+private enum FixtureError: Error {
+    case pngGenerationFailed
+}

scripts/build-app.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# macOS keys the Screen Recording permission to the bundle identifier plus the
+# code signature. The identity below and --identifier ai.flowmaster.shotdeck must
+# never change: altering either one makes the existing grant invalid and forces
+# the user to approve Screen Recording again by hand.
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+IDENTITY="Apple Development: ben@flow-master.ai (QH2H9G2LK5)"
+BUNDLE_ID="ai.flowmaster.shotdeck"
+APP_BUNDLE="${ROOT}/.build/Shotdeck.app"
+
+SKIP_SIGN=0
+for arg in "$@"; do
+    case "${arg}" in
+        --skip-sign)
+            SKIP_SIGN=1
+            ;;
+        *)
+            echo "Unknown argument: ${arg}" >&2
+            echo "Usage: $0 [--skip-sign]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+echo "==> Building Shotdeck (release)"
+swift build -c release --product Shotdeck
+
+BIN_PATH="$(swift build -c release --product Shotdeck --show-bin-path)/Shotdeck"
+if [[ ! -x "${BIN_PATH}" ]]; then
+    echo "Release binary not found at ${BIN_PATH}" >&2
+    exit 1
+fi
+
+echo "==> Assembling ${APP_BUNDLE}"
+rm -rf "${APP_BUNDLE}"
+mkdir -p "${APP_BUNDLE}/Contents/MacOS"
+mkdir -p "${APP_BUNDLE}/Contents/Resources"
+cp "${BIN_PATH}" "${APP_BUNDLE}/Contents/MacOS/Shotdeck"
+chmod +x "${APP_BUNDLE}/Contents/MacOS/Shotdeck"
+cp "${ROOT}/Info.plist" "${APP_BUNDLE}/Contents/Info.plist"
+
+if [[ "${SKIP_SIGN}" -eq 1 ]]; then
+    echo
+    echo "************************************************************************"
+    echo "WARNING: --skip-sign was used. This app is UNSIGNED."
+    echo "The resulting app will trigger a fresh Screen Recording prompt and must"
+    echo "not be handed to the user."
+    echo "************************************************************************"
+    echo
+else
+    if ! security find-identity -v -p codesigning | grep -Fq "${IDENTITY}"; then
+        echo "The codesigning identity '${IDENTITY}' is not in this shell's keychain search list." >&2
+        echo "The login keychain is not reachable from this shell." >&2
+        echo "Run this script from a normal login session so the app can be signed." >&2
+        echo "Refusing to produce an unsigned app." >&2
+        exit 1
+    fi
+
+    echo "==> Signing ${APP_BUNDLE}"
+    codesign --force --options runtime \
+        --sign "${IDENTITY}" \
+        --identifier "${BUNDLE_ID}" \
+        "${APP_BUNDLE}"
+fi
+
+echo
+echo "App path: ${APP_BUNDLE}"
+echo "Launch with: open ${APP_BUNDLE}"