Feature/Fix: Discover referenced long-lived Codex parents

Sources/CodexBarCore/Generated/CodexParserHash.generated.swift

@@ -1,5 +1,5 @@
 // Generated by Scripts/regenerate-codex-parser-hash.sh. Do not edit by hand.
 
 enum CodexParserHash {
-    static let value = "cdef6eb9658a43e2"
+    static let value = "f1fe17eb233c9f4d"
 }

Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift

@@ -0,0 +1,137 @@
+import Foundation
+
+/// Expands an already bounded rollout-file selection with only the ancestors its documents reference.
+enum CodexLineageDiscovery {
+    struct Report: Equatable, Sendable {
+        let documents: [CodexLineageLedger.Document]
+        let referencedParentDocumentCount: Int
+        let unresolvedParentIDs: Set<String>
+    }
+
+    static func discover(
+        includedFiles: [URL],
+        roots: [URL],
+        checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> Report
+    {
+        var locator = ParentFileLocator(roots: roots, checkCancellation: checkCancellation)
+        var documents: [CodexLineageLedger.Document] = []
+        var knownIDs: Set<String> = []
+        var seenPaths: Set<String> = []
+        var pendingParentIDs: [String] = []
+        var unresolvedParentIDs: Set<String> = []
+        var referencedParentDocumentCount = 0
+
+        func remember(_ document: CodexLineageLedger.Document) {
+            documents.append(document)
+            knownIDs.insert(Self.canonicalSessionID(document.ownerID))
+            if let metadataSessionID = Self.nonEmpty(document.metadataSessionID) {
+                knownIDs.insert(Self.canonicalSessionID(metadataSessionID))
+            }
+            if let parentSessionID = Self.nonEmpty(document.parentSessionID) {
+                pendingParentIDs.append(Self.canonicalSessionID(parentSessionID))
+            }
+        }
+
+        for fileURL in includedFiles.sorted(by: { $0.path < $1.path }) {
+            try checkCancellation?()
+            let path = fileURL.standardizedFileURL.path
+            guard seenPaths.insert(path).inserted else { continue }
+            try remember(CostUsageScanner.parseCodexLineageDocument(
+                fileURL: fileURL,
+                checkCancellation: checkCancellation))
+        }
+
+        var nextParent = 0
+        while nextParent < pendingParentIDs.count {
+            try checkCancellation?()
+            let parentID = pendingParentIDs[nextParent]
+            nextParent += 1
+            guard !knownIDs.contains(parentID), !unresolvedParentIDs.contains(parentID) else { continue }
+            guard let parentURL = try locator.fileURL(for: parentID) else {
+                unresolvedParentIDs.insert(parentID)
+                continue
+            }
+            let path = parentURL.standardizedFileURL.path
+            guard seenPaths.insert(path).inserted else {
+                unresolvedParentIDs.insert(parentID)
+                continue
+            }
+            let parent = try CostUsageScanner.parseCodexLineageDocument(
+                fileURL: parentURL,
+                checkCancellation: checkCancellation)
+            let ownerID = Self.canonicalSessionID(parent.ownerID)
+            let metadataSessionID = parent.metadataSessionID.map(Self.canonicalSessionID)
+            guard ownerID == parentID || metadataSessionID == parentID else {
+                unresolvedParentIDs.insert(parentID)
+                continue
+            }
+            referencedParentDocumentCount += 1
+            remember(parent)
+        }
+
+        return Report(
+            documents: documents,
+            referencedParentDocumentCount: referencedParentDocumentCount,
+            unresolvedParentIDs: unresolvedParentIDs)
+    }
+
+    private static func nonEmpty(_ value: String?) -> String? {
+        guard let value, !value.isEmpty else { return nil }
+        return value
+    }
+
+    private static func canonicalSessionID(_ value: String) -> String {
+        UUID(uuidString: value)?.uuidString.lowercased() ?? value
+    }
+
+    private struct ParentFileLocator {
+        let roots: [URL]
+        let checkCancellation: CostUsageScanner.CancellationCheck?
+        var didIndexRoots = false
+        var filesByID: [String: URL] = [:]
+
+        mutating func fileURL(for sessionID: String) throws -> URL? {
+            let canonicalID = CodexLineageDiscovery.canonicalSessionID(sessionID)
+            if let known = self.filesByID[canonicalID] {
+                return known
+            }
+            if !self.didIndexRoots {
+                try self.indexRoots()
+            }
+            return self.filesByID[canonicalID]
+        }
+
+        private mutating func indexRoots() throws {
+            self.didIndexRoots = true
+            var files: [URL] = []
+            for root in self.roots {
+                try self.checkCancellation?()
+                guard let enumerator = FileManager.default.enumerator(
+                    at: root,
+                    includingPropertiesForKeys: [.isRegularFileKey],
+                    options: [.skipsHiddenFiles, .skipsPackageDescendants])
+                else { continue }
+                while let fileURL = enumerator.nextObject() as? URL {
+                    try self.checkCancellation?()
+                    guard fileURL.pathExtension.lowercased() == "jsonl" else { continue }
+                    files.append(fileURL)
+                }
+            }
+
+            for fileURL in files.sorted(by: { $0.path < $1.path }) {
+                try self.checkCancellation?()
+                if let ownerID = CostUsageScanner.codexRolloutOwnerID(fileURL: fileURL) {
+                    let canonicalID = CodexLineageDiscovery.canonicalSessionID(ownerID)
+                    self.filesByID[canonicalID] = self.filesByID[canonicalID] ?? fileURL
+                }
+                if let metadataID = try CostUsageScanner.parseCodexSessionIdentifier(
+                    fileURL: fileURL,
+                    checkCancellation: self.checkCancellation)
+                {
+                    let canonicalID = CodexLineageDiscovery.canonicalSessionID(metadataID)
+                    self.filesByID[canonicalID] = self.filesByID[canonicalID] ?? fileURL
+                }
+            }
+        }
+    }
+}

Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift

@@ -0,0 +1,163 @@
+import Foundation
+
+/// Experimental accounting model for Codex rollout families.
+///
+/// Rollout files are overlapping physical views of a logical lineage. The ledger builds the
+/// transitive lineage first, then admits each complete token observation once per lineage.
+/// It intentionally does not participate in production cost totals yet.
+enum CodexLineageLedger {
+    struct Totals: Equatable, Hashable, Sendable {
+        var input: Int
+        var cached: Int
+        var output: Int
+
+        static let zero = Self(input: 0, cached: 0, output: 0)
+
+        mutating func add(_ other: Self) {
+            self.input += other.input
+            self.cached += other.cached
+            self.output += other.output
+        }
+    }
+
+    struct Observation: Equatable, Sendable {
+        let timestamp: String
+        let last: Totals
+        let total: Totals
+    }
+
+    struct Document: Equatable, Sendable {
+        /// Canonical owner from the rollout filename when available.
+        let ownerID: String
+        /// Session identity persisted in metadata. Fork copies may retain an ancestor identity.
+        let metadataSessionID: String?
+        let parentSessionID: String?
+        let observations: [Observation]
+    }
+
+    struct Report: Equatable, Sendable {
+        let utcDays: [String: Totals]
+        let localDays: [String: Totals]
+        let componentCount: Int
+        let acceptedObservationCount: Int
+        let duplicateObservationCount: Int
+    }
+
+    enum LedgerError: Error, Equatable {
+        case emptyOwnerID
+        case invalidTimestamp(String)
+    }
+
+    static func reconcile(documents: [Document], localTimeZone: TimeZone) throws -> Report {
+        var graph = DisjointSet()
+        for document in documents {
+            guard !document.ownerID.isEmpty else { throw LedgerError.emptyOwnerID }
+            graph.insert(document.ownerID)
+            if let metadataSessionID = Self.nonEmpty(document.metadataSessionID) {
+                graph.union(document.ownerID, metadataSessionID)
+            }
+            if let parentSessionID = Self.nonEmpty(document.parentSessionID) {
+                graph.union(document.ownerID, parentSessionID)
+            }
+        }
+
+        var acceptedByComponent: [String: [Fingerprint: AcceptedObservation]] = [:]
+        var physicalObservationCount = 0
+        for document in documents {
+            let componentID = graph.find(document.ownerID)
+            var accepted = acceptedByComponent[componentID] ?? [:]
+            for observation in document.observations {
+                physicalObservationCount += 1
+                let date = try Self.date(from: observation.timestamp)
+                let fingerprint = Fingerprint(last: observation.last, total: observation.total)
+                if let existing = accepted[fingerprint], existing.date <= date {
+                    continue
+                }
+                accepted[fingerprint] = AcceptedObservation(date: date, last: observation.last)
+            }
+            acceptedByComponent[componentID] = accepted
+        }
+
+        var utcDays: [String: Totals] = [:]
+        var localDays: [String: Totals] = [:]
+        var acceptedObservationCount = 0
+        for accepted in acceptedByComponent.values {
+            acceptedObservationCount += accepted.count
+            for observation in accepted.values {
+                Self.add(observation.last, on: observation.date, timeZone: .gmt, to: &utcDays)
+                Self.add(observation.last, on: observation.date, timeZone: localTimeZone, to: &localDays)
+            }
+        }
+
+        return Report(
+            utcDays: utcDays,
+            localDays: localDays,
+            componentCount: Set(documents.map { graph.find($0.ownerID) }).count,
+            acceptedObservationCount: acceptedObservationCount,
+            duplicateObservationCount: physicalObservationCount - acceptedObservationCount)
+    }
+
+    private struct Fingerprint: Equatable, Hashable {
+        let last: Totals
+        let total: Totals
+    }
+
+    private struct AcceptedObservation {
+        let date: Date
+        let last: Totals
+    }
+
+    private static func nonEmpty(_ value: String?) -> String? {
+        guard let value, !value.isEmpty else { return nil }
+        return value
+    }
+
+    private static func date(from timestamp: String) throws -> Date {
+        guard let date = CostUsageScanner.dateFromTimestamp(timestamp) else {
+            throw LedgerError.invalidTimestamp(timestamp)
+        }
+        return date
+    }
+
+    private static func add(
+        _ totals: Totals,
+        on date: Date,
+        timeZone: TimeZone,
+        to days: inout [String: Totals])
+    {
+        var calendar = Calendar(identifier: .gregorian)
+        calendar.timeZone = timeZone
+        let components = calendar.dateComponents([.year, .month, .day], from: date)
+        guard let year = components.year, let month = components.month, let day = components.day else { return }
+        let key = String(format: "%04d-%02d-%02d", year, month, day)
+        var dayTotals = days[key] ?? .zero
+        dayTotals.add(totals)
+        days[key] = dayTotals
+    }
+
+    private struct DisjointSet {
+        private var parents: [String: String] = [:]
+
+        mutating func insert(_ item: String) {
+            if self.parents[item] == nil {
+                self.parents[item] = item
+            }
+        }
+
+        mutating func find(_ item: String) -> String {
+            self.insert(item)
+            guard let parent = self.parents[item], parent != item else { return item }
+            let root = self.find(parent)
+            self.parents[item] = root
+            return root
+        }
+
+        mutating func union(_ first: String, _ second: String) {
+            let firstRoot = self.find(first)
+            let secondRoot = self.find(second)
+            if firstRoot != secondRoot {
+                self.parents[secondRoot] = firstRoot
+            }
+        }
+    }
+}