@scalebun/react-native 1.0.0 → 1.0.2

package/ios/Outbox/NativeOutbox.swift

@@ -1,598 +1,598 @@
-import Foundation
-
-/// Native file-based replay outbox (durable; survives app restart / process kill).
-/// Swift mirror of the Android `NativeOutbox.kt`.
-///
-/// Layout:
-///   <root>/sessions/<sessionId>/
-///     manifest.json
-///     frames/{pending,uploading,failed,dead}/<frameId>.{webp|jpg} + <frameId>.json
-///     events|logs|network|errors|performance/{pending,uploading,failed,dead}/
-///       segment-NNNNNN.jsonl + segment-NNNNNN.meta.json
-///
-/// Durability rules:
-///  - Atomic writes only: write `<name>.tmp` then rename. A partial file never
-///    becomes a valid queue item.
-///  - For a frame, the metadata `.json` is the COMMIT MARKER: image written/renamed
-///    first, then `.json`. An image with no sibling `.json` is an orphan, swept on
-///    recovery, never uploaded.
-///  - Telemetry appends to an OPEN segment (`segment-current.jsonl`); closed (renamed
-///    to `segment-NNNNNN.jsonl` + `.meta.json`) on count/byte threshold or flush.
-///    Only CLOSED segments upload.
-///  - On startup, `uploading/*` moves back to `pending/*`.
-///
-/// All disk mutation is serialized on `lock` (a serial queue) so the bridge, capture
-/// and uploader threads never race a rename.
-final class NativeOutbox {
-
-    static let FRAMES = "frames"
-    static let TELEMETRY_LANES = ["events", "logs", "network", "errors", "performance"]
-    private static let OPEN_SEGMENT = "segment-current.jsonl"
-    private static let STATES = ["pending", "uploading", "failed", "dead"]
-
-    /// Diagnostic counters (process-global, observable — section 3/§Privacy).
-    /// `maskFailureDropCount`: frames discarded at capture time because masking could
-    /// not be resolved (fail-closed). `maskPolicyDropCount`: committed frames deleted
-    /// by recover() for masked=false under a mask-required policy.
-    static var maskFailureDropCount = 0
-    static var maskPolicyDropCount = 0
-
-    private let lock = DispatchQueue(label: "com.scalebun.replaysdk.outbox")
-    private let fm = FileManager.default
-    private let maxBytes: Int64
-    private let maxAgeMs: Int64
-    let root: URL
-
-    init(maxBytes: Int64, maxAgeMs: Int64) {
-        self.maxBytes = maxBytes
-        self.maxAgeMs = maxAgeMs
-        self.root = NativeOutbox.resolveRoot()
-    }
-
-    /// Library/Application Support/ScaleBun/Outbox, excluded from iCloud/iTunes backup
-    /// (screenshots must NOT be in cloud backup). Falls back to a temp dir if needed.
-    private static func resolveRoot() -> URL {
-        let fm = FileManager.default
-        let base = (try? fm.url(for: .applicationSupportDirectory, in: .userDomainMask,
-                                appropriateFor: nil, create: true))
-            ?? fm.temporaryDirectory
-        var dir = base.appendingPathComponent("ScaleBun", isDirectory: true)
-            .appendingPathComponent("Outbox", isDirectory: true)
-        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
-        var values = URLResourceValues()
-        values.isExcludedFromBackup = true
-        try? dir.setResourceValues(values)
-        return dir
-    }
-
-    // ─── Session dirs ───────────────────────────────────────────────────
-
-    private func sessionDir(_ sessionId: String) -> URL {
-        return root.appendingPathComponent("sessions", isDirectory: true)
-            .appendingPathComponent(sessionId, isDirectory: true)
-    }
-
-    private func laneDir(_ sessionId: String, _ lane: String, _ state: String) -> URL {
-        let dir = sessionDir(sessionId).appendingPathComponent(lane, isDirectory: true)
-            .appendingPathComponent(state, isDirectory: true)
-        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
-        return dir
-    }
-
-    func initSession(_ sessionId: String, _ screenName: String) {
-        lock.sync {
-            let dir = sessionDir(sessionId)
-            for lane in [NativeOutbox.FRAMES] + NativeOutbox.TELEMETRY_LANES {
-                for state in NativeOutbox.STATES {
-                    let d = dir.appendingPathComponent(lane, isDirectory: true)
-                        .appendingPathComponent(state, isDirectory: true)
-                    try? fm.createDirectory(at: d, withIntermediateDirectories: true)
-                }
-            }
-            let manifest = dir.appendingPathComponent("manifest.json")
-            if !fm.fileExists(atPath: manifest.path) {
-                let obj: [String: Any] = [
-                    "sessionId": sessionId,
-                    "screenName": screenName,
-                    "startedAt": nowMs(),
-                    "schema": 1,
-                ]
-                atomicWrite(manifest, jsonData(obj))
-            }
-        }
-    }
-
-    // ─── Frames ─────────────────────────────────────────────────────────
-
-    /// Persist a captured frame: image bytes first (renamed into place), then the
-    /// metadata json as the commit marker. Returns the metadata path, or nil.
-    func writeFrame(_ meta: [String: Any], _ bytes: Data) -> String? {
-        return lock.sync {
-            guard let sessionId = meta["sessionId"] as? String,
-                  let frameId = meta["frameId"] as? String else { return nil }
-            let format = (meta["format"] as? String) ?? "webp"
-            let ext = format == "jpeg" ? "jpg" : (format == "avif" ? "avif" : "webp")
-            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
-            let imageFile = pending.appendingPathComponent("\(frameId).\(ext)")
-            guard atomicWrite(imageFile, bytes) else { return nil }
-            var m = meta
-            m["localFile"] = imageFile.lastPathComponent
-            m["attemptCount"] = 0
-            m["nextRetryAt"] = 0
-            let metaFile = pending.appendingPathComponent("\(frameId).json")
-            guard atomicWrite(metaFile, jsonData(m)) else { return nil }
-            return metaFile.path
-        }
-    }
-
-    /// Staged frame write — IMAGE ONLY (no metadata json). Invisible to the uploader
-    /// (which lists `.json` metas) until `commitFrame` lands the meta. Lets the JS
-    /// orchestrator decide keyframe/delta + change-detection before the frame becomes
-    /// uploadable. A staged image with no sibling `.json` is swept as an orphan on the
-    /// next `recover()`. Returns the image filename, or nil on failure.
-    func writeFrameImage(_ sessionId: String, _ frameId: String, _ format: String, _ bytes: Data) -> String? {
-        return lock.sync {
-            let ext = format == "jpeg" ? "jpg" : (format == "avif" ? "avif" : "webp")
-            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
-            let imageFile = pending.appendingPathComponent("\(frameId).\(ext)")
-            guard atomicWrite(imageFile, bytes) else { return nil }
-            return imageFile.lastPathComponent
-        }
-    }
-
-    /// Commit a previously staged frame: write the metadata json (upload marker)
-    /// carrying the JS-authoritative sequenceNumber/frameType/baseFrameId. Returns the
-    /// meta path, or nil if the staged image is missing.
-    func commitFrame(_ meta: [String: Any]) -> String? {
-        return lock.sync {
-            guard let sessionId = meta["sessionId"] as? String,
-                  let frameId = meta["frameId"] as? String else { return nil }
-            let format = (meta["format"] as? String) ?? "webp"
-            let ext = format == "jpeg" ? "jpg" : (format == "avif" ? "avif" : "webp")
-            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
-            let imageFile = pending.appendingPathComponent("\(frameId).\(ext)")
-            guard fm.fileExists(atPath: imageFile.path) else { return nil }
-            var m = meta
-            m["localFile"] = imageFile.lastPathComponent
-            m["attemptCount"] = 0
-            m["nextRetryAt"] = 0
-            let metaFile = pending.appendingPathComponent("\(frameId).json")
-            guard atomicWrite(metaFile, jsonData(m)) else { return nil }
-            return metaFile.path
-        }
-    }
-
-    /// Discard a staged frame the JS orchestrator suppressed: delete image + any meta.
-    func discardFrame(_ sessionId: String, _ frameId: String) {
-        lock.sync {
-            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
-            for f in listFiles(pending) where f.deletingPathExtension().lastPathComponent == frameId {
-                try? fm.removeItem(at: f)
-            }
-        }
-    }
-
-    // ─── Telemetry (JSONL segments) ─────────────────────────────────────
-
-    func appendTelemetry(_ sessionId: String, _ lane: String, _ records: [[String: Any]],
-                         _ flushCount: Int, _ maxSegBytes: Int) {
-        lock.sync {
-            if records.isEmpty { return }
-            let pending = laneDir(sessionId, lane, "pending")
-            let open = pending.appendingPathComponent(NativeOutbox.OPEN_SEGMENT)
-            var blob = Data()
-            for r in records {
-                blob.append(jsonData(r))
-                blob.append(0x0A) // '\n'
-            }
-            appendBytes(open, blob)
-            let lines = countLines(open)
-            let size = fileSize(open)
-            if lines >= flushCount || size >= Int64(maxSegBytes) {
-                closeSegment(sessionId, lane)
-            }
-        }
-    }
-
-    func closeAllOpenSegments(_ sessionId: String) {
-        lock.sync {
-            for lane in NativeOutbox.TELEMETRY_LANES { closeSegment(sessionId, lane) }
-        }
-    }
-
-    /// Caller must hold `lock`.
-    private func closeSegment(_ sessionId: String, _ lane: String) {
-        let pending = laneDir(sessionId, lane, "pending")
-        let open = pending.appendingPathComponent(NativeOutbox.OPEN_SEGMENT)
-        if !fm.fileExists(atPath: open.path) || fileSize(open) == 0 { return }
-        let seq = nextSegmentSeq(pending)
-        let name = String(format: "segment-%06d", seq)
-        let finalFile = pending.appendingPathComponent("\(name).jsonl")
-        do {
-            try fm.moveItem(at: open, to: finalFile)
-        } catch {
-            ReplayLogger.warn("outbox.closeSegment rename failed: \(error.localizedDescription)")
-            return
-        }
-        let meta: [String: Any] = [
-            "sessionId": sessionId,
-            "lane": lane,
-            "segment": name,
-            "lines": countLines(finalFile),
-            "bytes": fileSize(finalFile),
-            "closedAt": nowMs(),
-            "attemptCount": 0,
-            "nextRetryAt": 0,
-        ]
-        atomicWrite(pending.appendingPathComponent("\(name).meta.json"), jsonData(meta))
-    }
-
-    private func nextSegmentSeq(_ dir: URL) -> Int {
-        let files = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
-        var maxN = 0
-        for f in files where f.hasPrefix("segment-") && f.hasSuffix(".jsonl") {
-            let mid = f.dropFirst("segment-".count).dropLast(".jsonl".count)
-            if let n = Int(mid), n > maxN { maxN = n }
-        }
-        return maxN + 1
-    }
-
-    // ─── Queue listing (for the uploader) ───────────────────────────────
-
-    func listSessionIds() -> [String] {
-        return lock.sync {
-            let dir = root.appendingPathComponent("sessions", isDirectory: true)
-            let names = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
-            return names.filter { isDir(dir.appendingPathComponent($0)) }
-        }
-    }
-
-    func dueFrameMetas(_ sessionId: String, _ now: Int64) -> [URL] {
-        return lock.sync {
-            listFiles(laneDir(sessionId, NativeOutbox.FRAMES, "pending"))
-                .filter { $0.lastPathComponent.hasSuffix(".json") && isDue($0, now) }
-        }
-    }
-
-    func dueSegments(_ sessionId: String, _ lane: String, _ now: Int64) -> [URL] {
-        return lock.sync {
-            listFiles(laneDir(sessionId, lane, "pending"))
-                .filter { $0.lastPathComponent.hasSuffix(".meta.json") && isDue($0, now) }
-        }
-    }
-
-    private func isDue(_ metaFile: URL, _ now: Int64) -> Bool {
-        guard let obj = readJson(metaFile) else { return true }
-        return (obj["nextRetryAt"] as? Int64 ?? int64(obj["nextRetryAt"])) <= now
-    }
-
-    // ─── State transitions (atomic via rename) ──────────────────────────
-
-    func moveFrameToUploading(_ meta: URL) -> URL? {
-        return lock.sync { moveFramePair(meta, "uploading") }
-    }
-
-    func frameImageFor(_ metaFile: URL) -> URL? {
-        guard let obj = readJson(metaFile), let name = obj["localFile"] as? String else { return nil }
-        return metaFile.deletingLastPathComponent().appendingPathComponent(name)
-    }
-
-    func deleteFrame(_ metaFile: URL) {
-        lock.sync {
-            if let img = frameImageFor(metaFile) { try? fm.removeItem(at: img) }
-            try? fm.removeItem(at: metaFile)
-        }
-    }
-
-    func failFrame(_ metaFile: URL, _ maxAttempts: Int, _ backoffMs: Int64) {
-        // Back-compat shim → treat as a server-transient failure.
-        recordServerFailure(metaFile, isFrame: true, attemptCap: maxAttempts, backoffMs: backoffMs)
-    }
-
-    // ─── Network-aware failure recording (two-counter model, section 6) ──────
-    //
-    // `networkFailureCount` — incremented on NETWORK_UNAVAILABLE; NEVER reaches dead.
-    // `serverAttemptCount`  — incremented on SERVER_TRANSIENT/SERVER_PERMANENT; the
-    //                          only counter that can reach the dead cap. A claimed item
-    //                          lives in `uploading/`; below it is moved back to
-    //                          `pending/` (retryable) or `dead/` (terminal).
-
-    /// NETWORK_UNAVAILABLE: keep fully retryable forever, no progress toward dead.
-    func recordNetworkFailure(_ metaFile: URL, isFrame: Bool, retryIntervalMs: Int64) {
-        lock.sync {
-            guard var obj = readJson(metaFile) else { return }
-            obj["networkFailureCount"] = int(obj["networkFailureCount"]) + 1
-            obj["nextRetryAt"] = nowMs() + retryIntervalMs
-            obj["lastOutcome"] = "NETWORK_UNAVAILABLE"
-            atomicWrite(metaFile, jsonData(obj))
-            requeueToPending(metaFile, isFrame)
-        }
-    }
-
-    /// SERVER_TRANSIENT / SERVER_PERMANENT: bump serverAttemptCount; dead at `attemptCap`.
-    func recordServerFailure(_ metaFile: URL, isFrame: Bool, attemptCap: Int, backoffMs: Int64,
-                             permanent: Bool = false, statusCode: Int = 0, bodySnippet: String = "") {
-        lock.sync {
-            guard var obj = readJson(metaFile) else { return }
-            let attempts = max(int(obj["serverAttemptCount"]), int(obj["attemptCount"])) + 1
-            obj["serverAttemptCount"] = attempts
-            obj["attemptCount"] = attempts // keep legacy field in sync for observability
-            obj["nextRetryAt"] = nowMs() + backoffMs
-            obj["lastOutcome"] = permanent ? "SERVER_PERMANENT" : "SERVER_TRANSIENT"
-            if statusCode != 0 { obj["lastStatus"] = statusCode }
-            if !bodySnippet.isEmpty { obj["lastError"] = String(bodySnippet.prefix(280)) }
-            atomicWrite(metaFile, jsonData(obj))
-            if attempts >= attemptCap {
-                if permanent {
-                    ReplayLogger.warn("outbox: poison batch -> dead (status=\(statusCode)): \(bodySnippet.prefix(120))")
-                }
-                _ = isFrame ? moveFramePair(metaFile, "dead") : moveSegmentTriple(metaFile, "dead")
-            } else {
-                requeueToPending(metaFile, isFrame)
-            }
-        }
-    }
-
-    /// Caller holds `lock`.
-    private func requeueToPending(_ metaFile: URL, _ isFrame: Bool) {
-        guard currentStateOf(metaFile) == "uploading" else { return }
-        _ = isFrame ? moveFramePair(metaFile, "pending") : moveSegmentTriple(metaFile, "pending")
-    }
-
-    private func currentStateOf(_ url: URL) -> String {
-        url.deletingLastPathComponent().lastPathComponent
-    }
-
-    func moveSegmentToUploading(_ metaFile: URL) -> URL? {
-        return lock.sync { moveSegmentTriple(metaFile, "uploading") }
-    }
-
-    func segmentDataFor(_ metaFile: URL) -> URL? {
-        guard let obj = readJson(metaFile), let seg = obj["segment"] as? String else { return nil }
-        return metaFile.deletingLastPathComponent().appendingPathComponent("\(seg).jsonl")
-    }
-
-    func deleteSegment(_ metaFile: URL) {
-        lock.sync {
-            if let data = segmentDataFor(metaFile) { try? fm.removeItem(at: data) }
-            try? fm.removeItem(at: metaFile)
-        }
-    }
-
-    func failSegment(_ metaFile: URL, _ maxAttempts: Int, _ backoffMs: Int64) {
-        // Back-compat shim → treat as a server-transient failure.
-        recordServerFailure(metaFile, isFrame: false, attemptCap: maxAttempts, backoffMs: backoffMs)
-    }
-
-    // ─── Recovery / cleanup ─────────────────────────────────────────────
-
-    func recover(maskRequired: Bool = false) {
-        lock.sync {
-            for sessionId in listSessionIdsLocked() {
-                requeueDir(laneDir(sessionId, NativeOutbox.FRAMES, "uploading"),
-                           laneDir(sessionId, NativeOutbox.FRAMES, "pending"))
-                let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
-                for f in listFiles(pending) {
-                    let n = f.lastPathComponent
-                    if n.hasSuffix(".json") || n.hasSuffix(".tmp") { continue }
-                    let base = (n as NSString).deletingPathExtension
-                    if !fm.fileExists(atPath: pending.appendingPathComponent("\(base).json").path) {
-                        try? fm.removeItem(at: f)
-                    }
-                }
-                // Mask-policy enforcement (section 3): delete any committed frame with
-                // masked=false under a mask-required policy — never resurrect/upload it.
-                if maskRequired {
-                    for meta in listFiles(pending) where meta.lastPathComponent.hasSuffix(".json") {
-                        let isMasked = (readJson(meta)?["masked"] as? Bool) ?? false
-                        if !isMasked {
-                            if let img = frameImageFor(meta) { try? fm.removeItem(at: img) }
-                            try? fm.removeItem(at: meta)
-                            NativeOutbox.maskPolicyDropCount += 1
-                        }
-                    }
-                }
-                for lane in NativeOutbox.TELEMETRY_LANES {
-                    requeueDir(laneDir(sessionId, lane, "uploading"),
-                               laneDir(sessionId, lane, "pending"))
-                }
-                sweepTmp(sessionDir(sessionId))
-            }
-            enforceLimitsLocked()
-        }
-    }
-
-    func enforceLimits() { lock.sync { enforceLimitsLocked() } }
-
-    func totalBytes() -> Int64 { return lock.sync { dirSize(root) } }
-
-    // ─── helpers (lock held by caller where noted) ──────────────────────
-
-    private func enforceLimitsLocked() {
-        let sessionsRoot = root.appendingPathComponent("sessions", isDirectory: true)
-        let now = nowMs()
-        for dir in listDirs(sessionsRoot) {
-            if now - manifestStartedAt(dir) > maxAgeMs { try? fm.removeItem(at: dir) }
-        }
-        var total = dirSize(root)
-        if total <= maxBytes { return }
-        let live = listDirs(sessionsRoot).sorted { manifestStartedAt($0) < manifestStartedAt($1) }
-        for dir in live {
-            if total <= maxBytes { break }
-            let sz = dirSize(dir)
-            try? fm.removeItem(at: dir)
-            total -= sz
-        }
-    }
-
-    private func listSessionIdsLocked() -> [String] {
-        let dir = root.appendingPathComponent("sessions", isDirectory: true)
-        let names = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
-        return names.filter { isDir(dir.appendingPathComponent($0)) }
-    }
-
-    private func moveFramePair(_ metaFile: URL, _ to: String) -> URL? {
-        let sessionId = sessionIdOf(metaFile)
-        let img = frameImageFor(metaFile)
-        let destDir = laneDir(sessionId, NativeOutbox.FRAMES, to)
-        if let img = img, fm.fileExists(atPath: img.path) {
-            try? fm.moveItem(at: img, to: destDir.appendingPathComponent(img.lastPathComponent))
-        }
-        let destMeta = destDir.appendingPathComponent(metaFile.lastPathComponent)
-        do { try fm.moveItem(at: metaFile, to: destMeta); return destMeta }
-        catch { return nil }
-    }
-
-    private func moveSegmentTriple(_ metaFile: URL, _ to: String) -> URL? {
-        let sessionId = sessionIdOf(metaFile)
-        let lane = laneOf(metaFile)
-        let data = segmentDataFor(metaFile)
-        let destDir = laneDir(sessionId, lane, to)
-        if let data = data, fm.fileExists(atPath: data.path) {
-            try? fm.moveItem(at: data, to: destDir.appendingPathComponent(data.lastPathComponent))
-        }
-        let destMeta = destDir.appendingPathComponent(metaFile.lastPathComponent)
-        do { try fm.moveItem(at: metaFile, to: destMeta); return destMeta }
-        catch { return nil }
-    }
-
-    private func requeueDir(_ fromDir: URL, _ toDir: URL) {
-        for f in listFiles(fromDir) {
-            if f.lastPathComponent.hasSuffix(".tmp") { try? fm.removeItem(at: f); continue }
-            try? fm.moveItem(at: f, to: toDir.appendingPathComponent(f.lastPathComponent))
-        }
-    }
-
-    private func sweepTmp(_ dir: URL) {
-        guard let en = fm.enumerator(at: dir, includingPropertiesForKeys: nil) else { return }
-        for case let url as URL in en where url.lastPathComponent.hasSuffix(".tmp") {
-            try? fm.removeItem(at: url)
-        }
-    }
-
-    private func laneOf(_ url: URL) -> String {
-        url.deletingLastPathComponent().deletingLastPathComponent().lastPathComponent
-    }
-    private func sessionIdOf(_ url: URL) -> String {
-        url.deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent().lastPathComponent
-    }
-
-    private func manifestStartedAt(_ sessionDir: URL) -> Int64 {
-        guard let obj = readJson(sessionDir.appendingPathComponent("manifest.json")) else { return 0 }
-        return int64(obj["startedAt"])
-    }
-
-    // ─── low-level fs ───────────────────────────────────────────────────
-
-    private func isDir(_ url: URL) -> Bool {
-        var isDir: ObjCBool = false
-        return fm.fileExists(atPath: url.path, isDirectory: &isDir) && isDir.boolValue
-    }
-
-    private func listFiles(_ dir: URL) -> [URL] {
-        return ((try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)) ?? [])
-    }
-
-    private func listDirs(_ dir: URL) -> [URL] {
-        return listFiles(dir).filter { isDir($0) }
-    }
-
-    private func fileSize(_ url: URL) -> Int64 {
-        return int64((try? fm.attributesOfItem(atPath: url.path)[.size]) as Any?)
-    }
-
-    private func dirSize(_ dir: URL) -> Int64 {
-        guard let en = fm.enumerator(at: dir, includingPropertiesForKeys: [.fileSizeKey]) else { return 0 }
-        var total: Int64 = 0
-        for case let url as URL in en {
-            let v = try? url.resourceValues(forKeys: [.fileSizeKey])
-            total += Int64(v?.fileSize ?? 0)
-        }
-        return total
-    }
-
-    private func countLines(_ url: URL) -> Int {
-        guard let data = try? Data(contentsOf: url) else { return 0 }
-        var n = 0
-        for b in data where b == 0x0A { n += 1 }
-        return n
-    }
-
-    private func appendBytes(_ url: URL, _ data: Data) {
-        if let h = try? FileHandle(forWritingTo: url) {
-            defer { try? h.close() }
-            _ = try? h.seekToEnd()
-            try? h.write(contentsOf: data)
-        } else {
-            try? data.write(to: url)
-        }
-    }
-
-    /// Write to `<file>.tmp`, F_FULLFSYNC the file, atomically rename to the final
-    /// path, then fsync the PARENT DIRECTORY. On iOS plain `fsync` does NOT force a
-    /// hardware flush, so `F_FULLFSYNC` is required; and the rename is not durable
-    /// until the directory entry itself is flushed (section 5).
-    @discardableResult
-    private func atomicWrite(_ file: URL, _ data: Data) -> Bool {
-        let dir = file.deletingLastPathComponent()
-        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
-        let tmp = dir.appendingPathComponent(file.lastPathComponent + ".tmp")
-        do {
-            try data.write(to: tmp)
-            fullFsyncFile(tmp)
-            if fm.fileExists(atPath: file.path) { try? fm.removeItem(at: file) }
-            try fm.moveItem(at: tmp, to: file)
-            fsyncDir(dir)
-            return true
-        } catch {
-            try? fm.removeItem(at: tmp)
-            ReplayLogger.warn("outbox.atomicWrite failed: \(error.localizedDescription)")
-            return false
-        }
-    }
-
-    /// F_FULLFSYNC the file's bytes to the storage medium (NOT plain fsync on iOS).
-    private func fullFsyncFile(_ url: URL) {
-        let fd = open(url.path, O_WRONLY)
-        if fd >= 0 {
-            _ = fcntl(fd, F_FULLFSYNC)
-            close(fd)
-        }
-    }
-
-    /// Flush the directory entry so a freshly-renamed file survives a hard kill.
-    private func fsyncDir(_ dir: URL) {
-        let fd = open(dir.path, O_RDONLY)
-        if fd >= 0 {
-            if fcntl(fd, F_FULLFSYNC) == -1 { _ = fsync(fd) }
-            close(fd)
-        }
-    }
-
-    // ─── json ───────────────────────────────────────────────────────────
-
-    private func jsonData(_ obj: [String: Any]) -> Data {
-        return (try? JSONSerialization.data(withJSONObject: obj)) ?? Data("{}".utf8)
-    }
-
-    private func readJson(_ url: URL) -> [String: Any]? {
-        guard let data = try? Data(contentsOf: url),
-              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
-        return obj
-    }
-
-    private func nowMs() -> Int64 { Int64(Date().timeIntervalSince1970 * 1000) }
-
-    private func int(_ v: Any?) -> Int {
-        if let n = v as? Int { return n }
-        if let n = v as? NSNumber { return n.intValue }
-        return 0
-    }
-
-    private func int64(_ v: Any?) -> Int64 {
-        if let n = v as? Int64 { return n }
-        if let n = v as? Int { return Int64(n) }
-        if let n = v as? NSNumber { return n.int64Value }
-        return 0
-    }
-}
+import Foundation
+
+/// Native file-based replay outbox (durable; survives app restart / process kill).
+/// Swift mirror of the Android `NativeOutbox.kt`.
+///
+/// Layout:
+///   <root>/sessions/<sessionId>/
+///     manifest.json
+///     frames/{pending,uploading,failed,dead}/<frameId>.{webp|jpg} + <frameId>.json
+///     events|logs|network|errors|performance/{pending,uploading,failed,dead}/
+///       segment-NNNNNN.jsonl + segment-NNNNNN.meta.json
+///
+/// Durability rules:
+///  - Atomic writes only: write `<name>.tmp` then rename. A partial file never
+///    becomes a valid queue item.
+///  - For a frame, the metadata `.json` is the COMMIT MARKER: image written/renamed
+///    first, then `.json`. An image with no sibling `.json` is an orphan, swept on
+///    recovery, never uploaded.
+///  - Telemetry appends to an OPEN segment (`segment-current.jsonl`); closed (renamed
+///    to `segment-NNNNNN.jsonl` + `.meta.json`) on count/byte threshold or flush.
+///    Only CLOSED segments upload.
+///  - On startup, `uploading/*` moves back to `pending/*`.
+///
+/// All disk mutation is serialized on `lock` (a serial queue) so the bridge, capture
+/// and uploader threads never race a rename.
+final class NativeOutbox {
+
+    static let FRAMES = "frames"
+    static let TELEMETRY_LANES = ["events", "logs", "network", "errors", "performance"]
+    private static let OPEN_SEGMENT = "segment-current.jsonl"
+    private static let STATES = ["pending", "uploading", "failed", "dead"]
+
+    /// Diagnostic counters (process-global, observable — section 3/§Privacy).
+    /// `maskFailureDropCount`: frames discarded at capture time because masking could
+    /// not be resolved (fail-closed). `maskPolicyDropCount`: committed frames deleted
+    /// by recover() for masked=false under a mask-required policy.
+    static var maskFailureDropCount = 0
+    static var maskPolicyDropCount = 0
+
+    private let lock = DispatchQueue(label: "com.scalebun.replaysdk.outbox")
+    private let fm = FileManager.default
+    private let maxBytes: Int64
+    private let maxAgeMs: Int64
+    let root: URL
+
+    init(maxBytes: Int64, maxAgeMs: Int64) {
+        self.maxBytes = maxBytes
+        self.maxAgeMs = maxAgeMs
+        self.root = NativeOutbox.resolveRoot()
+    }
+
+    /// Library/Application Support/ScaleBun/Outbox, excluded from iCloud/iTunes backup
+    /// (screenshots must NOT be in cloud backup). Falls back to a temp dir if needed.
+    private static func resolveRoot() -> URL {
+        let fm = FileManager.default
+        let base = (try? fm.url(for: .applicationSupportDirectory, in: .userDomainMask,
+                                appropriateFor: nil, create: true))
+            ?? fm.temporaryDirectory
+        var dir = base.appendingPathComponent("ScaleBun", isDirectory: true)
+            .appendingPathComponent("Outbox", isDirectory: true)
+        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        try? dir.setResourceValues(values)
+        return dir
+    }
+
+    // ─── Session dirs ───────────────────────────────────────────────────
+
+    private func sessionDir(_ sessionId: String) -> URL {
+        return root.appendingPathComponent("sessions", isDirectory: true)
+            .appendingPathComponent(sessionId, isDirectory: true)
+    }
+
+    private func laneDir(_ sessionId: String, _ lane: String, _ state: String) -> URL {
+        let dir = sessionDir(sessionId).appendingPathComponent(lane, isDirectory: true)
+            .appendingPathComponent(state, isDirectory: true)
+        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    func initSession(_ sessionId: String, _ screenName: String) {
+        lock.sync {
+            let dir = sessionDir(sessionId)
+            for lane in [NativeOutbox.FRAMES] + NativeOutbox.TELEMETRY_LANES {
+                for state in NativeOutbox.STATES {
+                    let d = dir.appendingPathComponent(lane, isDirectory: true)
+                        .appendingPathComponent(state, isDirectory: true)
+                    try? fm.createDirectory(at: d, withIntermediateDirectories: true)
+                }
+            }
+            let manifest = dir.appendingPathComponent("manifest.json")
+            if !fm.fileExists(atPath: manifest.path) {
+                let obj: [String: Any] = [
+                    "sessionId": sessionId,
+                    "screenName": screenName,
+                    "startedAt": nowMs(),
+                    "schema": 1,
+                ]
+                atomicWrite(manifest, jsonData(obj))
+            }
+        }
+    }
+
+    // ─── Frames ─────────────────────────────────────────────────────────
+
+    /// Persist a captured frame: image bytes first (renamed into place), then the
+    /// metadata json as the commit marker. Returns the metadata path, or nil.
+    func writeFrame(_ meta: [String: Any], _ bytes: Data) -> String? {
+        return lock.sync {
+            guard let sessionId = meta["sessionId"] as? String,
+                  let frameId = meta["frameId"] as? String else { return nil }
+            let format = (meta["format"] as? String) ?? "webp"
+            let ext = format == "jpeg" ? "jpg" : (format == "avif" ? "avif" : "webp")
+            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
+            let imageFile = pending.appendingPathComponent("\(frameId).\(ext)")
+            guard atomicWrite(imageFile, bytes) else { return nil }
+            var m = meta
+            m["localFile"] = imageFile.lastPathComponent
+            m["attemptCount"] = 0
+            m["nextRetryAt"] = 0
+            let metaFile = pending.appendingPathComponent("\(frameId).json")
+            guard atomicWrite(metaFile, jsonData(m)) else { return nil }
+            return metaFile.path
+        }
+    }
+
+    /// Staged frame write — IMAGE ONLY (no metadata json). Invisible to the uploader
+    /// (which lists `.json` metas) until `commitFrame` lands the meta. Lets the JS
+    /// orchestrator decide keyframe/delta + change-detection before the frame becomes
+    /// uploadable. A staged image with no sibling `.json` is swept as an orphan on the
+    /// next `recover()`. Returns the image filename, or nil on failure.
+    func writeFrameImage(_ sessionId: String, _ frameId: String, _ format: String, _ bytes: Data) -> String? {
+        return lock.sync {
+            let ext = format == "jpeg" ? "jpg" : (format == "avif" ? "avif" : "webp")
+            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
+            let imageFile = pending.appendingPathComponent("\(frameId).\(ext)")
+            guard atomicWrite(imageFile, bytes) else { return nil }
+            return imageFile.lastPathComponent
+        }
+    }
+
+    /// Commit a previously staged frame: write the metadata json (upload marker)
+    /// carrying the JS-authoritative sequenceNumber/frameType/baseFrameId. Returns the
+    /// meta path, or nil if the staged image is missing.
+    func commitFrame(_ meta: [String: Any]) -> String? {
+        return lock.sync {
+            guard let sessionId = meta["sessionId"] as? String,
+                  let frameId = meta["frameId"] as? String else { return nil }
+            let format = (meta["format"] as? String) ?? "webp"
+            let ext = format == "jpeg" ? "jpg" : (format == "avif" ? "avif" : "webp")
+            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
+            let imageFile = pending.appendingPathComponent("\(frameId).\(ext)")
+            guard fm.fileExists(atPath: imageFile.path) else { return nil }
+            var m = meta
+            m["localFile"] = imageFile.lastPathComponent
+            m["attemptCount"] = 0
+            m["nextRetryAt"] = 0
+            let metaFile = pending.appendingPathComponent("\(frameId).json")
+            guard atomicWrite(metaFile, jsonData(m)) else { return nil }
+            return metaFile.path
+        }
+    }
+
+    /// Discard a staged frame the JS orchestrator suppressed: delete image + any meta.
+    func discardFrame(_ sessionId: String, _ frameId: String) {
+        lock.sync {
+            let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
+            for f in listFiles(pending) where f.deletingPathExtension().lastPathComponent == frameId {
+                try? fm.removeItem(at: f)
+            }
+        }
+    }
+
+    // ─── Telemetry (JSONL segments) ─────────────────────────────────────
+
+    func appendTelemetry(_ sessionId: String, _ lane: String, _ records: [[String: Any]],
+                         _ flushCount: Int, _ maxSegBytes: Int) {
+        lock.sync {
+            if records.isEmpty { return }
+            let pending = laneDir(sessionId, lane, "pending")
+            let open = pending.appendingPathComponent(NativeOutbox.OPEN_SEGMENT)
+            var blob = Data()
+            for r in records {
+                blob.append(jsonData(r))
+                blob.append(0x0A) // '\n'
+            }
+            appendBytes(open, blob)
+            let lines = countLines(open)
+            let size = fileSize(open)
+            if lines >= flushCount || size >= Int64(maxSegBytes) {
+                closeSegment(sessionId, lane)
+            }
+        }
+    }
+
+    func closeAllOpenSegments(_ sessionId: String) {
+        lock.sync {
+            for lane in NativeOutbox.TELEMETRY_LANES { closeSegment(sessionId, lane) }
+        }
+    }
+
+    /// Caller must hold `lock`.
+    private func closeSegment(_ sessionId: String, _ lane: String) {
+        let pending = laneDir(sessionId, lane, "pending")
+        let open = pending.appendingPathComponent(NativeOutbox.OPEN_SEGMENT)
+        if !fm.fileExists(atPath: open.path) || fileSize(open) == 0 { return }
+        let seq = nextSegmentSeq(pending)
+        let name = String(format: "segment-%06d", seq)
+        let finalFile = pending.appendingPathComponent("\(name).jsonl")
+        do {
+            try fm.moveItem(at: open, to: finalFile)
+        } catch {
+            ReplayLogger.warn("outbox.closeSegment rename failed: \(error.localizedDescription)")
+            return
+        }
+        let meta: [String: Any] = [
+            "sessionId": sessionId,
+            "lane": lane,
+            "segment": name,
+            "lines": countLines(finalFile),
+            "bytes": fileSize(finalFile),
+            "closedAt": nowMs(),
+            "attemptCount": 0,
+            "nextRetryAt": 0,
+        ]
+        atomicWrite(pending.appendingPathComponent("\(name).meta.json"), jsonData(meta))
+    }
+
+    private func nextSegmentSeq(_ dir: URL) -> Int {
+        let files = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
+        var maxN = 0
+        for f in files where f.hasPrefix("segment-") && f.hasSuffix(".jsonl") {
+            let mid = f.dropFirst("segment-".count).dropLast(".jsonl".count)
+            if let n = Int(mid), n > maxN { maxN = n }
+        }
+        return maxN + 1
+    }
+
+    // ─── Queue listing (for the uploader) ───────────────────────────────
+
+    func listSessionIds() -> [String] {
+        return lock.sync {
+            let dir = root.appendingPathComponent("sessions", isDirectory: true)
+            let names = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
+            return names.filter { isDir(dir.appendingPathComponent($0)) }
+        }
+    }
+
+    func dueFrameMetas(_ sessionId: String, _ now: Int64) -> [URL] {
+        return lock.sync {
+            listFiles(laneDir(sessionId, NativeOutbox.FRAMES, "pending"))
+                .filter { $0.lastPathComponent.hasSuffix(".json") && isDue($0, now) }
+        }
+    }
+
+    func dueSegments(_ sessionId: String, _ lane: String, _ now: Int64) -> [URL] {
+        return lock.sync {
+            listFiles(laneDir(sessionId, lane, "pending"))
+                .filter { $0.lastPathComponent.hasSuffix(".meta.json") && isDue($0, now) }
+        }
+    }
+
+    private func isDue(_ metaFile: URL, _ now: Int64) -> Bool {
+        guard let obj = readJson(metaFile) else { return true }
+        return (obj["nextRetryAt"] as? Int64 ?? int64(obj["nextRetryAt"])) <= now
+    }
+
+    // ─── State transitions (atomic via rename) ──────────────────────────
+
+    func moveFrameToUploading(_ meta: URL) -> URL? {
+        return lock.sync { moveFramePair(meta, "uploading") }
+    }
+
+    func frameImageFor(_ metaFile: URL) -> URL? {
+        guard let obj = readJson(metaFile), let name = obj["localFile"] as? String else { return nil }
+        return metaFile.deletingLastPathComponent().appendingPathComponent(name)
+    }
+
+    func deleteFrame(_ metaFile: URL) {
+        lock.sync {
+            if let img = frameImageFor(metaFile) { try? fm.removeItem(at: img) }
+            try? fm.removeItem(at: metaFile)
+        }
+    }
+
+    func failFrame(_ metaFile: URL, _ maxAttempts: Int, _ backoffMs: Int64) {
+        // Back-compat shim → treat as a server-transient failure.
+        recordServerFailure(metaFile, isFrame: true, attemptCap: maxAttempts, backoffMs: backoffMs)
+    }
+
+    // ─── Network-aware failure recording (two-counter model, section 6) ──────
+    //
+    // `networkFailureCount` — incremented on NETWORK_UNAVAILABLE; NEVER reaches dead.
+    // `serverAttemptCount`  — incremented on SERVER_TRANSIENT/SERVER_PERMANENT; the
+    //                          only counter that can reach the dead cap. A claimed item
+    //                          lives in `uploading/`; below it is moved back to
+    //                          `pending/` (retryable) or `dead/` (terminal).
+
+    /// NETWORK_UNAVAILABLE: keep fully retryable forever, no progress toward dead.
+    func recordNetworkFailure(_ metaFile: URL, isFrame: Bool, retryIntervalMs: Int64) {
+        lock.sync {
+            guard var obj = readJson(metaFile) else { return }
+            obj["networkFailureCount"] = int(obj["networkFailureCount"]) + 1
+            obj["nextRetryAt"] = nowMs() + retryIntervalMs
+            obj["lastOutcome"] = "NETWORK_UNAVAILABLE"
+            atomicWrite(metaFile, jsonData(obj))
+            requeueToPending(metaFile, isFrame)
+        }
+    }
+
+    /// SERVER_TRANSIENT / SERVER_PERMANENT: bump serverAttemptCount; dead at `attemptCap`.
+    func recordServerFailure(_ metaFile: URL, isFrame: Bool, attemptCap: Int, backoffMs: Int64,
+                             permanent: Bool = false, statusCode: Int = 0, bodySnippet: String = "") {
+        lock.sync {
+            guard var obj = readJson(metaFile) else { return }
+            let attempts = max(int(obj["serverAttemptCount"]), int(obj["attemptCount"])) + 1
+            obj["serverAttemptCount"] = attempts
+            obj["attemptCount"] = attempts // keep legacy field in sync for observability
+            obj["nextRetryAt"] = nowMs() + backoffMs
+            obj["lastOutcome"] = permanent ? "SERVER_PERMANENT" : "SERVER_TRANSIENT"
+            if statusCode != 0 { obj["lastStatus"] = statusCode }
+            if !bodySnippet.isEmpty { obj["lastError"] = String(bodySnippet.prefix(280)) }
+            atomicWrite(metaFile, jsonData(obj))
+            if attempts >= attemptCap {
+                if permanent {
+                    ReplayLogger.warn("outbox: poison batch -> dead (status=\(statusCode)): \(bodySnippet.prefix(120))")
+                }
+                _ = isFrame ? moveFramePair(metaFile, "dead") : moveSegmentTriple(metaFile, "dead")
+            } else {
+                requeueToPending(metaFile, isFrame)
+            }
+        }
+    }
+
+    /// Caller holds `lock`.
+    private func requeueToPending(_ metaFile: URL, _ isFrame: Bool) {
+        guard currentStateOf(metaFile) == "uploading" else { return }
+        _ = isFrame ? moveFramePair(metaFile, "pending") : moveSegmentTriple(metaFile, "pending")
+    }
+
+    private func currentStateOf(_ url: URL) -> String {
+        url.deletingLastPathComponent().lastPathComponent
+    }
+
+    func moveSegmentToUploading(_ metaFile: URL) -> URL? {
+        return lock.sync { moveSegmentTriple(metaFile, "uploading") }
+    }
+
+    func segmentDataFor(_ metaFile: URL) -> URL? {
+        guard let obj = readJson(metaFile), let seg = obj["segment"] as? String else { return nil }
+        return metaFile.deletingLastPathComponent().appendingPathComponent("\(seg).jsonl")
+    }
+
+    func deleteSegment(_ metaFile: URL) {
+        lock.sync {
+            if let data = segmentDataFor(metaFile) { try? fm.removeItem(at: data) }
+            try? fm.removeItem(at: metaFile)
+        }
+    }
+
+    func failSegment(_ metaFile: URL, _ maxAttempts: Int, _ backoffMs: Int64) {
+        // Back-compat shim → treat as a server-transient failure.
+        recordServerFailure(metaFile, isFrame: false, attemptCap: maxAttempts, backoffMs: backoffMs)
+    }
+
+    // ─── Recovery / cleanup ─────────────────────────────────────────────
+
+    func recover(maskRequired: Bool = false) {
+        lock.sync {
+            for sessionId in listSessionIdsLocked() {
+                requeueDir(laneDir(sessionId, NativeOutbox.FRAMES, "uploading"),
+                           laneDir(sessionId, NativeOutbox.FRAMES, "pending"))
+                let pending = laneDir(sessionId, NativeOutbox.FRAMES, "pending")
+                for f in listFiles(pending) {
+                    let n = f.lastPathComponent
+                    if n.hasSuffix(".json") || n.hasSuffix(".tmp") { continue }
+                    let base = (n as NSString).deletingPathExtension
+                    if !fm.fileExists(atPath: pending.appendingPathComponent("\(base).json").path) {
+                        try? fm.removeItem(at: f)
+                    }
+                }
+                // Mask-policy enforcement (section 3): delete any committed frame with
+                // masked=false under a mask-required policy — never resurrect/upload it.
+                if maskRequired {
+                    for meta in listFiles(pending) where meta.lastPathComponent.hasSuffix(".json") {
+                        let isMasked = (readJson(meta)?["masked"] as? Bool) ?? false
+                        if !isMasked {
+                            if let img = frameImageFor(meta) { try? fm.removeItem(at: img) }
+                            try? fm.removeItem(at: meta)
+                            NativeOutbox.maskPolicyDropCount += 1
+                        }
+                    }
+                }
+                for lane in NativeOutbox.TELEMETRY_LANES {
+                    requeueDir(laneDir(sessionId, lane, "uploading"),
+                               laneDir(sessionId, lane, "pending"))
+                }
+                sweepTmp(sessionDir(sessionId))
+            }
+            enforceLimitsLocked()
+        }
+    }
+
+    func enforceLimits() { lock.sync { enforceLimitsLocked() } }
+
+    func totalBytes() -> Int64 { return lock.sync { dirSize(root) } }
+
+    // ─── helpers (lock held by caller where noted) ──────────────────────
+
+    private func enforceLimitsLocked() {
+        let sessionsRoot = root.appendingPathComponent("sessions", isDirectory: true)
+        let now = nowMs()
+        for dir in listDirs(sessionsRoot) {
+            if now - manifestStartedAt(dir) > maxAgeMs { try? fm.removeItem(at: dir) }
+        }
+        var total = dirSize(root)
+        if total <= maxBytes { return }
+        let live = listDirs(sessionsRoot).sorted { manifestStartedAt($0) < manifestStartedAt($1) }
+        for dir in live {
+            if total <= maxBytes { break }
+            let sz = dirSize(dir)
+            try? fm.removeItem(at: dir)
+            total -= sz
+        }
+    }
+
+    private func listSessionIdsLocked() -> [String] {
+        let dir = root.appendingPathComponent("sessions", isDirectory: true)
+        let names = (try? fm.contentsOfDirectory(atPath: dir.path)) ?? []
+        return names.filter { isDir(dir.appendingPathComponent($0)) }
+    }
+
+    private func moveFramePair(_ metaFile: URL, _ to: String) -> URL? {
+        let sessionId = sessionIdOf(metaFile)
+        let img = frameImageFor(metaFile)
+        let destDir = laneDir(sessionId, NativeOutbox.FRAMES, to)
+        if let img = img, fm.fileExists(atPath: img.path) {
+            try? fm.moveItem(at: img, to: destDir.appendingPathComponent(img.lastPathComponent))
+        }
+        let destMeta = destDir.appendingPathComponent(metaFile.lastPathComponent)
+        do { try fm.moveItem(at: metaFile, to: destMeta); return destMeta }
+        catch { return nil }
+    }
+
+    private func moveSegmentTriple(_ metaFile: URL, _ to: String) -> URL? {
+        let sessionId = sessionIdOf(metaFile)
+        let lane = laneOf(metaFile)
+        let data = segmentDataFor(metaFile)
+        let destDir = laneDir(sessionId, lane, to)
+        if let data = data, fm.fileExists(atPath: data.path) {
+            try? fm.moveItem(at: data, to: destDir.appendingPathComponent(data.lastPathComponent))
+        }
+        let destMeta = destDir.appendingPathComponent(metaFile.lastPathComponent)
+        do { try fm.moveItem(at: metaFile, to: destMeta); return destMeta }
+        catch { return nil }
+    }
+
+    private func requeueDir(_ fromDir: URL, _ toDir: URL) {
+        for f in listFiles(fromDir) {
+            if f.lastPathComponent.hasSuffix(".tmp") { try? fm.removeItem(at: f); continue }
+            try? fm.moveItem(at: f, to: toDir.appendingPathComponent(f.lastPathComponent))
+        }
+    }
+
+    private func sweepTmp(_ dir: URL) {
+        guard let en = fm.enumerator(at: dir, includingPropertiesForKeys: nil) else { return }
+        for case let url as URL in en where url.lastPathComponent.hasSuffix(".tmp") {
+            try? fm.removeItem(at: url)
+        }
+    }
+
+    private func laneOf(_ url: URL) -> String {
+        url.deletingLastPathComponent().deletingLastPathComponent().lastPathComponent
+    }
+    private func sessionIdOf(_ url: URL) -> String {
+        url.deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent().lastPathComponent
+    }
+
+    private func manifestStartedAt(_ sessionDir: URL) -> Int64 {
+        guard let obj = readJson(sessionDir.appendingPathComponent("manifest.json")) else { return 0 }
+        return int64(obj["startedAt"])
+    }
+
+    // ─── low-level fs ───────────────────────────────────────────────────
+
+    private func isDir(_ url: URL) -> Bool {
+        var isDir: ObjCBool = false
+        return fm.fileExists(atPath: url.path, isDirectory: &isDir) && isDir.boolValue
+    }
+
+    private func listFiles(_ dir: URL) -> [URL] {
+        return ((try? fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)) ?? [])
+    }
+
+    private func listDirs(_ dir: URL) -> [URL] {
+        return listFiles(dir).filter { isDir($0) }
+    }
+
+    private func fileSize(_ url: URL) -> Int64 {
+        return int64((try? fm.attributesOfItem(atPath: url.path)[.size]) as Any?)
+    }
+
+    private func dirSize(_ dir: URL) -> Int64 {
+        guard let en = fm.enumerator(at: dir, includingPropertiesForKeys: [.fileSizeKey]) else { return 0 }
+        var total: Int64 = 0
+        for case let url as URL in en {
+            let v = try? url.resourceValues(forKeys: [.fileSizeKey])
+            total += Int64(v?.fileSize ?? 0)
+        }
+        return total
+    }
+
+    private func countLines(_ url: URL) -> Int {
+        guard let data = try? Data(contentsOf: url) else { return 0 }
+        var n = 0
+        for b in data where b == 0x0A { n += 1 }
+        return n
+    }
+
+    private func appendBytes(_ url: URL, _ data: Data) {
+        if let h = try? FileHandle(forWritingTo: url) {
+            defer { try? h.close() }
+            _ = try? h.seekToEnd()
+            try? h.write(contentsOf: data)
+        } else {
+            try? data.write(to: url)
+        }
+    }
+
+    /// Write to `<file>.tmp`, F_FULLFSYNC the file, atomically rename to the final
+    /// path, then fsync the PARENT DIRECTORY. On iOS plain `fsync` does NOT force a
+    /// hardware flush, so `F_FULLFSYNC` is required; and the rename is not durable
+    /// until the directory entry itself is flushed (section 5).
+    @discardableResult
+    private func atomicWrite(_ file: URL, _ data: Data) -> Bool {
+        let dir = file.deletingLastPathComponent()
+        try? fm.createDirectory(at: dir, withIntermediateDirectories: true)
+        let tmp = dir.appendingPathComponent(file.lastPathComponent + ".tmp")
+        do {
+            try data.write(to: tmp)
+            fullFsyncFile(tmp)
+            if fm.fileExists(atPath: file.path) { try? fm.removeItem(at: file) }
+            try fm.moveItem(at: tmp, to: file)
+            fsyncDir(dir)
+            return true
+        } catch {
+            try? fm.removeItem(at: tmp)
+            ReplayLogger.warn("outbox.atomicWrite failed: \(error.localizedDescription)")
+            return false
+        }
+    }
+
+    /// F_FULLFSYNC the file's bytes to the storage medium (NOT plain fsync on iOS).
+    private func fullFsyncFile(_ url: URL) {
+        let fd = open(url.path, O_WRONLY)
+        if fd >= 0 {
+            _ = fcntl(fd, F_FULLFSYNC)
+            close(fd)
+        }
+    }
+
+    /// Flush the directory entry so a freshly-renamed file survives a hard kill.
+    private func fsyncDir(_ dir: URL) {
+        let fd = open(dir.path, O_RDONLY)
+        if fd >= 0 {
+            if fcntl(fd, F_FULLFSYNC) == -1 { _ = fsync(fd) }
+            close(fd)
+        }
+    }
+
+    // ─── json ───────────────────────────────────────────────────────────
+
+    private func jsonData(_ obj: [String: Any]) -> Data {
+        return (try? JSONSerialization.data(withJSONObject: obj)) ?? Data("{}".utf8)
+    }
+
+    private func readJson(_ url: URL) -> [String: Any]? {
+        guard let data = try? Data(contentsOf: url),
+              let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
+        return obj
+    }
+
+    private func nowMs() -> Int64 { Int64(Date().timeIntervalSince1970 * 1000) }
+
+    private func int(_ v: Any?) -> Int {
+        if let n = v as? Int { return n }
+        if let n = v as? NSNumber { return n.intValue }
+        return 0
+    }
+
+    private func int64(_ v: Any?) -> Int64 {
+        if let n = v as? Int64 { return n }
+        if let n = v as? Int { return Int64(n) }
+        if let n = v as? NSNumber { return n.int64Value }
+        return 0
+    }
+}