@sriinnu/runic 1.0.0 → 2.0.0

package/Sources/RunicCore/UsageFormatter.swift

@@ -97,7 +97,7 @@ public enum UsageFormatter {
         guard tokenCount > 0 else { return nil }
         let rate = costUSD / (Double(tokenCount) / 1000.0)
         guard rate.isFinite, rate >= 0 else { return nil }
-        return "\(usdRateString(rate))/1K"
+        return "\(self.usdRateString(rate))/1K"
     }
 
     public static func usdPerRequestString(costUSD: Double?, requestCount: Int) -> String? {
@@ -105,7 +105,7 @@ public enum UsageFormatter {
         guard requestCount > 0 else { return nil }
         let rate = costUSD / Double(requestCount)
         guard rate.isFinite, rate >= 0 else { return nil }
-        return "\(usdRateString(rate))/req"
+        return "\(self.usdRateString(rate))/req"
     }
 
     public static func usdPerHourFromTokensString(
@@ -120,7 +120,7 @@ public enum UsageFormatter {
         guard per1KValue.isFinite, per1KValue >= 0 else { return nil }
         let hourly = per1KValue * (tokensPerMinute * 60.0 / 1000.0)
         guard hourly.isFinite, hourly >= 0 else { return nil }
-        return "\(usdRateString(hourly))/hr"
+        return "\(self.usdRateString(hourly))/hr"
     }
 
     public static func currencyString(_ value: Double, currencyCode: String) -> String {
@@ -164,21 +164,21 @@ public enum UsageFormatter {
     }
 
     public static func tokenSummaryString(_ totals: UsageLedgerTotals, includeBreakdown: Bool = true) -> String {
-        let total = tokenCountString(totals.totalTokens)
+        let total = self.tokenCountString(totals.totalTokens)
         guard includeBreakdown else {
             return "\(total) tok"
         }
 
         var parts: [String] = []
         if totals.inputTokens > 0 {
-            parts.append("in \(tokenCountString(totals.inputTokens))")
+            parts.append("in \(self.tokenCountString(totals.inputTokens))")
         }
         if totals.outputTokens > 0 {
-            parts.append("out \(tokenCountString(totals.outputTokens))")
+            parts.append("out \(self.tokenCountString(totals.outputTokens))")
         }
         let cached = totals.cacheCreationTokens + totals.cacheReadTokens
         if cached > 0 {
-            parts.append("cache \(tokenCountString(cached))")
+            parts.append("cache \(self.tokenCountString(cached))")
         }
         guard !parts.isEmpty else { return "\(total) tok" }
         return "\(total) tok (\(parts.joined(separator: ", ")))"
@@ -248,8 +248,8 @@ public enum UsageFormatter {
     /// Returns a human-friendly context window label for a model when known.
     /// Examples: "ctx 128k", "ctx 1M".
     public static func modelContextLabel(for model: String) -> String? {
-        guard let context = Self.modelContextWindow(for: model) else { return nil }
-        return "ctx \(tokenCountString(context))"
+        guard let context = modelContextWindow(for: model) else { return nil }
+        return "ctx \(self.tokenCountString(context))"
     }
 
     /// Resolves an approximate context window (in tokens) for common model families.
@@ -285,7 +285,7 @@ public enum UsageFormatter {
         "gpt-4o-mini": 128_000,
         "gpt-4-turbo": 128_000,
         "gpt-4": 128_000,
-        "gpt-3.5-turbo": 16_385,
+        "gpt-3.5-turbo": 16385,
         "gpt-4.1": 1_000_000,
         "gpt-4.1-mini": 1_000_000,
         "gpt-4.1-nano": 1_000_000,
@@ -315,33 +315,33 @@ public enum UsageFormatter {
         "llama-3-1-8b": 128_000,
         "llama-3-3-70b": 128_000,
         "mistral-large": 128_000,
-        "mistral-small": 32_000,
+        "mistral-small": 32000,
         "mistral-medium": 131_072,
-        "deepseek-chat": 64_000,
-        "deepseek-coder": 32_000,
+        "deepseek-chat": 64000,
+        "deepseek-coder": 32000,
         "cohere-command": 128_000,
         "cohere-command-r": 128_000,
         "cohere-command-r-plus": 128_000,
         "qwen-2-5-72b": 128_000,
         "qwen-2-5-32b": 128_000,
-        "qwen1-5-32b": 8_192,
-        "qwen1-5-14b": 8_192,
+        "qwen1-5-32b": 8192,
+        "qwen1-5-14b": 8192,
         "grok-2": 128_000,
         "grok-2-mini": 131_072,
         "grok-2-vision": 131_072,
-        "mixtral-8x7b": 32_768,
-        "mixtral-8x22b": 64_000,
-        "llama-3-8b": 8_192,
-        "llama-3-70b": 8_192,
-        "llama-2-70b": 4_096,
-        "llama-2-13b": 4_096,
+        "mixtral-8x7b": 32768,
+        "mixtral-8x22b": 64000,
+        "llama-3-8b": 8192,
+        "llama-3-70b": 8192,
+        "llama-2-70b": 4096,
+        "llama-2-13b": 4096,
     ]
 
     private static let modelContextPrefixes: [(String, Int)] = [
         ("gpt-4.1", 1_000_000),
         ("gpt-4o", 128_000),
         ("gpt-4-", 128_000),
-        ("gpt-3.5", 16_385),
+        ("gpt-3.5", 16385),
         ("gpt-5", 400_000),
         ("gpt-5-", 400_000),
         ("claude-3", 200_000),
@@ -351,9 +351,9 @@ public enum UsageFormatter {
         ("gemini-1-5", 1_000_000),
         ("gemini-2-0", 1_000_000),
         ("gemini-2-5", 1_000_000),
-        ("llama-3", 8_192),
+        ("llama-3", 8192),
         ("qwen-2-5", 128_000),
-        ("qwen1-5", 8_192),
+        ("qwen1-5", 8192),
     ]
 
     private static func normalizedModelIdentifier(for model: String) -> String {
@@ -370,7 +370,7 @@ public enum UsageFormatter {
         for token in tokens.reversed() {
             let lower = token.lowercased()
             if lower.hasSuffix("k"), let numeric = Int(lower.dropLast()), numeric > 0 {
-                return numeric * 1_000
+                return numeric * 1000
             }
             if lower.hasSuffix("m"), let numeric = Int(lower.dropLast()), numeric > 0 {
                 return numeric * 1_000_000

package/Sources/RunicCore/UsageLedger/ClaudeUsageLogSource.swift

@@ -44,33 +44,142 @@ public struct ClaudeUsageLogSource: UsageLedgerSource, @unchecked Sendable {
             throw ClaudeUsageLogError.noProjectsDirectory
         }
 
+        // Only scan files modified since our last scan (incremental).
+        // On first run, scans the last `maxAgeDays` worth of files.
+        let cache = LedgerCache.shared
+        let lastScan = await cache.lastScanDate(provider: "claude")
+        let incrementalCutoff = lastScan ?? self.minDate() ?? self.now.addingTimeInterval(-86400)
         let minDate = self.minDate()
-        let files = self.findUsageFiles(in: projectsDirs, minDate: minDate)
-        if files.isEmpty {
-            return []
+
+        let allFiles = self.findUsageFiles(in: projectsDirs, minDate: minDate)
+
+        // Filter to only files modified since last scan (plus today's files which may have grown).
+        let todayStart = Calendar.current.startOfDay(for: self.now)
+        let filesToScan = allFiles.filter { file in
+            guard let modDate = (try? self.fileManager
+                .attributesOfItem(atPath: file.url.path))?[.modificationDate] as? Date
+            else {
+                return true
+            }
+            return modDate >= incrementalCutoff || modDate >= todayStart
         }
 
-        var entries: [UsageLedgerEntry] = []
-        var seenKeys = Set<String>()
+        if filesToScan.isEmpty {
+            return []
+        }
 
-        for file in files {
-            do {
-                let data = try Data(contentsOf: file.url)
-                guard let content = String(data: data, encoding: .utf8) else { continue }
-                let lines = content.split(whereSeparator: \.isNewline)
-                for line in lines {
-                    if let entry = self.parseLine(line, file: file, minDate: minDate, seenKeys: &seenKeys) {
-                        entries.append(entry)
+        self.log
+            .info(
+                "Scanning \(filesToScan.count) of \(allFiles.count) JSONL files (incremental since \(incrementalCutoff))")
+
+        // Parse files concurrently (max 16 at a time).
+        let maxConcurrency = 16
+        let fileEntries = await withTaskGroup(
+            of: [UsageLedgerEntry].self,
+            returning: [UsageLedgerEntry].self)
+        { group in
+            var all: [UsageLedgerEntry] = []
+            var inflight = 0
+            for file in filesToScan {
+                if inflight >= maxConcurrency {
+                    if let batch = await group.next() {
+                        all.append(contentsOf: batch)
+                        inflight -= 1
                     }
                 }
-            } catch {
-                self.log.warning("Claude usage log read failed", metadata: [
-                    "file": file.url.path,
-                    "error": error.localizedDescription,
-                ])
+                group.addTask {
+                    self.parseFile(file, minDate: minDate)
+                }
+                inflight += 1
+            }
+            for await batch in group {
+                all.append(contentsOf: batch)
+            }
+            return all
+        }
+
+        // Deduplicate across files using the same composite key as per-file dedup.
+        var seenKeys = Set<String>()
+        var entries: [UsageLedgerEntry] = []
+        entries.reserveCapacity(fileEntries.count)
+        for entry in fileEntries {
+            let key = self.dedupeKey(
+                requestID: entry.requestID,
+                messageID: entry.messageID,
+                sessionID: entry.sessionID,
+                timestamp: entry.timestamp,
+                inputTokens: entry.inputTokens,
+                outputTokens: entry.outputTokens,
+                cacheCreationTokens: entry.cacheCreationTokens,
+                cacheReadTokens: entry.cacheReadTokens)
+            if seenKeys.insert(key).inserted {
+                entries.append(entry)
             }
         }
 
+        // Aggregate into daily summaries and persist to cache.
+        let dailyFormatter = DateFormatter()
+        dailyFormatter.dateFormat = "yyyy-MM-dd"
+        dailyFormatter.timeZone = .current
+
+        var dailyBuckets: [String: (
+            input: Int,
+            output: Int,
+            cacheCreate: Int,
+            cacheRead: Int,
+            cost: Double,
+            requests: Int,
+            models: Set<String>)] = [:]
+        for entry in entries {
+            let key = dailyFormatter.string(from: entry.timestamp)
+            var bucket = dailyBuckets[key] ?? (0, 0, 0, 0, 0, 0, [])
+            bucket.input += entry.inputTokens
+            bucket.output += entry.outputTokens
+            bucket.cacheCreate += entry.cacheCreationTokens
+            bucket.cacheRead += entry.cacheReadTokens
+            bucket.cost += entry.costUSD ?? 0
+            bucket.requests += 1
+            if let model = entry.model { bucket.models.insert(model) }
+            dailyBuckets[key] = bucket
+        }
+
+        let cachedDailies = dailyBuckets.map { key, bucket in
+            CachedDaily(
+                dayKey: key,
+                inputTokens: bucket.input,
+                outputTokens: bucket.output,
+                cacheCreationTokens: bucket.cacheCreate,
+                cacheReadTokens: bucket.cacheRead,
+                costUSD: bucket.cost > 0 ? bucket.cost : nil,
+                requestCount: bucket.requests,
+                modelsUsed: Array(bucket.models))
+        }
+
+        let todayKey = await LedgerCache.dayKey(for: self.now)
+        await cache.mergeDailies(provider: "claude", newDailies: cachedDailies, scanDate: self.now, todayKey: todayKey)
+
+        return entries
+    }
+
+    /// Parse a single JSONL file, returning usage entries.
+    private func parseFile(_ file: UsageFile, minDate: Date?) -> [UsageLedgerEntry] {
+        var entries: [UsageLedgerEntry] = []
+        do {
+            let data = try Data(contentsOf: file.url)
+            guard let content = String(data: data, encoding: .utf8) else { return [] }
+            var seenKeys = Set<String>()
+            let lines = content.split(whereSeparator: \.isNewline)
+            for line in lines {
+                if let entry = self.parseLine(line, file: file, minDate: minDate, seenKeys: &seenKeys) {
+                    entries.append(entry)
+                }
+            }
+        } catch {
+            self.log.warning("Claude usage log read failed", metadata: [
+                "file": file.url.path,
+                "error": error.localizedDescription,
+            ])
+        }
         return entries
     }
 
@@ -90,24 +199,22 @@ public struct ClaudeUsageLogSource: UsageLedgerSource, @unchecked Sendable {
 
         var candidates: [URL] = []
         if !envPaths.isEmpty {
-            candidates = envPaths.map { expandTilde(path: String($0)) }
+            candidates = envPaths.map { self.expandTilde(path: String($0)) }
         } else {
-            let home = fileManager.homeDirectoryForCurrentUser
+            let home = self.fileManager.homeDirectoryForCurrentUser
             candidates = [
                 home.appendingPathComponent(".config/claude", isDirectory: true),
                 home.appendingPathComponent(".claude", isDirectory: true),
             ]
         }
 
-        let projectsDirs = candidates
+        return candidates
             .map { $0.appendingPathComponent("projects", isDirectory: true) }
             .filter { self.fileManager.directoryExists(at: $0) }
-
-        return projectsDirs
     }
 
     private func normalizePaths(_ urls: [URL]) -> [URL] {
-        urls.map { $0.standardizedFileURL }
+        urls.map(\.standardizedFileURL)
             .filter { self.fileManager.directoryExists(at: $0) }
             .map { $0.appendingPathComponent("projects", isDirectory: true) }
             .filter { self.fileManager.directoryExists(at: $0) }
@@ -123,7 +230,7 @@ public struct ClaudeUsageLogSource: UsageLedgerSource, @unchecked Sendable {
                 options: [.skipsHiddenFiles])
 
             while let fileURL = enumerator?.nextObject() as? URL {
-                guard fileURL.lastPathComponent == "usage.jsonl" else { continue }
+                guard fileURL.pathExtension == "jsonl" else { continue }
                 if let minDate {
                     let values = try? fileURL.resourceValues(forKeys: [.contentModificationDateKey])
                     if let modifiedAt = values?.contentModificationDate, modifiedAt < minDate { continue }
@@ -138,7 +245,11 @@ public struct ClaudeUsageLogSource: UsageLedgerSource, @unchecked Sendable {
                 let projectID = pathComponents[projectsIndex + 1]
                 let projectName = self.derivedProjectName(from: projectID)
                 let sessionID = pathComponents[projectsIndex + 2]
-                results.append(UsageFile(url: fileURL, projectID: projectID, projectName: projectName, sessionID: sessionID))
+                results.append(UsageFile(
+                    url: fileURL,
+                    projectID: projectID,
+                    projectName: projectName,
+                    sessionID: sessionID))
             }
         }
 
@@ -257,7 +368,7 @@ public struct ClaudeUsageLogSource: UsageLedgerSource, @unchecked Sendable {
 
     private func expandTilde(path: String) -> URL {
         if path.hasPrefix("~/") {
-            let home = fileManager.homeDirectoryForCurrentUser
+            let home = self.fileManager.homeDirectoryForCurrentUser
             let trimmed = String(path.dropFirst(2))
             return home.appendingPathComponent(trimmed, isDirectory: true)
         }
@@ -312,6 +423,7 @@ private final class ClaudeISO8601FormatterBox: @unchecked Sendable {
         formatter.formatOptions = [.withInternetDateTime]
         return formatter
     }()
+
     let fractional: ISO8601DateFormatter = {
         let formatter = ISO8601DateFormatter()
         formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
@@ -321,8 +433,8 @@ private final class ClaudeISO8601FormatterBox: @unchecked Sendable {
 
 private let claudeISOFormatterBox = ClaudeISO8601FormatterBox()
 
-private extension FileManager {
-    func directoryExists(at url: URL) -> Bool {
+extension FileManager {
+    fileprivate func directoryExists(at url: URL) -> Bool {
         var isDir: ObjCBool = false
         return self.fileExists(atPath: url.path, isDirectory: &isDir) && isDir.boolValue
     }

package/Sources/RunicCore/UsageLedger/CodexUsageLogSource.swift

@@ -87,15 +87,27 @@ public struct CodexUsageLogSource: UsageLedgerSource, @unchecked Sendable {
     public func loadEntries() async throws -> [UsageLedgerEntry] {
         let root = try self.resolveSessionsRoot()
         let minDate = self.minDate()
-        let files = self.listSessionFiles(root: root, minDate: minDate)
-        if files.isEmpty {
+
+        // Incremental scan: only parse files modified since our last scan.
+        let cache = LedgerCache.shared
+        let lastScan = await cache.lastScanDate(provider: "codex")
+        let incrementalCutoff = lastScan ?? minDate ?? self.now.addingTimeInterval(-86400)
+        let todayStart = Calendar.current.startOfDay(for: self.now)
+
+        let allFiles = self.listSessionFiles(root: root, minDate: minDate)
+        let filesToScan = allFiles.filter { file in
+            guard let modDate = file.modifiedAt else { return true }
+            return modDate >= incrementalCutoff || modDate >= todayStart
+        }
+
+        if filesToScan.isEmpty {
             return []
         }
 
         var entries: [UsageLedgerEntry] = []
         var seenKeys = Set<String>()
 
-        for file in files {
+        for file in filesToScan {
             do {
                 try self.parseFile(file, minDate: minDate, seenKeys: &seenKeys, entries: &entries)
             } catch {
@@ -106,6 +118,47 @@ public struct CodexUsageLogSource: UsageLedgerSource, @unchecked Sendable {
             }
         }
 
+        // Aggregate into daily summaries and persist to cache.
+        let dailyFormatter = DateFormatter()
+        dailyFormatter.dateFormat = "yyyy-MM-dd"
+        dailyFormatter.timeZone = .current
+
+        var dailyBuckets: [String: (
+            input: Int,
+            output: Int,
+            cacheCreate: Int,
+            cacheRead: Int,
+            cost: Double,
+            requests: Int,
+            models: Set<String>)] = [:]
+        for entry in entries {
+            let key = dailyFormatter.string(from: entry.timestamp)
+            var bucket = dailyBuckets[key] ?? (0, 0, 0, 0, 0, 0, [])
+            bucket.input += entry.inputTokens
+            bucket.output += entry.outputTokens
+            bucket.cacheCreate += entry.cacheCreationTokens
+            bucket.cacheRead += entry.cacheReadTokens
+            bucket.cost += entry.costUSD ?? 0
+            bucket.requests += 1
+            if let model = entry.model { bucket.models.insert(model) }
+            dailyBuckets[key] = bucket
+        }
+
+        let cachedDailies = dailyBuckets.map { key, bucket in
+            CachedDaily(
+                dayKey: key,
+                inputTokens: bucket.input,
+                outputTokens: bucket.output,
+                cacheCreationTokens: bucket.cacheCreate,
+                cacheReadTokens: bucket.cacheRead,
+                costUSD: bucket.cost > 0 ? bucket.cost : nil,
+                requestCount: bucket.requests,
+                modelsUsed: Array(bucket.models))
+        }
+
+        let todayKey = await LedgerCache.dayKey(for: self.now)
+        await cache.mergeDailies(provider: "codex", newDailies: cachedDailies, scanDate: self.now, todayKey: todayKey)
+
         return entries
     }
 
@@ -431,6 +484,7 @@ private final class CodexISO8601FormatterBox: @unchecked Sendable {
         formatter.formatOptions = [.withInternetDateTime]
         return formatter
     }()
+
     let fractional: ISO8601DateFormatter = {
         let formatter = ISO8601DateFormatter()
         formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
@@ -440,8 +494,8 @@ private final class CodexISO8601FormatterBox: @unchecked Sendable {
 
 private let codexISOFormatterBox = CodexISO8601FormatterBox()
 
-private extension FileManager {
-    func directoryExists(at url: URL) -> Bool {
+extension FileManager {
+    fileprivate func directoryExists(at url: URL) -> Bool {
         var isDir: ObjCBool = false
         return self.fileExists(atPath: url.path, isDirectory: &isDir) && isDir.boolValue
     }

package/Sources/RunicCore/UsageLedger/LedgerCache.swift

@@ -0,0 +1,161 @@
+import Foundation
+import OSLog
+
+/// Persistent cache for aggregated ledger data. Stores daily summaries per provider
+/// so the app never re-scans old JSONL files. Works like a deque — new days are
+/// appended, historical days are immutable.
+///
+/// Storage: `~/Library/Application Support/Runic/ledger-cache/`
+///   - `claude-daily.json`, `codex-daily.json`, etc.
+///   - Each file: `{ "lastScanDate": "...", "dailies": [...] }`
+public actor LedgerCache {
+    public static let shared = LedgerCache()
+
+    private static let log = Logger(subsystem: "com.sriinnu.athena.Runic", category: "ledger-cache")
+    private let cacheDir: URL
+
+    private static let dayKeyFormatter: DateFormatter = {
+        let f = DateFormatter()
+        f.dateFormat = "yyyy-MM-dd"
+        f.timeZone = .current
+        return f
+    }()
+
+    public init() {
+        let appSupport = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first!
+        self.cacheDir = appSupport.appendingPathComponent("Runic/ledger-cache", isDirectory: true)
+        try? FileManager.default.createDirectory(at: self.cacheDir, withIntermediateDirectories: true)
+    }
+
+    // MARK: - Public API
+
+    /// Load cached daily summaries for a provider. Returns instantly.
+    public func loadCachedDailies(provider: String) -> CachedLedger? {
+        let url = self.fileURL(provider: provider)
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        return try? JSONDecoder().decode(CachedLedger.self, from: data)
+    }
+
+    /// Save aggregated daily summaries for a provider.
+    public func saveDailies(provider: String, ledger: CachedLedger) {
+        let url = self.fileURL(provider: provider)
+        guard let data = try? JSONEncoder().encode(ledger) else { return }
+        try? data.write(to: url, options: .atomic)
+        Self.log.debug("Saved \(ledger.dailies.count) days for \(provider)")
+    }
+
+    /// Merge new daily entries into existing cache. Deque behavior:
+    /// - Existing days are NOT overwritten (immutable history)
+    /// - Today's entry is ACCUMULATED (adds to existing totals for partial scans)
+    /// - New days are appended
+    public func mergeDailies(provider: String, newDailies: [CachedDaily], scanDate: Date, todayKey: String? = nil) {
+        var ledger = self.loadCachedDailies(provider: provider) ?? CachedLedger(
+            lastScanDate: scanDate,
+            lastFullScanDate: nil,
+            dailies: [])
+
+        let resolvedTodayKey = todayKey ?? Self.dayKey(for: Date())
+        var existingByKey: [String: CachedDaily] = [:]
+        for daily in ledger.dailies {
+            existingByKey[daily.dayKey] = daily
+        }
+
+        for newDaily in newDailies {
+            if newDaily.dayKey == resolvedTodayKey, let existing = existingByKey[newDaily.dayKey] {
+                // Accumulate today's partial scan results onto existing totals.
+                var mergedModels = Set(existing.modelsUsed)
+                mergedModels.formUnion(newDaily.modelsUsed)
+                existingByKey[newDaily.dayKey] = CachedDaily(
+                    dayKey: newDaily.dayKey,
+                    inputTokens: existing.inputTokens + newDaily.inputTokens,
+                    outputTokens: existing.outputTokens + newDaily.outputTokens,
+                    cacheCreationTokens: existing.cacheCreationTokens + newDaily.cacheCreationTokens,
+                    cacheReadTokens: existing.cacheReadTokens + newDaily.cacheReadTokens,
+                    costUSD: (existing.costUSD ?? 0) + (newDaily.costUSD ?? 0) > 0
+                        ? (existing.costUSD ?? 0) + (newDaily.costUSD ?? 0) : nil,
+                    requestCount: existing.requestCount + newDaily.requestCount,
+                    modelsUsed: Array(mergedModels))
+            } else if existingByKey[newDaily.dayKey] == nil {
+                existingByKey[newDaily.dayKey] = newDaily
+            }
+        }
+
+        ledger.dailies = existingByKey.values.sorted { $0.dayKey < $1.dayKey }
+        ledger.lastScanDate = scanDate
+        self.saveDailies(provider: provider, ledger: ledger)
+    }
+
+    /// Mark that a full historical scan has been completed.
+    public func markFullScanComplete(provider: String) {
+        guard var ledger = self.loadCachedDailies(provider: provider) else { return }
+        ledger.lastFullScanDate = Date()
+        self.saveDailies(provider: provider, ledger: ledger)
+    }
+
+    /// Whether a full historical scan has been done for this provider.
+    public func hasFullScan(provider: String) -> Bool {
+        self.loadCachedDailies(provider: provider)?.lastFullScanDate != nil
+    }
+
+    /// Date of last incremental scan (to know which files to scan next).
+    public func lastScanDate(provider: String) -> Date? {
+        self.loadCachedDailies(provider: provider)?.lastScanDate
+    }
+
+    // MARK: - Internal
+
+    private func fileURL(provider: String) -> URL {
+        self.cacheDir.appendingPathComponent("\(provider)-daily.json")
+    }
+
+    static func dayKey(for date: Date) -> String {
+        self.dayKeyFormatter.string(from: date)
+    }
+}
+
+// MARK: - Models
+
+public struct CachedLedger: Codable, Sendable {
+    public var lastScanDate: Date
+    public var lastFullScanDate: Date?
+    public var dailies: [CachedDaily]
+}
+
+public struct CachedDaily: Codable, Sendable {
+    public let dayKey: String // "2026-03-23"
+    public let inputTokens: Int
+    public let outputTokens: Int
+    public let cacheCreationTokens: Int
+    public let cacheReadTokens: Int
+    public let costUSD: Double?
+    public let requestCount: Int
+    public let modelsUsed: [String]
+
+    private static let dayKeyParser: DateFormatter = {
+        let f = DateFormatter()
+        f.dateFormat = "yyyy-MM-dd"
+        f.timeZone = .current
+        return f
+    }()
+
+    public var totalTokens: Int {
+        self.inputTokens + self.outputTokens + self.cacheCreationTokens + self.cacheReadTokens
+    }
+
+    /// Convert to a UsageLedgerDailySummary for immediate display from cache.
+    public func toLedgerDailySummary(provider: UsageProvider) -> UsageLedgerDailySummary? {
+        guard let dayStart = Self.dayKeyParser.date(from: self.dayKey) else { return nil }
+        return UsageLedgerDailySummary(
+            provider: provider,
+            projectID: nil,
+            dayStart: dayStart,
+            dayKey: self.dayKey,
+            totals: UsageLedgerTotals(
+                inputTokens: self.inputTokens,
+                outputTokens: self.outputTokens,
+                cacheCreationTokens: self.cacheCreationTokens,
+                cacheReadTokens: self.cacheReadTokens,
+                costUSD: self.costUSD),
+            modelsUsed: self.modelsUsed)
+    }
+}

package/Sources/RunicCore/UsageLedger/OTelGenAILedgerAdapter.swift

@@ -29,7 +29,7 @@ public enum OTelGenAILedgerAdapterError: LocalizedError, Sendable, Equatable {
         switch self {
         case .invalidUTF8:
             "OTel payload is not valid UTF-8."
-        case .invalidJSON(let message):
+        case let .invalidJSON(message):
             "OTel JSON parse failed: \(message)"
         }
     }