Feature/Fix: Add a shadow lineage ledger for Codex token accounting

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
+            }
+        }
+    }
+}

Tests/CodexBarTests/CodexLineageLedgerTests.swift

@@ -0,0 +1,195 @@
+import Foundation
+import Testing
+@testable import CodexBarCore
+
+struct CodexLineageLedgerTests {
+    @Test
+    func `transitive lineage counts copied observations once`() throws {
+        let first = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100)
+        let second = Self.observation(timestamp: "2026-07-09T12:01:00Z", input: 50, totalInput: 150)
+        let third = Self.observation(timestamp: "2026-07-09T12:02:00Z", input: 25, totalInput: 175)
+        let documents = [
+            Self.document(owner: "root", observations: [first]),
+            Self.document(owner: "child", metadata: "root", parent: "root", observations: [first, second]),
+            Self.document(owner: "grandchild", metadata: "child", parent: "child", observations: [
+                first,
+                second,
+                third,
+            ]),
+        ]
+
+        let report = try CodexLineageLedger.reconcile(
+            documents: documents,
+            localTimeZone: #require(TimeZone(identifier: "America/New_York")))
+
+        #expect(report.utcDays["2026-07-09"]?.input == 175)
+        #expect(report.localDays["2026-07-09"]?.input == 175)
+        #expect(report.componentCount == 1)
+        #expect(report.acceptedObservationCount == 3)
+        #expect(report.duplicateObservationCount == 3)
+    }
+
+    @Test
+    func `equal observations in disconnected lineages remain additive`() throws {
+        let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100)
+        let report = try CodexLineageLedger.reconcile(
+            documents: [
+                Self.document(owner: "first", observations: [observation]),
+                Self.document(owner: "second", observations: [observation]),
+            ],
+            localTimeZone: #require(TimeZone(identifier: "America/New_York")))
+
+        #expect(report.utcDays["2026-07-09"]?.input == 200)
+        #expect(report.componentCount == 2)
+        #expect(report.acceptedObservationCount == 2)
+        #expect(report.duplicateObservationCount == 0)
+    }
+
+    @Test
+    func `unchanged state reemissions within a lineage count once`() throws {
+        let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100)
+        let report = try CodexLineageLedger.reconcile(
+            documents: [Self.document(owner: "root", observations: [observation, observation, observation])],
+            localTimeZone: #require(TimeZone(identifier: "America/New_York")))
+
+        #expect(report.utcDays["2026-07-09"]?.input == 100)
+        #expect(report.acceptedObservationCount == 1)
+        #expect(report.duplicateObservationCount == 2)
+    }
+
+    @Test
+    func `complete token state distinguishes observations within a lineage`() throws {
+        let first = Self.observation(
+            timestamp: "2026-07-09T12:00:00Z",
+            input: 100,
+            cached: 40,
+            output: 10,
+            totalInput: 100)
+        let changedTotal = Self.observation(
+            timestamp: "2026-07-09T12:01:00Z",
+            input: 100,
+            cached: 40,
+            output: 10,
+            totalInput: 200)
+        let changedLast = Self.observation(
+            timestamp: "2026-07-09T12:02:00Z",
+            input: 125,
+            cached: 50,
+            output: 15,
+            totalInput: 200)
+        let report = try CodexLineageLedger.reconcile(
+            documents: [
+                Self.document(owner: "root", observations: [first, changedTotal, changedLast]),
+            ],
+            localTimeZone: #require(TimeZone(identifier: "America/New_York")))
+
+        #expect(report.utcDays["2026-07-09"] == .init(input: 325, cached: 130, output: 35))
+        #expect(report.acceptedObservationCount == 3)
+        #expect(report.duplicateObservationCount == 0)
+    }
+
+    @Test
+    func `UTC and local projections preserve their distinct day boundaries`() throws {
+        let observation = Self.observation(timestamp: "2026-07-10T02:00:00Z", input: 100, totalInput: 100)
+        let report = try CodexLineageLedger.reconcile(
+            documents: [Self.document(owner: "root", observations: [observation])],
+            localTimeZone: #require(TimeZone(identifier: "America/New_York")))
+
+        #expect(report.utcDays["2026-07-10"]?.input == 100)
+        #expect(report.localDays["2026-07-09"]?.input == 100)
+    }
+
+    @Test(arguments: [
+        ("archived-fork-33ce-3869", 15_309_178),
+        ("live-fork-4d90-52bf", 26_801_911),
+    ])
+    func `sanitized fork fixtures collapse copied prefixes and unchanged reemissions`(
+        fixtureName: String,
+        expectedTokens: Int) throws
+    {
+        let fixture = try SanitizedForkFamilyFixture.load(named: fixtureName)
+        let parentMetadata = try fixture.sessionMetadata(named: "parent")
+        let childMetadata = try fixture.sessionMetadata(named: "child")
+        let parent = try fixture.events(named: "parent")
+        let child = try fixture.events(named: "child")
+        let documents = [
+            CodexLineageLedger.Document(
+                ownerID: "parent-owner",
+                metadataSessionID: parentMetadata.id,
+                parentSessionID: parentMetadata.forkedFromID,
+                observations: parent.map(Self.observation)),
+            CodexLineageLedger.Document(
+                ownerID: "child-owner",
+                metadataSessionID: childMetadata.id,
+                parentSessionID: childMetadata.forkedFromID,
+                observations: child.map(Self.observation)),
+        ]
+
+        let report = try CodexLineageLedger.reconcile(
+            documents: documents,
+            localTimeZone: #require(TimeZone(identifier: "America/New_York")))
+        let total = report.utcDays.values.reduce(0) { partial, totals in
+            partial + totals.input + totals.output
+        }
+
+        #expect(total == expectedTokens)
+        #expect(total < fixture.manifest.oracle.dedupedLastTokens)
+    }
+
+    @Test
+    func `document order does not change lineage totals or attribution`() throws {
+        let copiedLater = Self.observation(timestamp: "2026-07-10T00:05:00Z", input: 100, totalInput: 100)
+        let original = Self.observation(timestamp: "2026-07-09T23:55:00Z", input: 100, totalInput: 100)
+        let root = Self.document(owner: "root", observations: [original])
+        let child = Self.document(owner: "child", parent: "root", observations: [copiedLater])
+        let timeZone = try #require(TimeZone(identifier: "America/New_York"))
+
+        let forward = try CodexLineageLedger.reconcile(documents: [root, child], localTimeZone: timeZone)
+        let reversed = try CodexLineageLedger.reconcile(documents: [child, root], localTimeZone: timeZone)
+
+        #expect(forward == reversed)
+        #expect(forward.utcDays["2026-07-09"]?.input == 100)
+        #expect(forward.utcDays["2026-07-10"] == nil)
+    }
+
+    private static func document(
+        owner: String,
+        metadata: String? = nil,
+        parent: String? = nil,
+        observations: [CodexLineageLedger.Observation]) -> CodexLineageLedger.Document
+    {
+        .init(
+            ownerID: owner,
+            metadataSessionID: metadata,
+            parentSessionID: parent,
+            observations: observations)
+    }
+
+    private static func observation(
+        timestamp: String,
+        input: Int,
+        cached: Int = 0,
+        output: Int = 0,
+        totalInput: Int) -> CodexLineageLedger.Observation
+    {
+        .init(
+            timestamp: timestamp,
+            last: .init(input: input, cached: cached, output: output),
+            total: .init(input: totalInput, cached: cached, output: output))
+    }
+
+    private static func observation(
+        _ event: SanitizedForkFamilyFixture.TokenEvent) -> CodexLineageLedger.Observation
+    {
+        .init(
+            timestamp: event.timestamp,
+            last: .init(
+                input: event.last.inputTokens,
+                cached: event.last.cachedInputTokens,
+                output: event.last.outputTokens),
+            total: .init(
+                input: event.total.inputTokens,
+                cached: event.total.cachedInputTokens,
+                output: event.total.outputTokens))
+    }
+}