From 6170f5c8c74504eb6e2c100cfaac2a52feb18f10 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 11:43:01 -0400 Subject: [PATCH 01/12] Add shadow Codex lineage ledger --- .../Providers/Codex/CodexLineageLedger.swift | 163 +++++++++++++++ .../CodexLineageLedgerTests.swift | 195 ++++++++++++++++++ 2 files changed, 358 insertions(+) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift create mode 100644 Tests/CodexBarTests/CodexLineageLedgerTests.swift diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift new file mode 100644 index 0000000000..ad798a76a3 --- /dev/null +++ b/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 + } + } + } +} diff --git a/Tests/CodexBarTests/CodexLineageLedgerTests.swift b/Tests/CodexBarTests/CodexLineageLedgerTests.swift new file mode 100644 index 0000000000..434e1e7572 --- /dev/null +++ b/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)) + } +} From 547567d5168679c0b59aad1450dbfbf4ec3e8d76 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 12:52:24 -0400 Subject: [PATCH 02/12] Adapt rollout snapshots for lineage accounting --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Vendored/CostUsage/CostUsageScanner.swift | 56 +++++++++++++++-- .../CodexLineageLedgerTests.swift | 61 +++++++++++++++++++ 3 files changed, 114 insertions(+), 5 deletions(-) diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index 085fda188b..2a1047a65a 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "865e101428b49ab7" } diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index fef88de04f..9bda419158 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -98,6 +98,13 @@ enum CostUsageScanner { let totals: CostUsageCodexTotals } + private struct CodexParsedTokenEvidence { + let sessionId: String? + let forkedFromId: String? + let snapshots: [CodexTimestampedTotals] + let observations: [CodexLineageLedger.Observation] + } + enum CodexForkBaseline { case resolved(CostUsageCodexTotals?) case unresolved @@ -1680,13 +1687,13 @@ enum CostUsageScanner { private static func parseCodexTokenSnapshots( fileURL: URL, - checkCancellation: CancellationCheck? = nil) throws -> ( - sessionId: String?, - snapshots: [CodexTimestampedTotals]) + checkCancellation: CancellationCheck? = nil) throws -> CodexParsedTokenEvidence { var sessionId: String? + var forkedFromId: String? var accumulator = CodexSnapshotAccumulator() var snapshots: [CodexTimestampedTotals] = [] + var observations: [CodexLineageLedger.Observation] = [] var warnedAboutUnparsedTimestamp = false func parsedSnapshotDate(timestamp: String) -> Date? { @@ -1708,6 +1715,12 @@ enum CostUsageScanner { timestamp: timestamp, date: parsedSnapshotDate(timestamp: timestamp), totals: counted)) + if let last, let total { + observations.append(CodexLineageLedger.Observation( + timestamp: timestamp, + last: Self.lineageTotals(last), + total: Self.lineageTotals(total))) + } } do { @@ -1724,6 +1737,9 @@ enum CostUsageScanner { if sessionId == nil { sessionId = metadata.sessionId } + if forkedFromId == nil { + forkedFromId = metadata.forkedFromId + } case let .tokenCount(record): appendSnapshot(timestamp: record.timestamp, last: record.last, total: record.total) case .turnContext, .taskStarted: @@ -1746,6 +1762,9 @@ enum CostUsageScanner { ?? obj["sessionId"] as? String ?? obj["id"] as? String } + if forkedFromId == nil { + forkedFromId = Self.codexForkParentId(from: payload) + } return } @@ -1785,7 +1804,36 @@ enum CostUsageScanner { metadata: ["path": fileURL.path, "error": error.localizedDescription]) } - return (sessionId, snapshots) + return CodexParsedTokenEvidence( + sessionId: sessionId, + forkedFromId: forkedFromId, + snapshots: snapshots, + observations: observations) + } + + static func parseCodexLineageDocument( + fileURL: URL, + checkCancellation: CancellationCheck? = nil) throws -> CodexLineageLedger.Document + { + let parsed = try Self.parseCodexTokenSnapshots( + fileURL: fileURL, + checkCancellation: checkCancellation) + return CodexLineageLedger.Document( + ownerID: Self.codexRolloutOwnerID(fileURL: fileURL) ?? parsed.sessionId ?? fileURL.standardizedFileURL.path, + metadataSessionID: parsed.sessionId, + parentSessionID: parsed.forkedFromId, + observations: parsed.observations) + } + + private static func lineageTotals(_ totals: CostUsageCodexTotals) -> CodexLineageLedger.Totals { + CodexLineageLedger.Totals(input: totals.input, cached: totals.cached, output: totals.output) + } + + private static func codexRolloutOwnerID(fileURL: URL) -> String? { + let stem = fileURL.deletingPathExtension().lastPathComponent + guard stem.count >= 36 else { return nil } + let candidate = String(stem.suffix(36)) + return UUID(uuidString: candidate) == nil ? nil : candidate.lowercased() } static func parseCodexFile( diff --git a/Tests/CodexBarTests/CodexLineageLedgerTests.swift b/Tests/CodexBarTests/CodexLineageLedgerTests.swift index 434e1e7572..9a6c46c808 100644 --- a/Tests/CodexBarTests/CodexLineageLedgerTests.swift +++ b/Tests/CodexBarTests/CodexLineageLedgerTests.swift @@ -3,6 +3,56 @@ import Testing @testable import CodexBarCore struct CodexLineageLedgerTests { + @Test + func `fast rollout parser adapts complete token states into a ledger document`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let ownerID = "019f55a1-7f6e-70c0-8e4f-f5bbefa9b7ac" + let fileURL = environment.root.appendingPathComponent( + "rollout-2026-07-09T12-00-00-\(ownerID).jsonl") + let contents = [ + #"{"type":"session_meta","payload":{"id":"metadata-id","forked_from_id":"parent-id"}}"#, + Self.tokenCountLine( + timestamp: "2026-07-09T12:00:00Z", + last: (input: 100, cached: 40, output: 10), + total: (input: 100, cached: 40, output: 10)), + Self.tokenCountLine( + timestamp: "2026-07-09T12:01:00Z", + last: (input: 50, cached: 20, output: 5), + total: (input: 150, cached: 60, output: 15)), + #"{"type":"event_msg","timestamp":"2026-07-09T12:02:00Z","payload":{"type":"token_count","info":{"# + + #""total_token_usage":{"input_tokens":200,"cached_input_tokens":80,"output_tokens":20}}}}"#, + ].joined(separator: "\n") + try contents.write(to: fileURL, atomically: true, encoding: .utf8) + + let document = try CostUsageScanner.parseCodexLineageDocument(fileURL: fileURL) + + #expect(document.ownerID == ownerID) + #expect(document.metadataSessionID == "metadata-id") + #expect(document.parentSessionID == "parent-id") + #expect(document.observations.count == 2) + #expect(document.observations[0].last == .init(input: 100, cached: 40, output: 10)) + #expect(document.observations[1].total == .init(input: 150, cached: 60, output: 15)) + } + + @Test + func `ledger document parsing propagates cancellation`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let fileURL = environment.root.appendingPathComponent("rollout-without-owner.jsonl") + try Self.tokenCountLine( + timestamp: "2026-07-09T12:00:00Z", + last: (input: 100, cached: 0, output: 10), + total: (input: 100, cached: 0, output: 10)) + .write(to: fileURL, atomically: true, encoding: .utf8) + + #expect(throws: CancellationError.self) { + _ = try CostUsageScanner.parseCodexLineageDocument( + fileURL: fileURL, + checkCancellation: { throw CancellationError() }) + } + } + @Test func `transitive lineage counts copied observations once`() throws { let first = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) @@ -192,4 +242,15 @@ struct CodexLineageLedgerTests { cached: event.total.cachedInputTokens, output: event.total.outputTokens)) } + + private static func tokenCountLine( + timestamp: String, + last: (input: Int, cached: Int, output: Int), + total: (input: Int, cached: Int, output: Int)) -> String + { + #"{"type":"event_msg","timestamp":"\#(timestamp)","payload":{"type":"token_count","info":{"# + + #""last_token_usage":{"input_tokens":\#(last.input),"cached_input_tokens":\#(last.cached),"# + + #""output_tokens":\#(last.output)},"total_token_usage":{"input_tokens":\#(total.input),"# + + #""cached_input_tokens":\#(total.cached),"output_tokens":\#(total.output)}}}}"# + } } From 5c2b75e5871a25397a9ba1599746e2cac4b2bbcc Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 13:07:49 -0400 Subject: [PATCH 03/12] Discover referenced Codex lineage parents --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Codex/CodexLineageDiscovery.swift | 137 ++++++++++++++++++ .../Vendored/CostUsage/CostUsageScanner.swift | 2 +- .../CodexLineageDiscoveryTests.swift | 120 +++++++++++++++ 4 files changed, 259 insertions(+), 2 deletions(-) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift create mode 100644 Tests/CodexBarTests/CodexLineageDiscoveryTests.swift diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index 2a1047a65a..a27b750991 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "865e101428b49ab7" + static let value = "f1fe17eb233c9f4d" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift new file mode 100644 index 0000000000..0b75a82e87 --- /dev/null +++ b/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 + } + + 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 = [] + var seenPaths: Set = [] + var pendingParentIDs: [String] = [] + var unresolvedParentIDs: Set = [] + 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 + } + } + } + } +} diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index 9bda419158..b52b9e4bac 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -1829,7 +1829,7 @@ enum CostUsageScanner { CodexLineageLedger.Totals(input: totals.input, cached: totals.cached, output: totals.output) } - private static func codexRolloutOwnerID(fileURL: URL) -> String? { + static func codexRolloutOwnerID(fileURL: URL) -> String? { let stem = fileURL.deletingPathExtension().lastPathComponent guard stem.count >= 36 else { return nil } let candidate = String(stem.suffix(36)) diff --git a/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift b/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift new file mode 100644 index 0000000000..9ab3126144 --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift @@ -0,0 +1,120 @@ +import Foundation +import Testing +@testable import CodexBarCore + +struct CodexLineageDiscoveryTests { + @Test + func `referenced parents cross the normal window and active archive roots transitively`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let grandparentID = "11111111-1111-4111-8111-111111111111" + let parentID = "22222222-2222-4222-8222-222222222222" + let childID = "33333333-3333-4333-8333-333333333333" + let unrelatedID = "44444444-4444-4444-8444-444444444444" + let grandparent = try Self.writeRollout( + root: environment.codexArchivedSessionsRoot, + relativeDirectory: "", + ownerID: grandparentID, + metadataID: grandparentID) + let parent = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2025/01/01", + ownerID: parentID, + metadataID: parentID, + parentID: grandparentID) + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2026/07/09", + ownerID: childID, + metadataID: childID, + parentID: parentID) + _ = try Self.writeRollout( + root: environment.codexArchivedSessionsRoot, + relativeDirectory: "", + ownerID: unrelatedID, + metadataID: unrelatedID) + + let report = try CodexLineageDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, environment.codexArchivedSessionsRoot]) + + #expect(Set(report.documents.map(\.ownerID)) == [childID, parentID, grandparentID]) + #expect(report.documents.map(\.ownerID).contains(unrelatedID) == false) + #expect(report.referencedParentDocumentCount == 2) + #expect(report.unresolvedParentIDs.isEmpty) + #expect(FileManager.default.fileExists(atPath: parent.path)) + #expect(FileManager.default.fileExists(atPath: grandparent.path)) + } + + @Test + func `missing referenced parents are diagnosed without widening included documents`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2026/07/09", + ownerID: "55555555-5555-4555-8555-555555555555", + metadataID: "55555555-5555-4555-8555-555555555555", + parentID: "66666666-6666-4666-8666-666666666666") + + let report = try CodexLineageDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, environment.codexArchivedSessionsRoot]) + + #expect(report.documents.count == 1) + #expect(report.referencedParentDocumentCount == 0) + #expect(report.unresolvedParentIDs == ["66666666-6666-4666-8666-666666666666"]) + } + + @Test + func `uuid parent references are matched case insensitively against filename owners`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let parentID = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + _ = try Self.writeRollout( + root: environment.codexArchivedSessionsRoot, + relativeDirectory: "", + ownerID: parentID, + metadataID: "parent-metadata-alias") + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2026/07/09", + ownerID: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", + metadataID: "child-metadata", + parentID: parentID.uppercased()) + + let report = try CodexLineageDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, environment.codexArchivedSessionsRoot]) + + #expect(report.documents.map(\.ownerID).contains(parentID)) + #expect(report.referencedParentDocumentCount == 1) + #expect(report.unresolvedParentIDs.isEmpty) + } + + private static func writeRollout( + root: URL, + relativeDirectory: String, + ownerID: String, + metadataID: String, + parentID: String? = nil) throws -> URL + { + let directory = relativeDirectory.isEmpty + ? root + : root.appendingPathComponent(relativeDirectory, isDirectory: true) + try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true) + let fileURL = directory.appendingPathComponent( + "rollout-2025-01-01T00-00-00-\(ownerID).jsonl") + var metadata = #"{"type":"session_meta","payload":{"id":"\#(metadataID)""# + if let parentID { + metadata += #", "forked_from_id":"\#(parentID)""# + } + metadata += "}}\n" + metadata += #"{"type":"event_msg","timestamp":"2026-07-09T12:00:00Z","payload":{"# + metadata += #""type":"token_count","info":{"last_token_usage":{"input_tokens":10,"# + metadata += #""cached_input_tokens":0,"output_tokens":1},"total_token_usage":{"input_tokens":10,"# + metadata += #""cached_input_tokens":0,"output_tokens":1}}}}"# + try metadata.write(to: fileURL, atomically: true, encoding: .utf8) + return fileURL + } +} From 3b1c89f9bd9814837b7ff4484fc426bf7d757965 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 13:22:05 -0400 Subject: [PATCH 04/12] Preserve lineage accounting dimensions --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Providers/Codex/CodexLineageLedger.swift | 104 +++++++++++++++- .../Vendored/CostUsage/CostUsageScanner.swift | 44 ++++++- .../CodexLineageLedgerTests.swift | 115 +++++++++++++++++- 4 files changed, 255 insertions(+), 10 deletions(-) diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index a27b750991..b4eeb35463 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "f1fe17eb233c9f4d" + static let value = "a231538286ac81c9" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift index ad798a76a3..a2053a539a 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift @@ -22,8 +22,16 @@ enum CodexLineageLedger { struct Observation: Equatable, Sendable { let timestamp: String + let model: String let last: Totals let total: Totals + + init(timestamp: String, model: String = CostUsagePricing.codexUnattributedModel, last: Totals, total: Totals) { + self.timestamp = timestamp + self.model = CostUsagePricing.normalizeCodexModel(model) + self.last = last + self.total = total + } } struct Document: Equatable, Sendable { @@ -38,11 +46,24 @@ enum CodexLineageLedger { struct Report: Equatable, Sendable { let utcDays: [String: Totals] let localDays: [String: Totals] + let utcRows: [DailyRow] + let localRows: [DailyRow] let componentCount: Int let acceptedObservationCount: Int let duplicateObservationCount: Int } + struct DailyRow: Equatable, Sendable { + let day: String + let model: String + let totals: Totals + let costUSD: Double? + + var isPriced: Bool { + self.costUSD != nil + } + } + enum LedgerError: Error, Equatable { case emptyOwnerID case invalidTimestamp(String) @@ -70,28 +91,44 @@ enum CodexLineageLedger { 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 + if let existing = accepted[fingerprint] { + if existing.date < date { + continue + } + if existing.date == date, + !Self.shouldPreferModel(observation.model, over: existing.model) + { + continue + } } - accepted[fingerprint] = AcceptedObservation(date: date, last: observation.last) + accepted[fingerprint] = AcceptedObservation( + date: date, + model: observation.model, + last: observation.last) } acceptedByComponent[componentID] = accepted } var utcDays: [String: Totals] = [:] var localDays: [String: Totals] = [:] + var utcRows: [DailyRowKey: DailyRowValue] = [:] + var localRows: [DailyRowKey: DailyRowValue] = [:] 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) + Self.addRow(observation, timeZone: .gmt, to: &utcRows) + Self.addRow(observation, timeZone: localTimeZone, to: &localRows) } } return Report( utcDays: utcDays, localDays: localDays, + utcRows: Self.dailyRows(from: utcRows), + localRows: Self.dailyRows(from: localRows), componentCount: Set(documents.map { graph.find($0.ownerID) }).count, acceptedObservationCount: acceptedObservationCount, duplicateObservationCount: physicalObservationCount - acceptedObservationCount) @@ -104,14 +141,37 @@ enum CodexLineageLedger { private struct AcceptedObservation { let date: Date + let model: String let last: Totals } + private struct DailyRowKey: Hashable { + let day: String + let model: String + } + + private struct DailyRowValue { + var totals: Totals = .zero + var costUSD = 0.0 + var isPriced = true + } + private static func nonEmpty(_ value: String?) -> String? { guard let value, !value.isEmpty else { return nil } return value } + /// Duplicate copies can carry different model evidence. Keep the earliest physical copy, + /// then resolve equal-time ties deterministically while preferring attributable evidence. + private static func shouldPreferModel(_ candidate: String, over existing: String) -> Bool { + let candidateIsUnknown = CostUsagePricing.isCodexUnattributedModel(candidate) + let existingIsUnknown = CostUsagePricing.isCodexUnattributedModel(existing) + if candidateIsUnknown != existingIsUnknown { + return !candidateIsUnknown + } + return candidate < existing + } + private static func date(from timestamp: String) throws -> Date { guard let date = CostUsageScanner.dateFromTimestamp(timestamp) else { throw LedgerError.invalidTimestamp(timestamp) @@ -135,6 +195,44 @@ enum CodexLineageLedger { days[key] = dayTotals } + private static func addRow( + _ observation: AcceptedObservation, + timeZone: TimeZone, + to rows: inout [DailyRowKey: DailyRowValue]) + { + let key = DailyRowKey(day: self.dayKey(for: observation.date, timeZone: timeZone), model: observation.model) + var value = rows[key] ?? DailyRowValue() + value.totals.add(observation.last) + if let cost = CostUsagePricing.codexCostUSD( + model: observation.model, + inputTokens: observation.last.input, + cachedInputTokens: observation.last.cached, + outputTokens: observation.last.output) + { + value.costUSD += cost + } else { + value.isPriced = false + } + rows[key] = value + } + + private static func dailyRows(from rows: [DailyRowKey: DailyRowValue]) -> [DailyRow] { + rows.map { key, value in + DailyRow( + day: key.day, + model: key.model, + totals: value.totals, + costUSD: value.isPriced ? value.costUSD : nil) + }.sorted { ($0.day, $0.model) < ($1.day, $1.model) } + } + + private static func dayKey(for date: Date, timeZone: TimeZone) -> String { + var calendar = Calendar(identifier: .gregorian) + calendar.timeZone = timeZone + let components = calendar.dateComponents([.year, .month, .day], from: date) + return String(format: "%04d-%02d-%02d", components.year ?? 0, components.month ?? 0, components.day ?? 0) + } + private struct DisjointSet { private var parents: [String: String] = [:] diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index b52b9e4bac..aa7f0cc51b 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -1685,12 +1685,14 @@ enum CostUsageScanner { return nil } + // swiftlint:disable:next cyclomatic_complexity private static func parseCodexTokenSnapshots( fileURL: URL, checkCancellation: CancellationCheck? = nil) throws -> CodexParsedTokenEvidence { var sessionId: String? var forkedFromId: String? + var currentModel: String? var accumulator = CodexSnapshotAccumulator() var snapshots: [CodexTimestampedTotals] = [] var observations: [CodexLineageLedger.Observation] = [] @@ -1708,7 +1710,12 @@ enum CostUsageScanner { return date } - func appendSnapshot(timestamp: String, last: CostUsageCodexTotals?, total: CostUsageCodexTotals?) { + func appendSnapshot( + timestamp: String, + model: String?, + last: CostUsageCodexTotals?, + total: CostUsageCodexTotals?) + { guard last != nil || total != nil else { return } let counted = accumulator.apply(last: last, total: total) snapshots.append(CodexTimestampedTotals( @@ -1718,6 +1725,9 @@ enum CostUsageScanner { if let last, let total { observations.append(CodexLineageLedger.Observation( timestamp: timestamp, + model: Self.codexModelEvidence(model) + ?? Self.codexModelEvidence(currentModel) + ?? CostUsagePricing.codexUnattributedModel, last: Self.lineageTotals(last), total: Self.lineageTotals(total))) } @@ -1741,8 +1751,16 @@ enum CostUsageScanner { forkedFromId = metadata.forkedFromId } case let .tokenCount(record): - appendSnapshot(timestamp: record.timestamp, last: record.last, total: record.total) - case .turnContext, .taskStarted: + appendSnapshot( + timestamp: record.timestamp, + model: record.model, + last: record.last, + total: record.total) + case let .turnContext(model): + if let model { + currentModel = model + } + case .taskStarted: break } return @@ -1768,6 +1786,20 @@ enum CostUsageScanner { return } + if obj["type"] as? String == "turn_context" { + let payload = obj["payload"] as? [String: Any] + let info = payload?["info"] as? [String: Any] + if let model = Self.codexTurnContextModel( + payloadModel: payload?["model"] as? String, + payloadModelName: payload?["model_name"] as? String, + infoModel: info?["model"] as? String, + infoModelName: info?["model_name"] as? String) + { + currentModel = model + } + return + } + guard obj["type"] as? String == "event_msg" else { return } guard let payload = obj["payload"] as? [String: Any] else { return } guard payload["type"] as? String == "token_count" else { return } @@ -1793,7 +1825,11 @@ enum CostUsageScanner { cached: max(0, toInt($0["cached_input_tokens"] ?? $0["cache_read_input_tokens"])), output: max(0, toInt($0["output_tokens"]))) } - appendSnapshot(timestamp: timestamp, last: last, total: total) + let model = Self.codexModelEvidence(info["model"] as? String) + ?? Self.codexModelEvidence(info["model_name"] as? String) + ?? Self.codexModelEvidence(payload["model"] as? String) + ?? Self.codexModelEvidence(obj["model"] as? String) + appendSnapshot(timestamp: timestamp, model: model, last: last, total: total) } }) } catch is CancellationError { diff --git a/Tests/CodexBarTests/CodexLineageLedgerTests.swift b/Tests/CodexBarTests/CodexLineageLedgerTests.swift index 9a6c46c808..aca6368d34 100644 --- a/Tests/CodexBarTests/CodexLineageLedgerTests.swift +++ b/Tests/CodexBarTests/CodexLineageLedgerTests.swift @@ -12,6 +12,7 @@ struct CodexLineageLedgerTests { "rollout-2026-07-09T12-00-00-\(ownerID).jsonl") let contents = [ #"{"type":"session_meta","payload":{"id":"metadata-id","forked_from_id":"parent-id"}}"#, + #"{"type":"turn_context","payload":{"model":"gpt-5.4"}}"#, Self.tokenCountLine( timestamp: "2026-07-09T12:00:00Z", last: (input: 100, cached: 40, output: 10), @@ -31,10 +32,116 @@ struct CodexLineageLedgerTests { #expect(document.metadataSessionID == "metadata-id") #expect(document.parentSessionID == "parent-id") #expect(document.observations.count == 2) + #expect(document.observations[0].model == "gpt-5.4") #expect(document.observations[0].last == .init(input: 100, cached: 40, output: 10)) #expect(document.observations[1].total == .init(input: 150, cached: 60, output: 15)) } + @Test + func `daily rows preserve model token and pricing dimensions`() throws { + let priced = Self.observation( + timestamp: "2026-07-10T02:00:00Z", + model: "gpt-5.4", + input: 100, + cached: 40, + output: 10, + totalInput: 100) + let unpriced = Self.observation( + timestamp: "2026-07-10T03:00:00Z", + model: "future-model", + input: 50, + output: 5, + totalInput: 150) + + let report = try CodexLineageLedger.reconcile( + documents: [Self.document(owner: "root", observations: [priced, unpriced])], + localTimeZone: #require(TimeZone(identifier: "America/New_York"))) + + #expect(report.utcRows.map(\.day) == ["2026-07-10", "2026-07-10"]) + #expect(report.localRows.map(\.day) == ["2026-07-09", "2026-07-09"]) + #expect(report.utcRows[0].model == "future-model") + #expect(report.utcRows[0].totals == .init(input: 50, cached: 0, output: 5)) + #expect(report.utcRows[0].isPriced == false) + #expect(report.utcRows[1].model == "gpt-5.4") + #expect(report.utcRows[1].isPriced) + #expect(report.utcRows[1].costUSD != nil) + } + + @Test + func `token event model overrides older turn context`() throws { + let environment = try CostUsageTestEnvironment() + let ownerID = "11111111-1111-4111-8111-111111111111" + let file = environment.codexSessionsRoot.appendingPathComponent( + "rollout-2026-07-09T12-00-00-\(ownerID).jsonl") + let contents = [ + #"{"type":"turn_context","payload":{"model":"gpt-5.4-mini"}}"#, + Self.tokenCountLine( + timestamp: "2026-07-09T12:00:00Z", + model: "gpt-5.4", + last: (input: 100, cached: 40, output: 10), + total: (input: 100, cached: 40, output: 10)), + ].joined(separator: "\n") + try FileManager.default.createDirectory(at: environment.codexSessionsRoot, withIntermediateDirectories: true) + try contents.write(to: file, atomically: true, encoding: .utf8) + + let document = try CostUsageScanner.parseCodexLineageDocument(fileURL: file) + + #expect(document.observations.map(\.model) == ["gpt-5.4"]) + } + + @Test + func `equal-time duplicate prefers attributed model deterministically`() throws { + let unknown = Self.observation(timestamp: "2026-07-10T03:00:00Z", input: 50, totalInput: 50) + let attributed = Self.observation( + timestamp: "2026-07-10T03:00:00Z", + model: "gpt-5.4", + input: 50, + totalInput: 50) + + let report = try CodexLineageLedger.reconcile( + documents: [ + Self.document(owner: "child", parent: "root", observations: [unknown]), + Self.document(owner: "root", observations: [attributed]), + ], + localTimeZone: .gmt) + + #expect(report.acceptedObservationCount == 1) + #expect(report.utcRows.map(\.model) == ["gpt-5.4"]) + #expect(report.utcRows[0].isPriced) + } + + @Test + func `daily rows price long context observations independently`() throws { + let first = Self.observation( + timestamp: "2026-07-10T03:00:00Z", + model: "gpt-5.4", + input: 272_001, + cached: 100_000, + output: 5, + totalInput: 272_001) + let second = Self.observation( + timestamp: "2026-07-10T04:00:00Z", + model: "gpt-5.4", + input: 100, + output: 5, + totalInput: 272_101) + let expected = try #require(CostUsagePricing.codexCostUSD( + model: "gpt-5.4", + inputTokens: 272_001, + cachedInputTokens: 100_000, + outputTokens: 5)) + #require(CostUsagePricing.codexCostUSD( + model: "gpt-5.4", + inputTokens: 100, + cachedInputTokens: 0, + outputTokens: 5)) + + let report = try CodexLineageLedger.reconcile( + documents: [Self.document(owner: "root", observations: [first, second])], + localTimeZone: .gmt) + + #expect(try abs(#require(report.utcRows.first?.costUSD) - expected) < 0.000001) + } + @Test func `ledger document parsing propagates cancellation`() throws { let environment = try CostUsageTestEnvironment() @@ -217,6 +324,7 @@ struct CodexLineageLedgerTests { private static func observation( timestamp: String, + model: String = CostUsagePricing.codexUnattributedModel, input: Int, cached: Int = 0, output: Int = 0, @@ -224,6 +332,7 @@ struct CodexLineageLedgerTests { { .init( timestamp: timestamp, + model: model, last: .init(input: input, cached: cached, output: output), total: .init(input: totalInput, cached: cached, output: output)) } @@ -245,12 +354,14 @@ struct CodexLineageLedgerTests { private static func tokenCountLine( timestamp: String, + model: String? = nil, last: (input: Int, cached: Int, output: Int), total: (input: Int, cached: Int, output: Int)) -> String { - #"{"type":"event_msg","timestamp":"\#(timestamp)","payload":{"type":"token_count","info":{"# + let modelJSON = model.map { #", "model":"\#($0)""# } ?? "" + return #"{"type":"event_msg","timestamp":"\#(timestamp)","payload":{"type":"token_count","info":{"# + #""last_token_usage":{"input_tokens":\#(last.input),"cached_input_tokens":\#(last.cached),"# + #""output_tokens":\#(last.output)},"total_token_usage":{"input_tokens":\#(total.input),"# - + #""cached_input_tokens":\#(total.cached),"output_tokens":\#(total.output)}}}}"# + + #""cached_input_tokens":\#(total.cached),"output_tokens":\#(total.output)}\#(modelJSON)}}}"# } } From 19d63cb10c5cfb66319bfa38806b00273bc2f909 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 13:39:06 -0400 Subject: [PATCH 05/12] Run Codex lineage accounting in shadow --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Providers/Codex/CodexLineageLedger.swift | 11 ++- .../Providers/Codex/CodexLineageShadow.swift | 94 +++++++++++++++++++ .../Vendored/CostUsage/CostUsageScanner.swift | 55 ++++++++++- .../CodexLineageShadowTests.swift | 68 ++++++++++++++ 5 files changed, 226 insertions(+), 4 deletions(-) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift create mode 100644 Tests/CodexBarTests/CodexLineageShadowTests.swift diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index b4eeb35463..d57f41412c 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "a231538286ac81c9" + static let value = "07457314442f300f" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift index a2053a539a..bf59ca377a 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift @@ -69,9 +69,14 @@ enum CodexLineageLedger { case invalidTimestamp(String) } - static func reconcile(documents: [Document], localTimeZone: TimeZone) throws -> Report { + static func reconcile( + documents: [Document], + localTimeZone: TimeZone, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> Report + { var graph = DisjointSet() for document in documents { + try checkCancellation?() guard !document.ownerID.isEmpty else { throw LedgerError.emptyOwnerID } graph.insert(document.ownerID) if let metadataSessionID = Self.nonEmpty(document.metadataSessionID) { @@ -85,9 +90,11 @@ enum CodexLineageLedger { var acceptedByComponent: [String: [Fingerprint: AcceptedObservation]] = [:] var physicalObservationCount = 0 for document in documents { + try checkCancellation?() let componentID = graph.find(document.ownerID) var accepted = acceptedByComponent[componentID] ?? [:] for observation in document.observations { + try checkCancellation?() physicalObservationCount += 1 let date = try Self.date(from: observation.timestamp) let fingerprint = Fingerprint(last: observation.last, total: observation.total) @@ -115,8 +122,10 @@ enum CodexLineageLedger { var localRows: [DailyRowKey: DailyRowValue] = [:] var acceptedObservationCount = 0 for accepted in acceptedByComponent.values { + try checkCancellation?() acceptedObservationCount += accepted.count for observation in accepted.values { + try checkCancellation?() Self.add(observation.last, on: observation.date, timeZone: .gmt, to: &utcDays) Self.add(observation.last, on: observation.date, timeZone: localTimeZone, to: &localDays) Self.addRow(observation, timeZone: .gmt, to: &utcRows) diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift new file mode 100644 index 0000000000..a6938113e0 --- /dev/null +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift @@ -0,0 +1,94 @@ +import Foundation + +/// Privacy-safe comparison between the production file scanner and the experimental lineage ledger. +enum CodexLineageShadow { + struct DayDifference: Equatable, Sendable { + let day: String + let legacy: CodexLineageLedger.Totals + let ledger: CodexLineageLedger.Totals + + var delta: CodexLineageLedger.Totals { + .init( + input: self.ledger.input - self.legacy.input, + cached: self.ledger.cached - self.legacy.cached, + output: self.ledger.output - self.legacy.output) + } + } + + struct Report: Equatable, Sendable { + let days: [DayDifference] + let acceptedObservationCount: Int + let duplicateObservationCount: Int + let componentCount: Int + let referencedParentDocumentCount: Int + let unresolvedParentCount: Int + let rejectedObservationCount: Int + } + + static func run( + includedFiles: [URL], + roots: [URL], + legacyDays: [String: [String: [Int]]], + dayRange: ClosedRange, + localTimeZone: TimeZone, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> Report + { + let discovery = try CodexLineageDiscovery.discover( + includedFiles: includedFiles, + roots: roots, + checkCancellation: checkCancellation) + var rejectedObservationCount = 0 + var documents: [CodexLineageLedger.Document] = [] + documents.reserveCapacity(discovery.documents.count) + for document in discovery.documents { + try checkCancellation?() + var observations: [CodexLineageLedger.Observation] = [] + observations.reserveCapacity(document.observations.count) + for observation in document.observations { + try checkCancellation?() + let accepted = CostUsageScanner.dateFromTimestamp(observation.timestamp) != nil + if !accepted { + rejectedObservationCount += 1 + } else { + observations.append(observation) + } + } + documents.append(CodexLineageLedger.Document( + ownerID: document.ownerID, + metadataSessionID: document.metadataSessionID, + parentSessionID: document.parentSessionID, + observations: observations)) + } + let ledger = try CodexLineageLedger.reconcile( + documents: documents, + localTimeZone: localTimeZone, + checkCancellation: checkCancellation) + let legacy = Self.legacyTotalsByDay(legacyDays) + let dayKeys = Set(legacy.keys).union(ledger.localDays.keys) + .filter(dayRange.contains) + .sorted() + let days = dayKeys.map { day in + DayDifference(day: day, legacy: legacy[day] ?? .zero, ledger: ledger.localDays[day] ?? .zero) + } + return Report( + days: days, + acceptedObservationCount: ledger.acceptedObservationCount, + duplicateObservationCount: ledger.duplicateObservationCount, + componentCount: ledger.componentCount, + referencedParentDocumentCount: discovery.referencedParentDocumentCount, + unresolvedParentCount: discovery.unresolvedParentIDs.count, + rejectedObservationCount: rejectedObservationCount) + } + + private static func legacyTotalsByDay( + _ days: [String: [String: [Int]]]) -> [String: CodexLineageLedger.Totals] + { + days.mapValues { models in + models.values.reduce(into: CodexLineageLedger.Totals.zero) { totals, packed in + totals.input += packed[safe: 0] ?? 0 + totals.cached += packed[safe: 1] ?? 0 + totals.output += packed[safe: 2] ?? 0 + } + } + } +} diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index aa7f0cc51b..08c25b83e3 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -1704,8 +1704,7 @@ enum CostUsageScanner { warnedAboutUnparsedTimestamp = true self.log.warning( "Codex cost usage could not parse parent token snapshot timestamp; " - + "falling back to lexical comparison", - metadata: ["path": fileURL.path, "timestamp": timestamp]) + + "falling back to lexical comparison") } return date } @@ -2543,6 +2542,7 @@ enum CostUsageScanner { shouldRefresh: shouldRefresh) } + // swiftlint:disable:next function_body_length private static func loadCodexDaily( range: CostUsageDayRange, now: Date, @@ -2676,6 +2676,12 @@ enum CostUsageScanner { ? [cachedUntilKey, range.scanUntilKey].compactMap(\.self).max() ?? range.scanUntilKey : range.scanUntilKey Self.pruneDays(cache: &cache, sinceKey: retainedSinceKey, untilKey: retainedUntilKey) + try Self.recordCodexLineageShadow( + files: files, + roots: plan.roots, + cache: cache, + range: range, + checkCancellation: checkCancellation) cache.roots = plan.rootsFingerprint cache.scanSinceKey = retainedSinceKey cache.scanUntilKey = retainedUntilKey @@ -2709,6 +2715,51 @@ enum CostUsageScanner { priorityTurns: plan.priorityTurns) } + private static func recordCodexLineageShadow( + files: [URL], + roots: [URL], + cache: CostUsageCache, + range: CostUsageDayRange, + checkCancellation: CancellationCheck?) throws + { + do { + let report = try CodexLineageShadow.run( + includedFiles: files, + roots: roots, + legacyDays: cache.days, + dayRange: range.sinceKey...range.untilKey, + localTimeZone: .current, + checkCancellation: checkCancellation) + self.log.info( + "Codex lineage shadow comparison completed", + metadata: [ + "accepted": "\(report.acceptedObservationCount)", + "components": "\(report.componentCount)", + "days": "\(report.days.count)", + "duplicates": "\(report.duplicateObservationCount)", + "referencedParents": "\(report.referencedParentDocumentCount)", + "rejected": "\(report.rejectedObservationCount)", + "unresolvedParents": "\(report.unresolvedParentCount)", + ]) + for day in report.days where day.delta != .zero { + self.log.info( + "Codex lineage shadow daily difference", + metadata: [ + "cachedDelta": "\(day.delta.cached)", + "day": "\(day.day)", + "inputDelta": "\(day.delta.input)", + "outputDelta": "\(day.delta.output)", + ]) + } + } catch is CancellationError { + throw CancellationError() + } catch { + self.log.warning( + "Codex lineage shadow comparison failed", + metadata: ["errorType": "\(type(of: error))"]) + } + } + private static func codexFileScanContext( range: CostUsageDayRange, options: Options, diff --git a/Tests/CodexBarTests/CodexLineageShadowTests.swift b/Tests/CodexBarTests/CodexLineageShadowTests.swift new file mode 100644 index 0000000000..51eb59adfc --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageShadowTests.swift @@ -0,0 +1,68 @@ +import Foundation +import Testing +@testable import CodexBarCore + +struct CodexLineageShadowTests { + @Test + func `shadow comparison records deltas and diagnostics without changing legacy totals`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let parentID = "11111111-1111-4111-8111-111111111111" + let childID = "22222222-2222-4222-8222-222222222222" + let parent = try Self.writeRollout( + root: environment.codexSessionsRoot, + ownerID: parentID, + metadataID: parentID, + events: [Self.event(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100)]) + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + ownerID: childID, + metadataID: childID, + parentID: parentID, + events: [ + Self.event(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100), + Self.event(timestamp: "not-a-time", input: 50, totalInput: 150), + ]) + let legacyDays = ["2026-07-09": ["gpt-5.4": [150, 20, 10]]] + + let report = try CodexLineageShadow.run( + includedFiles: [parent, child], + roots: [environment.codexSessionsRoot], + legacyDays: legacyDays, + dayRange: "2026-07-09"..."2026-07-09", + localTimeZone: .gmt) + + #expect(legacyDays["2026-07-09"]?["gpt-5.4"] == [150, 20, 10]) + #expect(report.days == [.init( + day: "2026-07-09", + legacy: .init(input: 150, cached: 20, output: 10), + ledger: .init(input: 100, cached: 0, output: 0))]) + #expect(report.days[0].delta == .init(input: -50, cached: -20, output: -10)) + #expect(report.acceptedObservationCount == 1) + #expect(report.duplicateObservationCount == 1) + #expect(report.componentCount == 1) + #expect(report.rejectedObservationCount == 1) + #expect(report.unresolvedParentCount == 0) + } + + private static func writeRollout( + root: URL, + ownerID: String, + metadataID: String, + parentID: String? = nil, + events: [String]) throws -> URL + { + try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) + let file = root.appendingPathComponent("rollout-2026-07-09T12-00-00-\(ownerID).jsonl") + let parent = parentID.map { #", "forked_from_id":"\#($0)""# } ?? "" + let metadata = #"{"type":"session_meta","payload":{"id":"\#(metadataID)"\#(parent)}}"# + try ([metadata] + events).joined(separator: "\n").write(to: file, atomically: true, encoding: .utf8) + return file + } + + private static func event(timestamp: String, input: Int, totalInput: Int) -> String { + #"{"type":"event_msg","timestamp":"\#(timestamp)","payload":{"type":"token_count","info":{"# + + #""last_token_usage":{"input_tokens":\#(input),"cached_input_tokens":0,"output_tokens":0},"# + + #""total_token_usage":{"input_tokens":\#(totalInput),"cached_input_tokens":0,"output_tokens":0}}}}"# + } +} From a140e7df7e8850502703ba8a03545d0b0d253be5 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 13:59:06 -0400 Subject: [PATCH 06/12] Classify Codex lineage residuals --- .../CodexLineageResidualClassifier.swift | 189 ++++++++++++++++++ .../CodexLineageResidualClassifierTests.swift | 147 ++++++++++++++ 2 files changed, 336 insertions(+) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageResidualClassifier.swift create mode 100644 Tests/CodexBarTests/CodexLineageResidualClassifierTests.swift diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageResidualClassifier.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageResidualClassifier.swift new file mode 100644 index 0000000000..5311942c77 --- /dev/null +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageResidualClassifier.swift @@ -0,0 +1,189 @@ +import Foundation + +/// Classifies differences between local Codex accounting paths and a finalized UTC usage source. +/// +/// This is an analysis seam, not an oracle-tuning mechanism. Callers supply independently observed +/// totals and corpus diagnostics; the classifier only applies a documented, bounded policy. +enum CodexLineageResidualClassifier { + enum Classification: String, Equatable, Sendable { + case invalidInput + case provisional + case withinTolerance + case unavailableHistory + case unsupportedEventShape + case utcLocalAttribution + case accountingSemantics + case containment + case ledgerDefect + } + + struct Evidence: Equatable, Sendable { + var localCorpusWasExhaustive = false + var rejectedObservationCount = 0 + var unresolvedParentCount = 0 + var duplicateObservationCount = 0 + } + + struct Sample: Equatable, Sendable { + let day: String + let referenceTokens: Int + let isReferenceFinalized: Bool + let isOrdinaryDay: Bool + let legacyTokens: Int + let ledgerUTCTokens: Int + let ledgerLocalTokens: Int + let evidence: Evidence + } + + struct DayResult: Equatable, Sendable { + let day: String + let classification: Classification + let legacyAbsoluteError: Int? + let ledgerAbsoluteError: Int? + } + + struct Report: Equatable, Sendable { + let days: [DayResult] + let finalizedReferenceTokens: Int + let finalizedLegacyTokens: Int + let finalizedLedgerTokens: Int + let legacyAbsoluteError: Int + let ledgerAbsoluteError: Int + let ordinaryDayRegressionCount: Int + let invalidSampleCount: Int + + var improvesAggregateError: Bool { + self.ledgerAbsoluteError < self.legacyAbsoluteError + } + } + + struct Policy: Equatable, Sendable { + /// A residual no larger than this fraction of the reference is not assigned a speculative cause. + let largeResidualFraction: Double + /// Ordinary days may move by this fraction before the ledger is considered regressive. + let ordinaryDayRegressionFraction: Double + + static let validation = Self( + largeResidualFraction: 0.05, + ordinaryDayRegressionFraction: 0.01) + } + + static func classify(samples: [Sample], policy: Policy = .validation) -> Report { + let ordered = samples.sorted { $0.day < $1.day } + let days = ordered.map { sample -> DayResult in + guard Self.isValid(sample: sample, policy: policy) else { + return DayResult( + day: sample.day, + classification: .invalidInput, + legacyAbsoluteError: nil, + ledgerAbsoluteError: nil) + } + guard sample.isReferenceFinalized else { + return DayResult( + day: sample.day, + classification: .provisional, + legacyAbsoluteError: nil, + ledgerAbsoluteError: nil) + } + let legacyError = Self.absoluteDifference(sample.legacyTokens, sample.referenceTokens) + let ledgerError = Self.absoluteDifference(sample.ledgerUTCTokens, sample.referenceTokens) + return DayResult( + day: sample.day, + classification: Self.classification( + sample: sample, + legacyError: legacyError, + ledgerError: ledgerError, + policy: policy), + legacyAbsoluteError: legacyError, + ledgerAbsoluteError: ledgerError) + } + + let finalized = ordered.filter { $0.isReferenceFinalized && Self.isValid(sample: $0, policy: policy) } + let referenceTokens = finalized.reduce(0) { Self.saturatingSum($0, $1.referenceTokens) } + let legacyTokens = finalized.reduce(0) { Self.saturatingSum($0, $1.legacyTokens) } + let ledgerTokens = finalized.reduce(0) { Self.saturatingSum($0, $1.ledgerUTCTokens) } + let ordinaryDayRegressionCount = finalized.count { sample in + guard sample.isOrdinaryDay else { return false } + let allowed = Self.threshold( + reference: sample.referenceTokens, + fraction: policy.ordinaryDayRegressionFraction) + return Self.absoluteDifference(sample.ledgerUTCTokens, sample.referenceTokens) + > Self.saturatingSum(Self.absoluteDifference(sample.legacyTokens, sample.referenceTokens), allowed) + } + + return Report( + days: days, + finalizedReferenceTokens: referenceTokens, + finalizedLegacyTokens: legacyTokens, + finalizedLedgerTokens: ledgerTokens, + legacyAbsoluteError: Self.absoluteDifference(legacyTokens, referenceTokens), + ledgerAbsoluteError: Self.absoluteDifference(ledgerTokens, referenceTokens), + ordinaryDayRegressionCount: ordinaryDayRegressionCount, + invalidSampleCount: days.count { $0.classification == .invalidInput }) + } + + private static func classification( + sample: Sample, + legacyError: Int, + ledgerError: Int, + policy: Policy) -> Classification + { + let largeResidual = Self.threshold( + reference: sample.referenceTokens, + fraction: policy.largeResidualFraction) + guard ledgerError > largeResidual else { return .withinTolerance } + if sample.evidence.rejectedObservationCount > 0 { + return .unsupportedEventShape + } + + let ordinaryAllowance = Self.threshold( + reference: sample.referenceTokens, + fraction: policy.ordinaryDayRegressionFraction) + if sample.isOrdinaryDay, ledgerError > Self.saturatingSum(legacyError, ordinaryAllowance) { + return .ledgerDefect + } + + let localError = Self.absoluteDifference(sample.ledgerLocalTokens, sample.referenceTokens) + if Self.saturatingSum(ledgerError, ordinaryAllowance) < localError { + return .utcLocalAttribution + } + if sample.evidence.unresolvedParentCount > 0 { + return .containment + } + if sample.evidence.localCorpusWasExhaustive, sample.ledgerUTCTokens < sample.referenceTokens { + return .unavailableHistory + } + if sample.evidence.duplicateObservationCount > 0, ledgerError < legacyError { + return .containment + } + return .accountingSemantics + } + + private static func threshold(reference: Int, fraction: Double) -> Int { + let value = (Double(reference) * fraction).rounded(.up) + return value >= Double(Int.max) ? Int.max : Int(value) + } + + private static func absoluteDifference(_ lhs: Int, _ rhs: Int) -> Int { + lhs >= rhs ? lhs - rhs : rhs - lhs + } + + private static func isValid(sample: Sample, policy: Policy) -> Bool { + sample.referenceTokens >= 0 && + sample.legacyTokens >= 0 && + sample.ledgerUTCTokens >= 0 && + sample.ledgerLocalTokens >= 0 && + sample.evidence.rejectedObservationCount >= 0 && + sample.evidence.unresolvedParentCount >= 0 && + sample.evidence.duplicateObservationCount >= 0 && + policy.largeResidualFraction.isFinite && + policy.largeResidualFraction >= 0 && + policy.ordinaryDayRegressionFraction.isFinite && + policy.ordinaryDayRegressionFraction >= 0 + } + + private static func saturatingSum(_ lhs: Int, _ rhs: Int) -> Int { + let (sum, overflow) = lhs.addingReportingOverflow(rhs) + return overflow ? Int.max : sum + } +} diff --git a/Tests/CodexBarTests/CodexLineageResidualClassifierTests.swift b/Tests/CodexBarTests/CodexLineageResidualClassifierTests.swift new file mode 100644 index 0000000000..b583256e00 --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageResidualClassifierTests.swift @@ -0,0 +1,147 @@ +import Testing +@testable import CodexBarCore + +struct CodexLineageResidualClassifierTests { + @Test + func `sanitized finalized UTC replay materially closes the aggregate gap`() { + let report = CodexLineageResidualClassifier.classify(samples: Self.forkHeavySamples) + + #expect(report.finalizedReferenceTokens == 3_692_873_480) + #expect(report.finalizedLegacyTokens == 2_882_545_128) + #expect(report.finalizedLedgerTokens == 3_589_444_942) + #expect(report.legacyAbsoluteError == 810_328_352) + #expect(report.ledgerAbsoluteError == 103_428_538) + #expect(report.improvesAggregateError) + #expect(report.days.allSatisfy { day in + guard let legacy = day.legacyAbsoluteError, let ledger = day.ledgerAbsoluteError else { return true } + return ledger < legacy + }) + } + + @Test + func `large undercount is unavailable history only after exhaustive local checks`() { + let verified = CodexLineageResidualClassifier.classify(samples: [Self.forkHeavySamples[0]]) + #expect(verified.days.first?.classification == .unavailableHistory) + + var incomplete = Self.forkHeavySamples[0] + incomplete = .init( + day: incomplete.day, + referenceTokens: incomplete.referenceTokens, + isReferenceFinalized: true, + isOrdinaryDay: false, + legacyTokens: incomplete.legacyTokens, + ledgerUTCTokens: incomplete.ledgerUTCTokens, + ledgerLocalTokens: incomplete.ledgerLocalTokens, + evidence: .init(localCorpusWasExhaustive: false)) + let unverified = CodexLineageResidualClassifier.classify(samples: [incomplete]) + #expect(unverified.days.first?.classification == .accountingSemantics) + } + + @Test + func `ordinary non-fork days do not materially regress`() { + let samples = [ + Self.ordinary(day: "2026-06-29", legacy: 120_000_000, ledger: 120_000_000), + Self.ordinary(day: "2026-06-30", legacy: 180_000_000, ledger: 180_000_000), + Self.ordinary(day: "2026-07-05", legacy: 290_018_710, ledger: 290_777_623), + Self.ordinary(day: "2026-07-06", legacy: 435_123_419, ledger: 435_123_419), + Self.ordinary(day: "2026-07-07", legacy: 324_480_000, ledger: 324_480_000), + Self.ordinary(day: "2026-07-08", legacy: 240_000_000, ledger: 240_000_000), + ] + + let report = CodexLineageResidualClassifier.classify(samples: samples) + #expect(report.ordinaryDayRegressionCount == 0) + #expect(report.days.allSatisfy { $0.classification == .withinTolerance }) + } + + @Test + func `reference day remains provisional until finalized`() { + let sample = CodexLineageResidualClassifier.Sample( + day: "2026-07-12", + referenceTokens: 618_121_840, + isReferenceFinalized: false, + isOrdinaryDay: false, + legacyTokens: 600_000_000, + ledgerUTCTokens: 615_000_000, + ledgerLocalTokens: 610_000_000, + evidence: .init()) + + let report = CodexLineageResidualClassifier.classify(samples: [sample]) + #expect(report.days.first?.classification == .provisional) + #expect(report.finalizedReferenceTokens == 0) + #expect(report.days.first?.ledgerAbsoluteError == nil) + } + + @Test + func `invalid token evidence is excluded without overflowing aggregate totals`() { + let invalid = CodexLineageResidualClassifier.Sample( + day: "2026-07-08", + referenceTokens: -1, + isReferenceFinalized: true, + isOrdinaryDay: true, + legacyTokens: 10, + ledgerUTCTokens: 10, + ledgerLocalTokens: 10, + evidence: .init()) + let large = CodexLineageResidualClassifier.Sample( + day: "2026-07-09", + referenceTokens: Int.max, + isReferenceFinalized: true, + isOrdinaryDay: false, + legacyTokens: Int.max, + ledgerUTCTokens: Int.max, + ledgerLocalTokens: Int.max, + evidence: .init()) + + let report = CodexLineageResidualClassifier.classify(samples: [invalid, large, large]) + + #expect(report.days.first?.classification == .invalidInput) + #expect(report.invalidSampleCount == 1) + #expect(report.finalizedReferenceTokens == Int.max) + #expect(report.finalizedLegacyTokens == Int.max) + #expect(report.finalizedLedgerTokens == Int.max) + #expect(report.legacyAbsoluteError == 0) + #expect(report.ledgerAbsoluteError == 0) + } + + private static let forkHeavySamples = [ + CodexLineageResidualClassifier.Sample( + day: "2026-07-09", + referenceTokens: 852_682_935, + isReferenceFinalized: true, + isOrdinaryDay: false, + legacyTokens: 946_818_053, + ledgerUTCTokens: 764_026_920, + ledgerLocalTokens: 764_026_920, + evidence: .init(localCorpusWasExhaustive: true, duplicateObservationCount: 100)), + CodexLineageResidualClassifier.Sample( + day: "2026-07-10", + referenceTokens: 1_580_199_588, + isReferenceFinalized: true, + isOrdinaryDay: false, + legacyTokens: 1_414_122_342, + ledgerUTCTokens: 1_510_013_760, + ledgerLocalTokens: 1_430_000_000, + evidence: .init(localCorpusWasExhaustive: true, duplicateObservationCount: 100)), + CodexLineageResidualClassifier.Sample( + day: "2026-07-11", + referenceTokens: 1_259_990_957, + isReferenceFinalized: true, + isOrdinaryDay: false, + legacyTokens: 521_604_733, + ledgerUTCTokens: 1_315_404_262, + ledgerLocalTokens: 1_200_000_000, + evidence: .init(localCorpusWasExhaustive: true, duplicateObservationCount: 100)), + ] + + private static func ordinary(day: String, legacy: Int, ledger: Int) -> CodexLineageResidualClassifier.Sample { + .init( + day: day, + referenceTokens: legacy, + isReferenceFinalized: true, + isOrdinaryDay: true, + legacyTokens: legacy, + ledgerUTCTokens: ledger, + ledgerLocalTokens: ledger, + evidence: .init(localCorpusWasExhaustive: true)) + } +} From 5bf1836bb625e42a6687d6c34c03464df676bdf7 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 14:24:42 -0400 Subject: [PATCH 07/12] Handle ambiguous Codex lineage evidence --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Codex/CodexLineageDiscovery.swift | 102 +++++--- .../Providers/Codex/CodexLineageLedger.swift | 246 +++++++++++++++++- .../Providers/Codex/CodexLineageShadow.swift | 44 +++- .../Vendored/CostUsage/CostUsageScanner.swift | 31 ++- .../CodexLineageDiscoveryTests.swift | 101 ++++++- .../CodexLineageLedgerTests.swift | 164 ++++++++++++ .../CodexLineageShadowTests.swift | 13 +- 8 files changed, 645 insertions(+), 58 deletions(-) diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index d57f41412c..90a5d3ff38 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "07457314442f300f" + static let value = "4c426503aec9cb49" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift index 0b75a82e87..8d61444a76 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageDiscovery.swift @@ -5,7 +5,7 @@ enum CodexLineageDiscovery { struct Report: Equatable, Sendable { let documents: [CodexLineageLedger.Document] let referencedParentDocumentCount: Int - let unresolvedParentIDs: Set + let unresolvedParents: Set } static func discover( @@ -15,20 +15,24 @@ enum CodexLineageDiscovery { { var locator = ParentFileLocator(roots: roots, checkCancellation: checkCancellation) var documents: [CodexLineageLedger.Document] = [] - var knownIDs: Set = [] + var knownIDs: Set = [] var seenPaths: Set = [] - var pendingParentIDs: [String] = [] - var unresolvedParentIDs: Set = [] + var pendingParentIDs: [ScopedIdentity] = [] + var unresolvedParents: Set = [] var referencedParentDocumentCount = 0 func remember(_ document: CodexLineageLedger.Document) { documents.append(document) - knownIDs.insert(Self.canonicalSessionID(document.ownerID)) + knownIDs.insert(.init(scopeID: document.scopeID, sessionID: Self.canonicalSessionID(document.ownerID))) if let metadataSessionID = Self.nonEmpty(document.metadataSessionID) { - knownIDs.insert(Self.canonicalSessionID(metadataSessionID)) + knownIDs.insert(.init( + scopeID: document.scopeID, + sessionID: Self.canonicalSessionID(metadataSessionID))) } if let parentSessionID = Self.nonEmpty(document.parentSessionID) { - pendingParentIDs.append(Self.canonicalSessionID(parentSessionID)) + pendingParentIDs.append(.init( + scopeID: document.scopeID, + sessionID: Self.canonicalSessionID(parentSessionID))) } } @@ -44,35 +48,46 @@ enum CodexLineageDiscovery { var nextParent = 0 while nextParent < pendingParentIDs.count { try checkCancellation?() - let parentID = pendingParentIDs[nextParent] + let parentIdentity = 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) + let unresolvedIdentity = CodexLineageLedger.ParentIdentity( + scopeID: parentIdentity.scopeID, + sessionID: parentIdentity.sessionID) + guard !knownIDs.contains(parentIdentity), !unresolvedParents.contains(unresolvedIdentity) else { continue } - let path = parentURL.standardizedFileURL.path - guard seenPaths.insert(path).inserted else { - unresolvedParentIDs.insert(parentID) + guard let parentURLs = try locator.fileURLs( + for: parentIdentity.sessionID, + scopeID: parentIdentity.scopeID) + else { + unresolvedParents.insert(unresolvedIdentity) 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 + var foundParent = false + for parentURL in parentURLs { + let path = parentURL.standardizedFileURL.path + guard seenPaths.insert(path).inserted else { 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 == parentIdentity.sessionID || metadataSessionID == parentIdentity.sessionID else { + continue + } + referencedParentDocumentCount += 1 + foundParent = true + remember(parent) + } + if !foundParent { + unresolvedParents.insert(unresolvedIdentity) } - referencedParentDocumentCount += 1 - remember(parent) } return Report( documents: documents, referencedParentDocumentCount: referencedParentDocumentCount, - unresolvedParentIDs: unresolvedParentIDs) + unresolvedParents: unresolvedParents) } private static func nonEmpty(_ value: String?) -> String? { @@ -84,21 +99,38 @@ enum CodexLineageDiscovery { UUID(uuidString: value)?.uuidString.lowercased() ?? value } + private struct ScopedIdentity: Equatable, Hashable { + let scopeID: String + let sessionID: String + } + private struct ParentFileLocator { let roots: [URL] let checkCancellation: CostUsageScanner.CancellationCheck? var didIndexRoots = false - var filesByID: [String: URL] = [:] + var filesByID: [ScopedIdentity: Set] = [:] - mutating func fileURL(for sessionID: String) throws -> URL? { + mutating func fileURLs(for sessionID: String, scopeID: String) throws -> [URL]? { let canonicalID = CodexLineageDiscovery.canonicalSessionID(sessionID) - if let known = self.filesByID[canonicalID] { - return known + let key = ScopedIdentity(scopeID: scopeID, sessionID: canonicalID) + if let known = self.filesByID[key] { + return Self.unambiguousMatches(known) } if !self.didIndexRoots { try self.indexRoots() } - return self.filesByID[canonicalID] + guard let matches = self.filesByID[key] else { return nil } + return Self.unambiguousMatches(matches) + } + + private static func unambiguousMatches(_ matches: Set) -> [URL]? { + guard !matches.isEmpty else { return nil } + if matches.count == 1 { + return Array(matches) + } + let ownerIDs = Set(matches.compactMap(CostUsageScanner.codexRolloutOwnerID(fileURL:))) + guard ownerIDs.count == 1 else { return nil } + return matches.sorted { $0.path < $1.path } } private mutating func indexRoots() throws { @@ -122,14 +154,20 @@ enum CodexLineageDiscovery { try self.checkCancellation?() if let ownerID = CostUsageScanner.codexRolloutOwnerID(fileURL: fileURL) { let canonicalID = CodexLineageDiscovery.canonicalSessionID(ownerID) - self.filesByID[canonicalID] = self.filesByID[canonicalID] ?? fileURL + let key = ScopedIdentity( + scopeID: CostUsageScanner.codexLineageScopeID(fileURL: fileURL), + sessionID: canonicalID) + self.filesByID[key, default: []].insert(fileURL) } if let metadataID = try CostUsageScanner.parseCodexSessionIdentifier( fileURL: fileURL, checkCancellation: self.checkCancellation) { let canonicalID = CodexLineageDiscovery.canonicalSessionID(metadataID) - self.filesByID[canonicalID] = self.filesByID[canonicalID] ?? fileURL + let key = ScopedIdentity( + scopeID: CostUsageScanner.codexLineageScopeID(fileURL: fileURL), + sessionID: canonicalID) + self.filesByID[key, default: []].insert(fileURL) } } } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift index bf59ca377a..7152a3aab0 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift @@ -41,6 +41,60 @@ enum CodexLineageLedger { let metadataSessionID: String? let parentSessionID: String? let observations: [Observation] + let scopeID: String + let incompleteObservationCount: Int + + init( + ownerID: String, + metadataSessionID: String?, + parentSessionID: String?, + observations: [Observation], + scopeID: String = "", + incompleteObservationCount: Int = 0) + { + self.ownerID = ownerID + self.metadataSessionID = metadataSessionID + self.parentSessionID = parentSessionID + self.observations = observations + self.scopeID = scopeID + self.incompleteObservationCount = incompleteObservationCount + } + } + + enum ContainmentReason: String, CaseIterable, Equatable, Hashable, Sendable { + case malformedTimestamp + case incompleteObservation + case conflictingOwnerIdentity + case identityCollision + case ancestryCycle + } + + enum FamilyQuality: Equatable, Sendable { + case primary + case incompleteProvenance + case contained(Set) + } + + struct FamilyDisposition: Equatable, Sendable { + let scopeID: String + let ownerIDs: Set + let quality: FamilyQuality + } + + struct ParentIdentity: Equatable, Hashable, Sendable { + let scopeID: String + let sessionID: String + + init(scopeID: String = "", sessionID: String) { + self.scopeID = scopeID + self.sessionID = sessionID + } + } + + struct ConservativeReport: Equatable, Sendable { + let primary: Report + let families: [FamilyDisposition] + let containedDocuments: [Document] } struct Report: Equatable, Sendable { @@ -78,12 +132,13 @@ enum CodexLineageLedger { for document in documents { try checkCancellation?() guard !document.ownerID.isEmpty else { throw LedgerError.emptyOwnerID } - graph.insert(document.ownerID) + let ownerID = Self.scoped(document.ownerID, document: document) + graph.insert(ownerID) if let metadataSessionID = Self.nonEmpty(document.metadataSessionID) { - graph.union(document.ownerID, metadataSessionID) + graph.union(ownerID, Self.scoped(metadataSessionID, document: document)) } if let parentSessionID = Self.nonEmpty(document.parentSessionID) { - graph.union(document.ownerID, parentSessionID) + graph.union(ownerID, Self.scoped(parentSessionID, document: document)) } } @@ -91,7 +146,7 @@ enum CodexLineageLedger { var physicalObservationCount = 0 for document in documents { try checkCancellation?() - let componentID = graph.find(document.ownerID) + let componentID = graph.find(Self.scoped(document.ownerID, document: document)) var accepted = acceptedByComponent[componentID] ?? [:] for observation in document.observations { try checkCancellation?() @@ -138,11 +193,81 @@ enum CodexLineageLedger { localDays: localDays, utcRows: Self.dailyRows(from: utcRows), localRows: Self.dailyRows(from: localRows), - componentCount: Set(documents.map { graph.find($0.ownerID) }).count, + componentCount: Set(documents.map { graph.find(Self.scoped($0.ownerID, document: $0)) }).count, acceptedObservationCount: acceptedObservationCount, duplicateObservationCount: physicalObservationCount - acceptedObservationCount) } + /// Routes every lineage family to either primary ledger accounting or explicit containment. + /// Contained documents are returned to the caller for a future family-scoped fallback; they never + /// contribute to `primary`, which prevents double accounting by construction. + static func reconcileConservatively( + documents: [Document], + unresolvedParents: Set = [], + localTimeZone: TimeZone, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> ConservativeReport + { + var graph = DisjointSet() + for document in documents { + try checkCancellation?() + let owner = Self.scoped(document.ownerID, document: document) + graph.insert(owner) + if let metadata = Self.nonEmpty(document.metadataSessionID) { + graph.union(owner, Self.scoped(metadata, document: document)) + } + if let parent = Self.nonEmpty(document.parentSessionID) { + graph.union(owner, Self.scoped(parent, document: document)) + } + } + + var documentsByFamily: [String: [Document]] = [:] + for document in documents { + try checkCancellation?() + let family = graph.find(Self.scoped(document.ownerID, document: document)) + documentsByFamily[family, default: []].append(document) + } + + var primaryDocuments: [Document] = [] + var containedDocuments: [Document] = [] + var families: [FamilyDisposition] = [] + for familyDocuments in documentsByFamily.values { + try checkCancellation?() + let reasons = Self.containmentReasons(in: familyDocuments) + let owners = Set(familyDocuments.map(\.ownerID)) + let unresolved = familyDocuments.contains { document in + guard let parent = Self.nonEmpty(document.parentSessionID) else { return false } + return unresolvedParents.contains(.init( + scopeID: document.scopeID, + sessionID: Self.canonicalIdentity(parent))) + } + let quality: FamilyQuality + if reasons.isEmpty { + quality = unresolved ? .incompleteProvenance : .primary + primaryDocuments.append(contentsOf: familyDocuments) + } else { + quality = .contained(reasons) + containedDocuments.append(contentsOf: familyDocuments) + } + families.append(FamilyDisposition( + scopeID: familyDocuments.first?.scopeID ?? "", + ownerIDs: owners, + quality: quality)) + } + + families.sort { + ($0.scopeID, $0.ownerIDs.sorted().joined(separator: "\u{0}")) + < ($1.scopeID, $1.ownerIDs.sorted().joined(separator: "\u{0}")) + } + containedDocuments.sort(by: Self.documentComesBefore) + return try ConservativeReport( + primary: Self.reconcile( + documents: primaryDocuments, + localTimeZone: localTimeZone, + checkCancellation: checkCancellation), + families: families, + containedDocuments: containedDocuments) + } + private struct Fingerprint: Equatable, Hashable { let last: Totals let total: Totals @@ -170,6 +295,117 @@ enum CodexLineageLedger { return value } + private static func scoped(_ identity: String, document: Document) -> String { + document.scopeID + "\u{0}" + self.canonicalIdentity(identity) + } + + private static func canonicalIdentity(_ identity: String) -> String { + UUID(uuidString: identity)?.uuidString.lowercased() ?? identity + } + + private static func documentComesBefore(_ lhs: Document, _ rhs: Document) -> Bool { + let lhsKey = [ + lhs.scopeID, + lhs.ownerID, + lhs.metadataSessionID ?? "", + lhs.parentSessionID ?? "", + String(lhs.incompleteObservationCount), + lhs.observations.map(Self.observationSortKey).joined(separator: "\u{1}"), + ].joined(separator: "\u{0}") + let rhsKey = [ + rhs.scopeID, + rhs.ownerID, + rhs.metadataSessionID ?? "", + rhs.parentSessionID ?? "", + String(rhs.incompleteObservationCount), + rhs.observations.map(Self.observationSortKey).joined(separator: "\u{1}"), + ].joined(separator: "\u{0}") + return lhsKey < rhsKey + } + + private static func observationSortKey(_ observation: Observation) -> String { + [ + observation.timestamp, + observation.model, + String(observation.last.input), + String(observation.last.cached), + String(observation.last.output), + String(observation.total.input), + String(observation.total.cached), + String(observation.total.output), + ].joined(separator: "\u{0}") + } + + private static func containmentReasons(in documents: [Document]) -> Set { + var reasons: Set = [] + if documents.contains(where: { $0.incompleteObservationCount > 0 }) { + reasons.insert(.incompleteObservation) + } + if documents.flatMap(\.observations) + .contains(where: { CostUsageScanner.dateFromTimestamp($0.timestamp) == nil }) + { + reasons.insert(.malformedTimestamp) + } + let ownerGroups = Dictionary(grouping: documents, by: \.ownerID) + if ownerGroups.values.contains(where: { group in + let metadataIDs = Set(group.compactMap { Self.nonEmpty($0.metadataSessionID) }) + let parentIDs = Set(group.compactMap { Self.nonEmpty($0.parentSessionID) }) + return metadataIDs.count > 1 || parentIDs.count > 1 + }) { + reasons.insert(.conflictingOwnerIdentity) + } + let metadataGroups = Dictionary(grouping: documents.compactMap { document in + Self.nonEmpty(document.metadataSessionID).map { (Self.canonicalIdentity($0), document) } + }, by: \.0) + if metadataGroups.contains(where: { metadataID, entries in + let documents = entries.map(\.1) + let owners = Set(documents.map { Self.canonicalIdentity($0.ownerID) }) + guard owners.count > 1, !owners.contains(metadataID) else { return false } + return !documents.allSatisfy { + $0.parentSessionID.map(Self.canonicalIdentity) == metadataID + } + }) { + reasons.insert(.identityCollision) + } + if Self.hasAncestryCycle(documents) { + reasons.insert(.ancestryCycle) + } + return reasons + } + + private static func hasAncestryCycle(_ documents: [Document]) -> Bool { + let metadataOwners = Dictionary(grouping: documents.compactMap { document in + document.metadataSessionID.map { ($0, document.ownerID) } + }, by: \.0).mapValues { Set($0.map(\.1)) } + var parents: [String: Set] = [:] + for document in documents { + guard let parent = Self.nonEmpty(document.parentSessionID) else { continue } + var targets = metadataOwners[parent] ?? [parent] + if parent != document.ownerID { + targets.remove(document.ownerID) + } + parents[document.ownerID, default: []].formUnion(targets) + } + var visiting: Set = [] + var visited: Set = [] + func visit(_ owner: String) -> Bool { + if visiting.contains(owner) { + return true + } + if visited.contains(owner) { + return false + } + visiting.insert(owner) + for parent in parents[owner] ?? [] where visit(parent) { + return true + } + visiting.remove(owner) + visited.insert(owner) + return false + } + return Set(documents.map(\.ownerID)).contains(where: visit) + } + /// Duplicate copies can carry different model evidence. Keep the earliest physical copy, /// then resolve equal-time ties deterministically while preferring attributable evidence. private static func shouldPreferModel(_ candidate: String, over existing: String) -> Bool { diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift index a6938113e0..aae024629e 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageShadow.swift @@ -23,6 +23,10 @@ enum CodexLineageShadow { let referencedParentDocumentCount: Int let unresolvedParentCount: Int let rejectedObservationCount: Int + let primaryFamilyCount: Int + let incompleteProvenanceFamilyCount: Int + let containedFamilyCount: Int + let containmentReasonCounts: [CodexLineageLedger.ContainmentReason: Int] } static func run( @@ -42,27 +46,27 @@ enum CodexLineageShadow { documents.reserveCapacity(discovery.documents.count) for document in discovery.documents { try checkCancellation?() - var observations: [CodexLineageLedger.Observation] = [] - observations.reserveCapacity(document.observations.count) for observation in document.observations { try checkCancellation?() let accepted = CostUsageScanner.dateFromTimestamp(observation.timestamp) != nil if !accepted { rejectedObservationCount += 1 - } else { - observations.append(observation) } } documents.append(CodexLineageLedger.Document( ownerID: document.ownerID, metadataSessionID: document.metadataSessionID, parentSessionID: document.parentSessionID, - observations: observations)) + observations: document.observations, + scopeID: document.scopeID, + incompleteObservationCount: document.incompleteObservationCount)) } - let ledger = try CodexLineageLedger.reconcile( + let conservative = try CodexLineageLedger.reconcileConservatively( documents: documents, + unresolvedParents: discovery.unresolvedParents, localTimeZone: localTimeZone, checkCancellation: checkCancellation) + let ledger = conservative.primary let legacy = Self.legacyTotalsByDay(legacyDays) let dayKeys = Set(legacy.keys).union(ledger.localDays.keys) .filter(dayRange.contains) @@ -76,8 +80,32 @@ enum CodexLineageShadow { duplicateObservationCount: ledger.duplicateObservationCount, componentCount: ledger.componentCount, referencedParentDocumentCount: discovery.referencedParentDocumentCount, - unresolvedParentCount: discovery.unresolvedParentIDs.count, - rejectedObservationCount: rejectedObservationCount) + unresolvedParentCount: discovery.unresolvedParents.count, + rejectedObservationCount: rejectedObservationCount, + primaryFamilyCount: conservative.families.count { $0.quality == .primary }, + incompleteProvenanceFamilyCount: conservative.families.count { + $0.quality == .incompleteProvenance + }, + containedFamilyCount: conservative.families.count { + if case .contained = $0.quality { + return true + } + return false + }, + containmentReasonCounts: Self.containmentReasonCounts(conservative.families)) + } + + private static func containmentReasonCounts( + _ families: [CodexLineageLedger.FamilyDisposition]) -> [CodexLineageLedger.ContainmentReason: Int] + { + var counts: [CodexLineageLedger.ContainmentReason: Int] = [:] + for family in families { + guard case let .contained(reasons) = family.quality else { continue } + for reason in reasons { + counts[reason, default: 0] += 1 + } + } + return counts } private static func legacyTotalsByDay( diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index 08c25b83e3..8514a9bcb2 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -103,6 +103,7 @@ enum CostUsageScanner { let forkedFromId: String? let snapshots: [CodexTimestampedTotals] let observations: [CodexLineageLedger.Observation] + let incompleteObservationCount: Int } enum CodexForkBaseline { @@ -1685,7 +1686,7 @@ enum CostUsageScanner { return nil } - // swiftlint:disable:next cyclomatic_complexity + // swiftlint:disable:next cyclomatic_complexity function_body_length private static func parseCodexTokenSnapshots( fileURL: URL, checkCancellation: CancellationCheck? = nil) throws -> CodexParsedTokenEvidence @@ -1696,6 +1697,7 @@ enum CostUsageScanner { var accumulator = CodexSnapshotAccumulator() var snapshots: [CodexTimestampedTotals] = [] var observations: [CodexLineageLedger.Observation] = [] + var incompleteObservationCount = 0 var warnedAboutUnparsedTimestamp = false func parsedSnapshotDate(timestamp: String) -> Date? { @@ -1716,6 +1718,9 @@ enum CostUsageScanner { total: CostUsageCodexTotals?) { guard last != nil || total != nil else { return } + if last == nil || total == nil { + incompleteObservationCount += 1 + } let counted = accumulator.apply(last: last, total: total) snapshots.append(CodexTimestampedTotals( timestamp: timestamp, @@ -1739,7 +1744,13 @@ enum CostUsageScanner { prefixBytes: 512 * 1024, checkCancellation: checkCancellation, onLine: { line in - guard !line.bytes.isEmpty, !line.wasTruncated else { return } + guard !line.bytes.isEmpty else { return } + if line.wasTruncated { + if line.bytes.range(of: Data(#""token_count""#.utf8)) != nil { + incompleteObservationCount += 1 + } + return + } if let fastLine = Self.parseCodexFastLine(line.bytes) { switch fastLine { case let .sessionMeta(metadata): @@ -1843,7 +1854,8 @@ enum CostUsageScanner { sessionId: sessionId, forkedFromId: forkedFromId, snapshots: snapshots, - observations: observations) + observations: observations, + incompleteObservationCount: incompleteObservationCount) } static func parseCodexLineageDocument( @@ -1857,7 +1869,18 @@ enum CostUsageScanner { ownerID: Self.codexRolloutOwnerID(fileURL: fileURL) ?? parsed.sessionId ?? fileURL.standardizedFileURL.path, metadataSessionID: parsed.sessionId, parentSessionID: parsed.forkedFromId, - observations: parsed.observations) + observations: parsed.observations, + scopeID: Self.codexLineageScopeID(fileURL: fileURL), + incompleteObservationCount: parsed.incompleteObservationCount) + } + + static func codexLineageScopeID(fileURL: URL) -> String { + let standardized = fileURL.standardizedFileURL + let components = standardized.pathComponents + if let index = components.lastIndex(where: { $0 == "sessions" || $0 == "archived_sessions" }) { + return NSString.path(withComponents: Array(components[.. CodexLineageLedger.Totals { diff --git a/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift b/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift index 9ab3126144..c3c40dc4e7 100644 --- a/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift +++ b/Tests/CodexBarTests/CodexLineageDiscoveryTests.swift @@ -41,7 +41,7 @@ struct CodexLineageDiscoveryTests { #expect(Set(report.documents.map(\.ownerID)) == [childID, parentID, grandparentID]) #expect(report.documents.map(\.ownerID).contains(unrelatedID) == false) #expect(report.referencedParentDocumentCount == 2) - #expect(report.unresolvedParentIDs.isEmpty) + #expect(report.unresolvedParents.isEmpty) #expect(FileManager.default.fileExists(atPath: parent.path)) #expect(FileManager.default.fileExists(atPath: grandparent.path)) } @@ -63,7 +63,9 @@ struct CodexLineageDiscoveryTests { #expect(report.documents.count == 1) #expect(report.referencedParentDocumentCount == 0) - #expect(report.unresolvedParentIDs == ["66666666-6666-4666-8666-666666666666"]) + #expect(report.unresolvedParents == [.init( + scopeID: environment.codexSessionsRoot.deletingLastPathComponent().path, + sessionID: "66666666-6666-4666-8666-666666666666")]) } @Test @@ -89,7 +91,100 @@ struct CodexLineageDiscoveryTests { #expect(report.documents.map(\.ownerID).contains(parentID)) #expect(report.referencedParentDocumentCount == 1) - #expect(report.unresolvedParentIDs.isEmpty) + #expect(report.unresolvedParents.isEmpty) + } + + @Test + func `parent lookup never crosses normalized Codex homes`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let parentID = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + let otherHomeSessions = environment.root + .appendingPathComponent("other-home", isDirectory: true) + .appendingPathComponent("sessions", isDirectory: true) + _ = try Self.writeRollout( + root: otherHomeSessions, + relativeDirectory: "2026/07/09", + ownerID: parentID, + metadataID: parentID) + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2026/07/09", + ownerID: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", + metadataID: "child", + parentID: parentID) + + let report = try CodexLineageDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, otherHomeSessions]) + + #expect(report.documents.map(\.ownerID) == ["bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb"]) + #expect(report.unresolvedParents == [.init( + scopeID: environment.codexSessionsRoot.deletingLastPathComponent().path, + sessionID: parentID)]) + } + + @Test + func `ambiguous parent identity is unresolved instead of path-order dependent`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let parentAlias = "shared-parent-alias" + _ = try Self.writeRollout( + root: environment.codexArchivedSessionsRoot, + relativeDirectory: "", + ownerID: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", + metadataID: parentAlias) + _ = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2025/01/01", + ownerID: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", + metadataID: parentAlias) + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2026/07/09", + ownerID: "cccccccc-cccc-4ccc-8ccc-cccccccccccc", + metadataID: "child", + parentID: parentAlias) + + let report = try CodexLineageDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, environment.codexArchivedSessionsRoot]) + + #expect(report.documents.count == 1) + #expect(report.unresolvedParents == [.init( + scopeID: environment.codexSessionsRoot.deletingLastPathComponent().path, + sessionID: parentAlias)]) + } + + @Test + func `compatible active and archived copies of one parent are both retained`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let parentID = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" + _ = try Self.writeRollout( + root: environment.codexArchivedSessionsRoot, + relativeDirectory: "", + ownerID: parentID, + metadataID: parentID) + _ = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2025/01/01", + ownerID: parentID, + metadataID: parentID) + let child = try Self.writeRollout( + root: environment.codexSessionsRoot, + relativeDirectory: "2026/07/09", + ownerID: "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", + metadataID: "child", + parentID: parentID) + + let report = try CodexLineageDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, environment.codexArchivedSessionsRoot]) + + #expect(report.documents.count == 3) + #expect(report.referencedParentDocumentCount == 2) + #expect(report.unresolvedParents.isEmpty) } private static func writeRollout( diff --git a/Tests/CodexBarTests/CodexLineageLedgerTests.swift b/Tests/CodexBarTests/CodexLineageLedgerTests.swift index aca6368d34..4d23eb192d 100644 --- a/Tests/CodexBarTests/CodexLineageLedgerTests.swift +++ b/Tests/CodexBarTests/CodexLineageLedgerTests.swift @@ -32,6 +32,8 @@ struct CodexLineageLedgerTests { #expect(document.metadataSessionID == "metadata-id") #expect(document.parentSessionID == "parent-id") #expect(document.observations.count == 2) + #expect(document.incompleteObservationCount == 1) + #expect(document.scopeID == environment.root.path) #expect(document.observations[0].model == "gpt-5.4") #expect(document.observations[0].last == .init(input: 100, cached: 40, output: 10)) #expect(document.observations[1].total == .init(input: 150, cached: 60, output: 15)) @@ -309,6 +311,168 @@ struct CodexLineageLedgerTests { #expect(forward.utcDays["2026-07-10"] == nil) } + @Test + func `incomplete evidence contains the entire family without primary contribution`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let parent = Self.document(owner: "parent", observations: [observation]) + let child = CodexLineageLedger.Document( + ownerID: "child", + metadataSessionID: "child", + parentSessionID: "parent", + observations: [observation], + incompleteObservationCount: 1) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [parent, child], + localTimeZone: .gmt) + + #expect(report.primary.utcDays.isEmpty) + #expect(report.containedDocuments.count == 2) + #expect(report.families == [.init( + scopeID: "", + ownerIDs: ["parent", "child"], + quality: .contained([.incompleteObservation]))]) + } + + @Test + func `missing ancestry lowers provenance without discarding unique descendant usage`() throws { + let child = Self.document( + owner: "child", + parent: "missing-parent", + observations: [Self.observation( + timestamp: "2026-07-09T12:00:00Z", + input: 100, + totalInput: 100)]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [child], + unresolvedParents: [.init(sessionID: "missing-parent")], + localTimeZone: .gmt) + + #expect(report.primary.utcDays["2026-07-09"]?.input == 100) + #expect(report.containedDocuments.isEmpty) + #expect(report.families.first?.quality == .incompleteProvenance) + } + + @Test + func `malformed timestamps and ancestry cycles route families to containment deterministically`() throws { + let malformed = Self.observation(timestamp: "not-a-time", input: 20, totalInput: 20) + let first = Self.document(owner: "first", parent: "second", observations: [malformed]) + let second = Self.document(owner: "second", parent: "first", observations: []) + + let forward = try CodexLineageLedger.reconcileConservatively( + documents: [first, second], + localTimeZone: .gmt) + let reversed = try CodexLineageLedger.reconcileConservatively( + documents: [second, first], + localTimeZone: .gmt) + + #expect(forward == reversed) + #expect(forward.primary.utcDays.isEmpty) + #expect(forward.families.first?.quality == .contained([.malformedTimestamp, .ancestryCycle])) + } + + @Test + func `identical identities in separate Codex homes remain additive`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let first = CodexLineageLedger.Document( + ownerID: "same-owner", + metadataSessionID: "same-metadata", + parentSessionID: nil, + observations: [observation], + scopeID: "/first-home") + let second = CodexLineageLedger.Document( + ownerID: "same-owner", + metadataSessionID: "same-metadata", + parentSessionID: nil, + observations: [observation], + scopeID: "/second-home") + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [first, second], + localTimeZone: .gmt) + + #expect(report.primary.utcDays["2026-07-09"]?.input == 200) + #expect(report.primary.componentCount == 2) + #expect(report.families.count == 2) + } + + @Test + func `conflicting physical copies of one owner are contained`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let first = Self.document(owner: "same-owner", metadata: "first", observations: [observation]) + let second = Self.document(owner: "same-owner", metadata: "second", observations: [observation]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [first, second], + localTimeZone: .gmt) + + #expect(report.primary.utcDays.isEmpty) + #expect(report.families.first?.quality == .contained([.conflictingOwnerIdentity])) + } + + @Test + func `missing optional identity fields remain compatible with a complete copy`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let complete = Self.document( + owner: "same-owner", + metadata: "metadata", + parent: "parent", + observations: [observation]) + let partial = Self.document(owner: "same-owner", observations: [observation]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [partial, complete], + localTimeZone: .gmt) + + #expect(report.primary.utcDays["2026-07-09"]?.input == 100) + #expect(report.containedDocuments.isEmpty) + #expect(report.families.first?.quality == .primary) + } + + @Test + func `retained ancestor metadata does not manufacture an ancestry cycle`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let root = Self.document(owner: "root", metadata: "root", observations: [observation]) + let child = Self.document( + owner: "child", + metadata: "root", + parent: "root", + observations: [observation]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [root, child], + localTimeZone: .gmt) + + #expect(report.primary.utcDays["2026-07-09"]?.input == 100) + #expect(report.families.first?.quality == .primary) + } + + @Test + func `unrelated owners sharing an ungrounded metadata identity are contained`() throws { + let first = Self.document( + owner: "first", + metadata: "shared", + observations: [Self.observation( + timestamp: "2026-07-09T12:00:00Z", + input: 100, + totalInput: 100)]) + let second = Self.document( + owner: "second", + metadata: "shared", + observations: [Self.observation( + timestamp: "2026-07-09T12:01:00Z", + input: 200, + totalInput: 200)]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [first, second], + localTimeZone: .gmt) + + #expect(report.primary.utcDays.isEmpty) + #expect(report.families.first?.quality == .contained([.identityCollision])) + } + private static func document( owner: String, metadata: String? = nil, diff --git a/Tests/CodexBarTests/CodexLineageShadowTests.swift b/Tests/CodexBarTests/CodexLineageShadowTests.swift index 51eb59adfc..b6c5454070 100644 --- a/Tests/CodexBarTests/CodexLineageShadowTests.swift +++ b/Tests/CodexBarTests/CodexLineageShadowTests.swift @@ -36,13 +36,16 @@ struct CodexLineageShadowTests { #expect(report.days == [.init( day: "2026-07-09", legacy: .init(input: 150, cached: 20, output: 10), - ledger: .init(input: 100, cached: 0, output: 0))]) - #expect(report.days[0].delta == .init(input: -50, cached: -20, output: -10)) - #expect(report.acceptedObservationCount == 1) - #expect(report.duplicateObservationCount == 1) - #expect(report.componentCount == 1) + ledger: .zero)]) + #expect(report.days[0].delta == .init(input: -150, cached: -20, output: -10)) + #expect(report.acceptedObservationCount == 0) + #expect(report.duplicateObservationCount == 0) + #expect(report.componentCount == 0) #expect(report.rejectedObservationCount == 1) #expect(report.unresolvedParentCount == 0) + #expect(report.primaryFamilyCount == 0) + #expect(report.containedFamilyCount == 1) + #expect(report.containmentReasonCounts == [.malformedTimestamp: 1]) } private static func writeRollout( From 1097b0a035713ee530f1c34e305341266e9a2385 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 14:42:06 -0400 Subject: [PATCH 08/12] Bound Codex lineage reconciliation --- .../Providers/Codex/CodexLineageEngine.swift | 429 ++++++++++++++++++ .../CodexLineageEngineTests.swift | 208 +++++++++ 2 files changed, 637 insertions(+) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift create mode 100644 Tests/CodexBarTests/CodexLineageEngineTests.swift diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift new file mode 100644 index 0000000000..8e9e3c921c --- /dev/null +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift @@ -0,0 +1,429 @@ +#if canImport(CryptoKit) +import CryptoKit +#else +import Crypto +#endif +import Foundation + +/// Pure, in-memory preparation and reuse seam for lineage families. +/// +/// Callers retain the previous cache until `publish` succeeds. This keeps cancellation and failed +/// reconciliation from exposing a partially rebuilt set of families. +enum CodexLineageEngine { + private static let algorithmVersion = 1 + + struct Fingerprint: Equatable, Hashable, Sendable { + let value: String + } + + struct PreparedFamily: Equatable, Sendable { + let stableID: String + let inputFingerprint: Fingerprint + let documents: [CodexLineageLedger.Document] + let unresolvedParents: Set + let observationCount: Int + } + + struct FamilyResult: Equatable, Sendable { + let stableID: String + let inputFingerprint: Fingerprint + let familyFingerprint: Fingerprint + let quality: CodexLineageLedger.FamilyQuality + let report: CodexLineageLedger.Report + } + + struct Cache: Equatable, Sendable { + let algorithmVersion: Int + let familiesByInputFingerprint: [Fingerprint: FamilyResult] + + static let empty = Self(algorithmVersion: CodexLineageEngine.algorithmVersion, familiesByInputFingerprint: [:]) + } + + struct Diagnostics: Equatable, Sendable { + let familyCount: Int + let recomputedFamilyCount: Int + let reusedFamilyCount: Int + let observationCount: Int + let peakFamilyObservationCount: Int + let peakAcceptedFingerprintCount: Int + } + + struct Result: Equatable, Sendable { + let report: CodexLineageLedger.Report + let families: [FamilyResult] + let candidateCache: Cache + let diagnostics: Diagnostics + } + + static func prepareFamilies( + documents: [CodexLineageLedger.Document], + unresolvedParents: Set = [], + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> [PreparedFamily] + { + var graph = DisjointSet() + for document in documents { + try checkCancellation?() + let owner = Self.scoped(document.ownerID, scopeID: document.scopeID) + graph.insert(owner) + if let metadata = Self.nonEmpty(document.metadataSessionID) { + graph.union(owner, Self.scoped(metadata, scopeID: document.scopeID)) + } + if let parent = Self.nonEmpty(document.parentSessionID) { + graph.union(owner, Self.scoped(parent, scopeID: document.scopeID)) + } + } + + var documentsByRoot: [String: [CodexLineageLedger.Document]] = [:] + for document in documents { + try checkCancellation?() + let root = graph.find(Self.scoped(document.ownerID, scopeID: document.scopeID)) + documentsByRoot[root, default: []].append(document) + } + + var families: [PreparedFamily] = [] + families.reserveCapacity(documentsByRoot.count) + for familyDocuments in documentsByRoot.values { + try checkCancellation?() + var keyedDocuments: [(document: CodexLineageLedger.Document, key: Fingerprint)] = [] + keyedDocuments.reserveCapacity(familyDocuments.count) + for document in familyDocuments { + try checkCancellation?() + try keyedDocuments.append(( + document: document, + key: Self.documentFingerprint(document, checkCancellation: checkCancellation))) + } + keyedDocuments.sort { $0.key.value < $1.key.value } + let sortedDocuments = keyedDocuments.map(\.document) + let identities = Set(sortedDocuments.flatMap { document in + [document.ownerID, document.metadataSessionID, document.parentSessionID].compactMap { value in + Self.nonEmpty(value).map { Self.scoped($0, scopeID: document.scopeID) } + } + }) + let familyUnresolved = unresolvedParents.filter { parent in + identities.contains(Self.scoped(parent.sessionID, scopeID: parent.scopeID)) + } + let stableID = identities.min() ?? "" + let fingerprint = try Self.inputFingerprint( + documents: sortedDocuments, + unresolvedParents: familyUnresolved, + checkCancellation: checkCancellation) + families.append(PreparedFamily( + stableID: stableID, + inputFingerprint: fingerprint, + documents: sortedDocuments, + unresolvedParents: familyUnresolved, + observationCount: sortedDocuments.reduce(0) { $0 + $1.observations.count })) + } + return families.sorted { $0.stableID < $1.stableID } + } + + static func reconcile( + families: [PreparedFamily], + previousCache: Cache? = nil, + localTimeZone: TimeZone, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> Result + { + let reusable = previousCache?.algorithmVersion == Self.algorithmVersion + ? previousCache?.familiesByInputFingerprint ?? [:] + : [:] + var results: [FamilyResult] = [] + results.reserveCapacity(families.count) + var recomputed = 0 + var reused = 0 + var peakAccepted = 0 + + for family in families.sorted(by: { $0.stableID < $1.stableID }) { + try checkCancellation?() + let cacheFingerprint = Self.cacheFingerprint( + input: family.inputFingerprint, + localTimeZone: localTimeZone) + if let cached = reusable[cacheFingerprint], + cached.stableID == family.stableID, + cached.inputFingerprint == family.inputFingerprint + { + results.append(cached) + reused += 1 + peakAccepted = max(peakAccepted, cached.report.acceptedObservationCount) + continue + } + let conservative = try CodexLineageLedger.reconcileConservatively( + documents: family.documents, + unresolvedParents: family.unresolvedParents, + localTimeZone: localTimeZone, + checkCancellation: checkCancellation) + let quality = conservative.families.first?.quality ?? .primary + let familyFingerprint = Self.familyFingerprint(input: cacheFingerprint, quality: quality) + let result = FamilyResult( + stableID: family.stableID, + inputFingerprint: family.inputFingerprint, + familyFingerprint: familyFingerprint, + quality: quality, + report: conservative.primary) + results.append(result) + recomputed += 1 + peakAccepted = max(peakAccepted, result.report.acceptedObservationCount) + } + + results.sort { $0.stableID < $1.stableID } + let report = try Self.compose(results.map(\.report), checkCancellation: checkCancellation) + let candidate = Cache( + algorithmVersion: Self.algorithmVersion, + familiesByInputFingerprint: Dictionary(uniqueKeysWithValues: results.map { + (Self.cacheFingerprint(input: $0.inputFingerprint, localTimeZone: localTimeZone), $0) + })) + try checkCancellation?() + return Result( + report: report, + families: results, + candidateCache: candidate, + diagnostics: Diagnostics( + familyCount: families.count, + recomputedFamilyCount: recomputed, + reusedFamilyCount: reused, + observationCount: families.reduce(0) { $0 + $1.observationCount }, + peakFamilyObservationCount: families.map(\.observationCount).max() ?? 0, + peakAcceptedFingerprintCount: peakAccepted)) + } + + static func publish( + _ candidate: Cache, + to cache: inout Cache, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws + { + try checkCancellation?() + cache = candidate + } + + private static func compose( + _ reports: [CodexLineageLedger.Report], + checkCancellation: CostUsageScanner.CancellationCheck?) throws -> CodexLineageLedger.Report + { + var utcDays: [String: CodexLineageLedger.Totals] = [:] + var localDays: [String: CodexLineageLedger.Totals] = [:] + var utcRows: [RowKey: RowValue] = [:] + var localRows: [RowKey: RowValue] = [:] + for report in reports { + try checkCancellation?() + try Self.mergeDays(report.utcDays, into: &utcDays, checkCancellation: checkCancellation) + try Self.mergeDays(report.localDays, into: &localDays, checkCancellation: checkCancellation) + try Self.mergeRows(report.utcRows, into: &utcRows, checkCancellation: checkCancellation) + try Self.mergeRows(report.localRows, into: &localRows, checkCancellation: checkCancellation) + } + return CodexLineageLedger.Report( + utcDays: utcDays, + localDays: localDays, + utcRows: Self.rows(utcRows), + localRows: Self.rows(localRows), + componentCount: reports.reduce(0) { $0 + $1.componentCount }, + acceptedObservationCount: reports.reduce(0) { $0 + $1.acceptedObservationCount }, + duplicateObservationCount: reports.reduce(0) { $0 + $1.duplicateObservationCount }) + } + + private struct RowKey: Hashable { + let day: String + let model: String + } + + private struct RowValue { + var totals = CodexLineageLedger.Totals.zero + var costUSD = 0.0 + var isPriced = true + } + + private static func mergeDays( + _ source: [String: CodexLineageLedger.Totals], + into destination: inout [String: CodexLineageLedger.Totals], + checkCancellation: CostUsageScanner.CancellationCheck?) throws + { + for (day, totals) in source { + try checkCancellation?() + var combined = destination[day] ?? .zero + combined.add(totals) + destination[day] = combined + } + } + + private static func mergeRows( + _ source: [CodexLineageLedger.DailyRow], + into destination: inout [RowKey: RowValue], + checkCancellation: CostUsageScanner.CancellationCheck?) throws + { + for row in source { + try checkCancellation?() + let key = RowKey(day: row.day, model: row.model) + var value = destination[key] ?? RowValue() + value.totals.add(row.totals) + if let cost = row.costUSD { + value.costUSD += cost + } else { + value.isPriced = false + } + destination[key] = value + } + } + + private static func rows(_ values: [RowKey: RowValue]) -> [CodexLineageLedger.DailyRow] { + values.map { key, value in + .init(day: key.day, model: key.model, totals: value.totals, costUSD: value.isPriced ? value.costUSD : nil) + }.sorted { ($0.day, $0.model) < ($1.day, $1.model) } + } + + private static func inputFingerprint( + documents: [CodexLineageLedger.Document], + unresolvedParents: Set, + checkCancellation: CostUsageScanner.CancellationCheck?) throws -> Fingerprint + { + var digest = DigestBuilder() + digest.append("codex-lineage-family") + digest.append(String(Self.algorithmVersion)) + for document in documents { + try checkCancellation?() + digest.append(contentsOf: [ + "document", document.scopeID, Self.canonical(document.ownerID), + document.metadataSessionID.map(Self.canonical) ?? "", + document.parentSessionID.map(Self.canonical) ?? "", + String(document.incompleteObservationCount), + ]) + let observations = document.observations.sorted(by: Self.observationComesBefore) + for observation in observations { + try checkCancellation?() + digest.append(contentsOf: [ + "observation", observation.timestamp, observation.model, + String(observation.last.input), String(observation.last.cached), String(observation.last.output), + String(observation.total.input), String(observation.total.cached), String(observation.total.output), + ]) + } + } + for parent in unresolvedParents.sorted(by: { ($0.scopeID, $0.sessionID) < ($1.scopeID, $1.sessionID) }) { + digest.append(contentsOf: ["unresolved", parent.scopeID, Self.canonical(parent.sessionID)]) + } + return digest.finalize() + } + + private static func familyFingerprint( + input: Fingerprint, + quality: CodexLineageLedger.FamilyQuality) -> Fingerprint + { + let qualityFields = switch quality { + case .primary: + ["primary"] + case .incompleteProvenance: + ["incompleteProvenance"] + case let .contained(reasons): + ["contained"] + reasons.map(\.rawValue).sorted() + } + return Self.digest(["codex-lineage-family-result", input.value] + qualityFields) + } + + private static func cacheFingerprint(input: Fingerprint, localTimeZone: TimeZone) -> Fingerprint { + self.digest([ + "codex-lineage-family-projection", + input.value, + localTimeZone.identifier, + ]) + } + + private static func digest(_ fields: [String]) -> Fingerprint { + var digest = DigestBuilder() + for field in fields { + digest.append(field) + } + return digest.finalize() + } + + private static func documentFingerprint( + _ document: CodexLineageLedger.Document, + checkCancellation: CostUsageScanner.CancellationCheck?) throws -> Fingerprint + { + let observations = document.observations.sorted(by: Self.observationComesBefore) + var digest = DigestBuilder() + digest.append(contentsOf: [ + document.scopeID, Self.canonical(document.ownerID), + document.metadataSessionID.map(Self.canonical) ?? "", + document.parentSessionID.map(Self.canonical) ?? "", + String(document.incompleteObservationCount), + ]) + for observation in observations { + try checkCancellation?() + digest.append(contentsOf: [ + observation.timestamp, observation.model, + String(observation.last.input), String(observation.last.cached), String(observation.last.output), + String(observation.total.input), String(observation.total.cached), String(observation.total.output), + ]) + } + return digest.finalize() + } + + private static func observationComesBefore( + _ lhs: CodexLineageLedger.Observation, + _ rhs: CodexLineageLedger.Observation) -> Bool + { + self.observationKey(lhs) < self.observationKey(rhs) + } + + private static func observationKey(_ observation: CodexLineageLedger.Observation) -> String { + [ + observation.timestamp, observation.model, + String(observation.last.input), String(observation.last.cached), String(observation.last.output), + String(observation.total.input), String(observation.total.cached), String(observation.total.output), + ].joined(separator: "\u{0}") + } + + private static func nonEmpty(_ value: String?) -> String? { + guard let value, !value.isEmpty else { return nil } + return value + } + + private static func canonical(_ value: String) -> String { + UUID(uuidString: value)?.uuidString.lowercased() ?? value + } + + private static func scoped(_ value: String, scopeID: String) -> String { + scopeID + "\u{0}" + self.canonical(value) + } + + private struct DisjointSet { + var parents: [String: String] = [:] + + mutating func insert(_ value: String) { + self.parents[value] = self.parents[value] ?? value + } + + mutating func find(_ value: String) -> String { + self.insert(value) + guard let parent = self.parents[value], parent != value else { return value } + let root = self.find(parent) + self.parents[value] = root + return root + } + + mutating func union(_ lhs: String, _ rhs: String) { + let lhsRoot = self.find(lhs) + let rhsRoot = self.find(rhs) + guard lhsRoot != rhsRoot else { return } + let first = min(lhsRoot, rhsRoot) + let second = max(lhsRoot, rhsRoot) + self.parents[second] = first + } + } + + private struct DigestBuilder { + private var hasher = SHA256() + + mutating func append(_ field: String) { + var length = UInt64(field.utf8.count).bigEndian + withUnsafeBytes(of: &length) { self.hasher.update(bufferPointer: $0) } + self.hasher.update(data: Data(field.utf8)) + } + + mutating func append(contentsOf fields: [String]) { + for field in fields { + self.append(field) + } + } + + consuming func finalize() -> Fingerprint { + Fingerprint(value: self.hasher.finalize().map { String(format: "%02x", $0) }.joined()) + } + } +} diff --git a/Tests/CodexBarTests/CodexLineageEngineTests.swift b/Tests/CodexBarTests/CodexLineageEngineTests.swift new file mode 100644 index 0000000000..2ad505de2e --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageEngineTests.swift @@ -0,0 +1,208 @@ +import Foundation +import Testing +@testable import CodexBarCore + +struct CodexLineageEngineTests { + @Test + func `family fingerprints and totals are deterministic under input permutation`() throws { + let first = Self.document(owner: "first", observations: [ + Self.observation(timestamp: "2026-07-09T12:01:00Z", input: 20, total: 30), + Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 10, total: 10), + ]) + let child = Self.document(owner: "child", parent: "first", observations: [ + Self.observation(timestamp: "2026-07-09T12:02:00Z", input: 5, total: 35), + ]) + let other = Self.document(owner: "other", observations: [ + Self.observation(timestamp: "2026-07-09T13:00:00Z", input: 7, total: 7), + ]) + + let forwardFamilies = try CodexLineageEngine.prepareFamilies(documents: [first, child, other]) + let reverseFamilies = try CodexLineageEngine.prepareFamilies(documents: [other, child, first]) + let forward = try CodexLineageEngine.reconcile(families: forwardFamilies, localTimeZone: .gmt) + let reverse = try CodexLineageEngine.reconcile(families: reverseFamilies, localTimeZone: .gmt) + + #expect(forward.families.map(\.familyFingerprint) == reverse.families.map(\.familyFingerprint)) + #expect(forward.report == reverse.report) + #expect(forward.report.utcDays["2026-07-09"]?.input == 42) + } + + @Test + func `warm reconciliation reuses unchanged families and recomputes only a changed family`() throws { + let first = Self.document(owner: "first", observations: [Self.observation(input: 10, total: 10)]) + let second = Self.document(owner: "second", observations: [Self.observation(input: 20, total: 20)]) + let initialFamilies = try CodexLineageEngine.prepareFamilies(documents: [first, second]) + let initial = try CodexLineageEngine.reconcile(families: initialFamilies, localTimeZone: .gmt) + let warm = try CodexLineageEngine.reconcile( + families: initialFamilies, + previousCache: initial.candidateCache, + localTimeZone: .gmt) + + let changed = Self.document(owner: "second", observations: [Self.observation(input: 25, total: 25)]) + let changedFamilies = try CodexLineageEngine.prepareFamilies(documents: [first, changed]) + let updated = try CodexLineageEngine.reconcile( + families: changedFamilies, + previousCache: initial.candidateCache, + localTimeZone: .gmt) + + #expect(warm.diagnostics.reusedFamilyCount == 2) + #expect(warm.diagnostics.recomputedFamilyCount == 0) + #expect(updated.diagnostics.reusedFamilyCount == 1) + #expect(updated.diagnostics.recomputedFamilyCount == 1) + #expect(updated.report.utcDays["2026-07-09"]?.input == 35) + } + + @Test + func `cache entries with mismatched family identity are recomputed`() throws { + let first = Self.document(owner: "first", observations: [Self.observation(input: 10, total: 10)]) + let second = Self.document(owner: "second", observations: [Self.observation(input: 20, total: 20)]) + let families = try CodexLineageEngine.prepareFamilies(documents: [first, second]) + let initial = try CodexLineageEngine.reconcile(families: families, localTimeZone: .gmt) + let entries = initial.candidateCache.familiesByInputFingerprint.sorted { $0.key.value < $1.key.value } + let mismatched = CodexLineageEngine.Cache( + algorithmVersion: initial.candidateCache.algorithmVersion, + familiesByInputFingerprint: [entries[0].key: entries[1].value, entries[1].key: entries[0].value]) + + let rebuilt = try CodexLineageEngine.reconcile( + families: families, + previousCache: mismatched, + localTimeZone: .gmt) + + #expect(rebuilt.diagnostics.reusedFamilyCount == 0) + #expect(rebuilt.diagnostics.recomputedFamilyCount == 2) + #expect(rebuilt.report.utcDays["2026-07-09"]?.input == 30) + } + + @Test + func `changing projection timezone recomputes families and does not reuse stale local days`() throws { + let document = Self.document(owner: "first", observations: [ + Self.observation(timestamp: "2026-07-10T02:00:00Z", input: 10, total: 10), + ]) + let families = try CodexLineageEngine.prepareFamilies(documents: [document]) + let utc = try CodexLineageEngine.reconcile(families: families, localTimeZone: .gmt) + let newYork = try CodexLineageEngine.reconcile( + families: families, + previousCache: utc.candidateCache, + localTimeZone: #require(TimeZone(identifier: "America/New_York"))) + + #expect(newYork.diagnostics.reusedFamilyCount == 0) + #expect(newYork.diagnostics.recomputedFamilyCount == 1) + #expect(utc.report.localDays["2026-07-10"]?.input == 10) + #expect(newYork.report.localDays["2026-07-09"]?.input == 10) + } + + @Test + func `new parent merges only affected families while unrelated family remains reusable`() throws { + let child = Self.document( + owner: "child", + parent: "parent", + observations: [Self.observation(input: 10, total: 10)]) + let parent = Self.document(owner: "parent", observations: [Self.observation(input: 20, total: 20)]) + let unrelated = Self.document(owner: "other", observations: [Self.observation(input: 5, total: 5)]) + let unresolved: Set = [.init(sessionID: "parent")] + let initialFamilies = try CodexLineageEngine.prepareFamilies( + documents: [child, unrelated], + unresolvedParents: unresolved) + let initial = try CodexLineageEngine.reconcile(families: initialFamilies, localTimeZone: .gmt) + + let resolvedFamilies = try CodexLineageEngine.prepareFamilies(documents: [child, parent, unrelated]) + let resolved = try CodexLineageEngine.reconcile( + families: resolvedFamilies, + previousCache: initial.candidateCache, + localTimeZone: .gmt) + + #expect(resolved.diagnostics.familyCount == 2) + #expect(resolved.diagnostics.reusedFamilyCount == 1) + #expect(resolved.diagnostics.recomputedFamilyCount == 1) + #expect(resolved.report.utcDays["2026-07-09"]?.input == 35) + } + + @Test + func `cancelled publication leaves the prior cache unchanged`() throws { + let family = try CodexLineageEngine.prepareFamilies(documents: [ + Self.document(owner: "first", observations: [Self.observation(input: 10, total: 10)]), + ]) + let result = try CodexLineageEngine.reconcile(families: family, localTimeZone: .gmt) + var published = CodexLineageEngine.Cache.empty + + #expect(throws: CancellationError.self) { + try CodexLineageEngine.publish( + result.candidateCache, + to: &published, + checkCancellation: { throw CancellationError() }) + } + #expect(published == .empty) + + try CodexLineageEngine.publish(result.candidateCache, to: &published) + #expect(published == result.candidateCache) + } + + @Test + func `structural diagnostics bound reconciliation scratch state to the largest family`() throws { + let repeated = (0..<2000).map { index in + Self.observation( + timestamp: String(format: "2026-07-09T12:%02d:%02dZ", (index / 60) % 60, index % 60), + input: 1, + total: index + 1) + } + let documents = [ + Self.document(owner: "large", observations: repeated), + Self.document(owner: "small", observations: Array(repeated.prefix(100))), + ] + let families = try CodexLineageEngine.prepareFamilies(documents: documents) + let result = try CodexLineageEngine.reconcile(families: families, localTimeZone: .gmt) + + #expect(result.diagnostics.observationCount == 2100) + #expect(result.diagnostics.peakFamilyObservationCount == 2000) + #expect(result.diagnostics.peakAcceptedFingerprintCount <= 2000) + } + + @Test + func `cancellation propagates during preparation and reconciliation without a candidate`() throws { + let documents = (0..<20).map { index in + Self.document(owner: "owner-\(index)", observations: [Self.observation(input: index + 1, total: index + 1)]) + } + var preparationChecks = 0 + #expect(throws: CancellationError.self) { + _ = try CodexLineageEngine.prepareFamilies(documents: documents) { + preparationChecks += 1 + if preparationChecks == 5 { + throw CancellationError() + } + } + } + + let families = try CodexLineageEngine.prepareFamilies(documents: documents) + var reconciliationChecks = 0 + #expect(throws: CancellationError.self) { + _ = try CodexLineageEngine.reconcile(families: families, localTimeZone: .gmt) { + reconciliationChecks += 1 + if reconciliationChecks == 5 { + throw CancellationError() + } + } + } + } + + private static func document( + owner: String, + parent: String? = nil, + observations: [CodexLineageLedger.Observation]) -> CodexLineageLedger.Document + { + .init( + ownerID: owner, + metadataSessionID: owner, + parentSessionID: parent, + observations: observations) + } + + private static func observation( + timestamp: String = "2026-07-09T12:00:00Z", + input: Int, + total: Int) -> CodexLineageLedger.Observation + { + .init( + timestamp: timestamp, + last: .init(input: input, cached: 0, output: 0), + total: .init(input: total, cached: 0, output: 0)) + } +} From 5c82112d95af25e839448f1f05771f1cafad910b Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 15:06:25 -0400 Subject: [PATCH 09/12] Stream Codex lineage families --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Providers/Codex/CodexLineageEngine.swift | 168 +++++++++++++ .../Codex/CodexLineageTwoPassDiscovery.swift | 227 ++++++++++++++++++ .../Vendored/CostUsage/CostUsageScanner.swift | 67 +++++- .../CodexLineageTwoPassDiscoveryTests.swift | 152 ++++++++++++ 5 files changed, 602 insertions(+), 14 deletions(-) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageTwoPassDiscovery.swift create mode 100644 Tests/CodexBarTests/CodexLineageTwoPassDiscoveryTests.swift diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index 90a5d3ff38..c0e0dd2e96 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "4c426503aec9cb49" + static let value = "84c52421265e9fc8" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift index 8e9e3c921c..22bd558301 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageEngine.swift @@ -24,6 +24,14 @@ enum CodexLineageEngine { let observationCount: Int } + struct PreparedDescriptorFamily: Equatable, Sendable { + let stableID: String + let inputFingerprint: Fingerprint + let descriptors: [CodexLineageTwoPassDiscovery.Descriptor] + let unresolvedParents: Set + let observationCount: Int + } + struct FamilyResult: Equatable, Sendable { let stableID: String let inputFingerprint: Fingerprint @@ -117,6 +125,134 @@ enum CodexLineageEngine { return families.sorted { $0.stableID < $1.stableID } } + static func prepareDescriptorFamilies( + descriptors: [CodexLineageTwoPassDiscovery.Descriptor], + unresolvedParents: Set = [], + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> [PreparedDescriptorFamily] + { + var graph = DisjointSet() + for descriptor in descriptors { + try checkCancellation?() + let owner = Self.scoped(descriptor.ownerID, scopeID: descriptor.scopeID) + graph.insert(owner) + if let metadata = Self.nonEmpty(descriptor.metadataSessionID) { + graph.union(owner, Self.scoped(metadata, scopeID: descriptor.scopeID)) + } + if let parent = Self.nonEmpty(descriptor.parentSessionID) { + graph.union(owner, Self.scoped(parent, scopeID: descriptor.scopeID)) + } + } + var descriptorsByRoot: [String: [CodexLineageTwoPassDiscovery.Descriptor]] = [:] + for descriptor in descriptors { + try checkCancellation?() + let root = graph.find(Self.scoped(descriptor.ownerID, scopeID: descriptor.scopeID)) + descriptorsByRoot[root, default: []].append(descriptor) + } + var families: [PreparedDescriptorFamily] = [] + for var familyDescriptors in descriptorsByRoot.values { + try checkCancellation?() + familyDescriptors.sort { Self.descriptorKey($0) < Self.descriptorKey($1) } + let identities = Set(familyDescriptors.flatMap { descriptor in + [descriptor.ownerID, descriptor.metadataSessionID, descriptor.parentSessionID].compactMap { value in + Self.nonEmpty(value).map { Self.scoped($0, scopeID: descriptor.scopeID) } + } + }) + let familyUnresolved = unresolvedParents.filter { + identities.contains(Self.scoped($0.sessionID, scopeID: $0.scopeID)) + } + let fingerprint = Self.descriptorFamilyFingerprint( + descriptors: familyDescriptors, + unresolvedParents: familyUnresolved) + families.append(.init( + stableID: identities.min() ?? "", + inputFingerprint: fingerprint, + descriptors: familyDescriptors, + unresolvedParents: familyUnresolved, + observationCount: familyDescriptors.reduce(0) { $0 + $1.observationCount })) + } + return families.sorted { $0.stableID < $1.stableID } + } + + static func reconcileStreaming( + families: [PreparedDescriptorFamily], + previousCache: Cache? = nil, + localTimeZone: TimeZone, + checkCancellation: CostUsageScanner.CancellationCheck? = nil, + loadDocument: ((CodexLineageTwoPassDiscovery.Descriptor) throws -> CodexLineageLedger.Document)? = nil) throws + -> Result + { + let reusable = previousCache?.algorithmVersion == Self.algorithmVersion + ? previousCache?.familiesByInputFingerprint ?? [:] + : [:] + var results: [FamilyResult] = [] + var recomputed = 0 + var reused = 0 + var peakLoadedObservations = 0 + var peakAccepted = 0 + for family in families.sorted(by: { $0.stableID < $1.stableID }) { + try checkCancellation?() + let cacheFingerprint = Self.cacheFingerprint( + input: family.inputFingerprint, + localTimeZone: localTimeZone) + if let cached = reusable[cacheFingerprint], cached.stableID == family.stableID { + results.append(cached) + reused += 1 + peakAccepted = max(peakAccepted, cached.report.acceptedObservationCount) + continue + } + var documents: [CodexLineageLedger.Document] = [] + documents.reserveCapacity(family.descriptors.count) + var loadedObservations = 0 + for descriptor in family.descriptors { + try checkCancellation?() + let document: CodexLineageLedger.Document = if let loadDocument { + try loadDocument(descriptor) + } else { + try CodexLineageTwoPassDiscovery.loadDocument( + descriptor, + checkCancellation: checkCancellation) + } + loadedObservations += document.observations.count + documents.append(document) + } + peakLoadedObservations = max(peakLoadedObservations, loadedObservations) + let conservative = try CodexLineageLedger.reconcileConservatively( + documents: documents, + unresolvedParents: family.unresolvedParents, + localTimeZone: localTimeZone, + checkCancellation: checkCancellation) + let quality = conservative.families.first?.quality ?? .primary + let result = FamilyResult( + stableID: family.stableID, + inputFingerprint: family.inputFingerprint, + familyFingerprint: Self.familyFingerprint(input: cacheFingerprint, quality: quality), + quality: quality, + report: conservative.primary) + results.append(result) + recomputed += 1 + peakAccepted = max(peakAccepted, result.report.acceptedObservationCount) + } + results.sort { $0.stableID < $1.stableID } + let report = try Self.compose(results.map(\.report), checkCancellation: checkCancellation) + let candidate = Cache( + algorithmVersion: Self.algorithmVersion, + familiesByInputFingerprint: Dictionary(uniqueKeysWithValues: results.map { + (Self.cacheFingerprint(input: $0.inputFingerprint, localTimeZone: localTimeZone), $0) + })) + try checkCancellation?() + return Result( + report: report, + families: results, + candidateCache: candidate, + diagnostics: .init( + familyCount: families.count, + recomputedFamilyCount: recomputed, + reusedFamilyCount: reused, + observationCount: families.reduce(0) { $0 + $1.observationCount }, + peakFamilyObservationCount: peakLoadedObservations, + peakAcceptedFingerprintCount: peakAccepted)) + } + static func reconcile( families: [PreparedFamily], previousCache: Cache? = nil, @@ -300,6 +436,38 @@ enum CodexLineageEngine { return digest.finalize() } + private static func descriptorFamilyFingerprint( + descriptors: [CodexLineageTwoPassDiscovery.Descriptor], + unresolvedParents: Set) -> Fingerprint + { + var digest = DigestBuilder() + digest.append(contentsOf: ["codex-lineage-descriptor-family", String(Self.algorithmVersion)]) + for descriptor in descriptors { + digest.append(contentsOf: [ + "descriptor", descriptor.scopeID, Self.canonical(descriptor.ownerID), + descriptor.metadataSessionID.map(Self.canonical) ?? "", + descriptor.parentSessionID.map(Self.canonical) ?? "", + String(descriptor.incompleteObservationCount), String(descriptor.observationCount), + String(descriptor.signature.size), String(descriptor.signature.modifiedMilliseconds), + descriptor.signature.contentSHA256, + ]) + } + for parent in unresolvedParents.sorted(by: { ($0.scopeID, $0.sessionID) < ($1.scopeID, $1.sessionID) }) { + digest.append(contentsOf: ["unresolved", parent.scopeID, Self.canonical(parent.sessionID)]) + } + return digest.finalize() + } + + private static func descriptorKey(_ descriptor: CodexLineageTwoPassDiscovery.Descriptor) -> String { + [ + descriptor.scopeID, self.canonical(descriptor.ownerID), + descriptor.metadataSessionID.map(self.canonical) ?? "", + descriptor.parentSessionID.map(self.canonical) ?? "", + descriptor.signature.contentSHA256, + descriptor.fileURL.standardizedFileURL.path, + ].joined(separator: "\u{0}") + } + private static func familyFingerprint( input: Fingerprint, quality: CodexLineageLedger.FamilyQuality) -> Fingerprint diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageTwoPassDiscovery.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageTwoPassDiscovery.swift new file mode 100644 index 0000000000..16edd16396 --- /dev/null +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageTwoPassDiscovery.swift @@ -0,0 +1,227 @@ +#if canImport(CryptoKit) +import CryptoKit +#else +import Crypto +#endif +import Foundation + +/// Pass-one lineage index. It retains file identity and quality evidence, never token observations. +enum CodexLineageTwoPassDiscovery { + enum DiscoveryError: Error, Equatable { + case fileChangedDuringScan + } + + struct FileSignature: Equatable, Hashable, Sendable { + let size: Int64 + let modifiedMilliseconds: Int64 + let contentSHA256: String + } + + struct Descriptor: Equatable, Sendable { + let fileURL: URL + let ownerID: String + let metadataSessionID: String? + let parentSessionID: String? + let scopeID: String + let incompleteObservationCount: Int + let observationCount: Int + let signature: FileSignature + } + + struct Report: Equatable, Sendable { + let descriptors: [Descriptor] + let referencedParentDocumentCount: Int + let unresolvedParents: Set + let peakRetainedObservationCount: Int + } + + static func discover( + includedFiles: [URL], + roots: [URL], + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> Report + { + var locator = ParentLocator(roots: roots, checkCancellation: checkCancellation) + var descriptors: [Descriptor] = [] + var known: Set = [] + var pending: [ScopedIdentity] = [] + var unresolved: Set = [] + var seenPaths: Set = [] + var referencedParents = 0 + + func remember(_ descriptor: Descriptor) { + descriptors.append(descriptor) + known.insert(.init(scopeID: descriptor.scopeID, sessionID: Self.canonical(descriptor.ownerID))) + if let metadata = Self.nonEmpty(descriptor.metadataSessionID) { + known.insert(.init(scopeID: descriptor.scopeID, sessionID: Self.canonical(metadata))) + } + if let parent = Self.nonEmpty(descriptor.parentSessionID) { + pending.append(.init(scopeID: descriptor.scopeID, sessionID: Self.canonical(parent))) + } + } + + for fileURL in includedFiles.sorted(by: { $0.path < $1.path }) { + try checkCancellation?() + guard seenPaths.insert(fileURL.standardizedFileURL.path).inserted else { continue } + try remember(Self.describe(fileURL: fileURL, checkCancellation: checkCancellation)) + } + + var nextParent = 0 + while nextParent < pending.count { + try checkCancellation?() + let identity = pending[nextParent] + nextParent += 1 + let unresolvedIdentity = CodexLineageLedger.ParentIdentity( + scopeID: identity.scopeID, + sessionID: identity.sessionID) + guard !known.contains(identity), !unresolved.contains(unresolvedIdentity) else { continue } + guard let matches = try locator.fileURLs(for: identity) else { + unresolved.insert(unresolvedIdentity) + continue + } + var found = false + for fileURL in matches { + try checkCancellation?() + guard seenPaths.insert(fileURL.standardizedFileURL.path).inserted else { continue } + let descriptor = try Self.describe(fileURL: fileURL, checkCancellation: checkCancellation) + let owner = Self.canonical(descriptor.ownerID) + let metadata = descriptor.metadataSessionID.map(Self.canonical) + guard owner == identity.sessionID || metadata == identity.sessionID else { continue } + remember(descriptor) + referencedParents += 1 + found = true + } + if !found { + unresolved.insert(unresolvedIdentity) + } + } + + return Report( + descriptors: descriptors.sorted { $0.fileURL.path < $1.fileURL.path }, + referencedParentDocumentCount: referencedParents, + unresolvedParents: unresolved, + peakRetainedObservationCount: 0) + } + + static func describe( + fileURL: URL, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> Descriptor + { + // Validate both sides of the parse. A post-parse signature alone can bless a + // mixed read when a rollout is replaced while the parser has the file open. + let initialSignature = try Self.signature(fileURL: fileURL, checkCancellation: checkCancellation) + let summary = try CostUsageScanner.parseCodexLineageDocumentSummary( + fileURL: fileURL, + checkCancellation: checkCancellation) + let finalSignature = try Self.signature(fileURL: fileURL, checkCancellation: checkCancellation) + guard initialSignature == finalSignature else { throw DiscoveryError.fileChangedDuringScan } + return Descriptor( + fileURL: fileURL, + ownerID: summary.ownerID, + metadataSessionID: summary.metadataSessionID, + parentSessionID: summary.parentSessionID, + scopeID: summary.scopeID, + incompleteObservationCount: summary.incompleteObservationCount, + observationCount: summary.observationCount, + signature: finalSignature) + } + + static func loadDocument( + _ descriptor: Descriptor, + checkCancellation: CostUsageScanner.CancellationCheck? = nil) throws -> CodexLineageLedger.Document + { + guard try self.signature(fileURL: descriptor.fileURL, checkCancellation: checkCancellation) == descriptor + .signature + else { throw DiscoveryError.fileChangedDuringScan } + let document = try CostUsageScanner.parseCodexLineageDocument( + fileURL: descriptor.fileURL, + checkCancellation: checkCancellation) + guard try Self.signature(fileURL: descriptor.fileURL, checkCancellation: checkCancellation) == descriptor + .signature + else { throw DiscoveryError.fileChangedDuringScan } + return document + } + + private static func signature( + fileURL: URL, + checkCancellation: CostUsageScanner.CancellationCheck?) throws -> FileSignature + { + let values = try fileURL.resourceValues(forKeys: [.fileSizeKey, .contentModificationDateKey]) + let handle = try FileHandle(forReadingFrom: fileURL) + defer { try? handle.close() } + var hasher = SHA256() + while true { + try checkCancellation?() + let data = try handle.read(upToCount: 256 * 1024) ?? Data() + guard !data.isEmpty else { break } + hasher.update(data: data) + } + let digest = hasher.finalize().map { String(format: "%02x", $0) }.joined() + return FileSignature( + size: Int64(values.fileSize ?? 0), + modifiedMilliseconds: Int64((values.contentModificationDate?.timeIntervalSince1970 ?? 0) * 1000), + contentSHA256: digest) + } + + private struct ScopedIdentity: Equatable, Hashable { + let scopeID: String + let sessionID: String + } + + private struct ParentLocator { + let roots: [URL] + let checkCancellation: CostUsageScanner.CancellationCheck? + var indexed = false + var filesByIdentity: [ScopedIdentity: Set] = [:] + + mutating func fileURLs(for identity: ScopedIdentity) throws -> [URL]? { + if !self.indexed { + try self.index() + } + guard let matches = self.filesByIdentity[identity], !matches.isEmpty else { return nil } + let owners = Set(matches.compactMap(CostUsageScanner.codexRolloutOwnerID(fileURL:))) + guard matches.count == 1 || owners.count == 1 else { return nil } + return matches.sorted { $0.path < $1.path } + } + + private mutating func index() throws { + self.indexed = true + 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 } + let scopeID = CostUsageScanner.codexLineageScopeID(fileURL: fileURL) + if let owner = CostUsageScanner.codexRolloutOwnerID(fileURL: fileURL) { + self.filesByIdentity[ + .init(scopeID: scopeID, sessionID: CodexLineageTwoPassDiscovery.canonical(owner)), + default: [], + ].insert(fileURL) + } + if let metadata = try CostUsageScanner.parseCodexSessionIdentifier( + fileURL: fileURL, + checkCancellation: self.checkCancellation) + { + self.filesByIdentity[ + .init(scopeID: scopeID, sessionID: CodexLineageTwoPassDiscovery.canonical(metadata)), + default: [], + ].insert(fileURL) + } + } + } + } + } + + private static func canonical(_ value: String) -> String { + UUID(uuidString: value)?.uuidString.lowercased() ?? value + } + + private static func nonEmpty(_ value: String?) -> String? { + guard let value, !value.isEmpty else { return nil } + return value + } +} diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index 8514a9bcb2..88f724d30e 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -104,6 +104,16 @@ enum CostUsageScanner { let snapshots: [CodexTimestampedTotals] let observations: [CodexLineageLedger.Observation] let incompleteObservationCount: Int + let observationCount: Int + } + + struct CodexLineageDocumentSummary: Equatable, Sendable { + let ownerID: String + let metadataSessionID: String? + let parentSessionID: String? + let scopeID: String + let incompleteObservationCount: Int + let observationCount: Int } enum CodexForkBaseline { @@ -1689,6 +1699,8 @@ enum CostUsageScanner { // swiftlint:disable:next cyclomatic_complexity function_body_length private static func parseCodexTokenSnapshots( fileURL: URL, + retainEvidence: Bool = true, + suppressScanErrors: Bool = true, checkCancellation: CancellationCheck? = nil) throws -> CodexParsedTokenEvidence { var sessionId: String? @@ -1698,6 +1710,7 @@ enum CostUsageScanner { var snapshots: [CodexTimestampedTotals] = [] var observations: [CodexLineageLedger.Observation] = [] var incompleteObservationCount = 0 + var observationCount = 0 var warnedAboutUnparsedTimestamp = false func parsedSnapshotDate(timestamp: String) -> Date? { @@ -1721,19 +1734,24 @@ enum CostUsageScanner { if last == nil || total == nil { incompleteObservationCount += 1 } - let counted = accumulator.apply(last: last, total: total) - snapshots.append(CodexTimestampedTotals( - timestamp: timestamp, - date: parsedSnapshotDate(timestamp: timestamp), - totals: counted)) - if let last, let total { - observations.append(CodexLineageLedger.Observation( + if retainEvidence { + let counted = accumulator.apply(last: last, total: total) + snapshots.append(CodexTimestampedTotals( timestamp: timestamp, - model: Self.codexModelEvidence(model) - ?? Self.codexModelEvidence(currentModel) - ?? CostUsagePricing.codexUnattributedModel, - last: Self.lineageTotals(last), - total: Self.lineageTotals(total))) + date: parsedSnapshotDate(timestamp: timestamp), + totals: counted)) + } + if let last, let total { + observationCount += 1 + if retainEvidence { + observations.append(CodexLineageLedger.Observation( + timestamp: timestamp, + model: Self.codexModelEvidence(model) + ?? Self.codexModelEvidence(currentModel) + ?? CostUsagePricing.codexUnattributedModel, + last: Self.lineageTotals(last), + total: Self.lineageTotals(total))) + } } } @@ -1845,6 +1863,9 @@ enum CostUsageScanner { } catch is CancellationError { throw CancellationError() } catch { + if !suppressScanErrors { + throw error + } self.log.warning( "Codex cost usage failed while scanning parent token snapshots", metadata: ["path": fileURL.path, "error": error.localizedDescription]) @@ -1855,7 +1876,8 @@ enum CostUsageScanner { forkedFromId: forkedFromId, snapshots: snapshots, observations: observations, - incompleteObservationCount: incompleteObservationCount) + incompleteObservationCount: incompleteObservationCount, + observationCount: observationCount) } static func parseCodexLineageDocument( @@ -1864,6 +1886,7 @@ enum CostUsageScanner { { let parsed = try Self.parseCodexTokenSnapshots( fileURL: fileURL, + suppressScanErrors: false, checkCancellation: checkCancellation) return CodexLineageLedger.Document( ownerID: Self.codexRolloutOwnerID(fileURL: fileURL) ?? parsed.sessionId ?? fileURL.standardizedFileURL.path, @@ -1874,6 +1897,24 @@ enum CostUsageScanner { incompleteObservationCount: parsed.incompleteObservationCount) } + static func parseCodexLineageDocumentSummary( + fileURL: URL, + checkCancellation: CancellationCheck? = nil) throws -> CodexLineageDocumentSummary + { + let parsed = try Self.parseCodexTokenSnapshots( + fileURL: fileURL, + retainEvidence: false, + suppressScanErrors: false, + checkCancellation: checkCancellation) + return CodexLineageDocumentSummary( + ownerID: Self.codexRolloutOwnerID(fileURL: fileURL) ?? parsed.sessionId ?? fileURL.standardizedFileURL.path, + metadataSessionID: parsed.sessionId, + parentSessionID: parsed.forkedFromId, + scopeID: Self.codexLineageScopeID(fileURL: fileURL), + incompleteObservationCount: parsed.incompleteObservationCount, + observationCount: parsed.observationCount) + } + static func codexLineageScopeID(fileURL: URL) -> String { let standardized = fileURL.standardizedFileURL let components = standardized.pathComponents diff --git a/Tests/CodexBarTests/CodexLineageTwoPassDiscoveryTests.swift b/Tests/CodexBarTests/CodexLineageTwoPassDiscoveryTests.swift new file mode 100644 index 0000000000..11a750c2bf --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageTwoPassDiscoveryTests.swift @@ -0,0 +1,152 @@ +import Foundation +import Testing +@testable import CodexBarCore + +struct CodexLineageTwoPassDiscoveryTests { + @Test + func `pass one retains descriptors without observations and follows exceptional archived parents`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let parentID = "11111111-1111-4111-8111-111111111111" + let childID = "22222222-2222-4222-8222-222222222222" + _ = try Self.writeRollout( + root: environment.codexArchivedSessionsRoot, + ownerID: parentID, + observations: 3) + let child = try Self.writeRollout( + root: environment.codexSessionsRoot.appendingPathComponent("2026/07/09"), + ownerID: childID, + parentID: parentID, + observations: 2) + + let report = try CodexLineageTwoPassDiscovery.discover( + includedFiles: [child], + roots: [environment.codexSessionsRoot, environment.codexArchivedSessionsRoot]) + + #expect(report.descriptors.count == 2) + #expect(report.descriptors.reduce(0) { $0 + $1.observationCount } == 5) + #expect(report.referencedParentDocumentCount == 1) + #expect(report.unresolvedParents.isEmpty) + #expect(report.peakRetainedObservationCount == 0) + } + + @Test + func `streaming reconciliation loads one family at a time and warm reuse loads none`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let first = try Self.writeRollout(root: environment.codexSessionsRoot, ownerID: Self.uuid(1), observations: 50) + let second = try Self.writeRollout(root: environment.codexSessionsRoot, ownerID: Self.uuid(2), observations: 20) + let discovery = try CodexLineageTwoPassDiscovery.discover(includedFiles: [first, second], roots: []) + let families = try CodexLineageEngine.prepareDescriptorFamilies(descriptors: discovery.descriptors) + var coldLoads = 0 + let cold = try CodexLineageEngine.reconcileStreaming( + families: families, + localTimeZone: .gmt, + loadDocument: { descriptor in + coldLoads += 1 + return try CodexLineageTwoPassDiscovery.loadDocument(descriptor) + }) + var warmLoads = 0 + let warm = try CodexLineageEngine.reconcileStreaming( + families: families, + previousCache: cold.candidateCache, + localTimeZone: .gmt, + loadDocument: { descriptor in + warmLoads += 1 + return try CodexLineageTwoPassDiscovery.loadDocument(descriptor) + }) + + #expect(coldLoads == 2) + #expect(cold.diagnostics.observationCount == 70) + #expect(cold.diagnostics.peakFamilyObservationCount == 50) + #expect(warmLoads == 0) + #expect(warm.diagnostics.reusedFamilyCount == 2) + #expect(warm.report == cold.report) + } + + @Test + func `descriptor and family fingerprints are deterministic under file permutation`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let first = try Self.writeRollout(root: environment.codexSessionsRoot, ownerID: Self.uuid(3), observations: 2) + let second = try Self.writeRollout(root: environment.codexSessionsRoot, ownerID: Self.uuid(4), observations: 2) + let forward = try CodexLineageTwoPassDiscovery.discover(includedFiles: [first, second], roots: []) + let reverse = try CodexLineageTwoPassDiscovery.discover(includedFiles: [second, first], roots: []) + let forwardFamilies = try CodexLineageEngine.prepareDescriptorFamilies(descriptors: forward.descriptors) + let reverseFamilies = try CodexLineageEngine.prepareDescriptorFamilies(descriptors: reverse.descriptors) + + #expect(forwardFamilies.map(\.inputFingerprint) == reverseFamilies.map(\.inputFingerprint)) + #expect(forwardFamilies.map(\.stableID) == reverseFamilies.map(\.stableID)) + } + + @Test + func `cancellation before streaming completion produces no candidate`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let file = try Self.writeRollout(root: environment.codexSessionsRoot, ownerID: Self.uuid(5), observations: 100) + let discovery = try CodexLineageTwoPassDiscovery.discover(includedFiles: [file], roots: []) + let families = try CodexLineageEngine.prepareDescriptorFamilies(descriptors: discovery.descriptors) + var checks = 0 + #expect(throws: CancellationError.self) { + _ = try CodexLineageEngine.reconcileStreaming( + families: families, + localTimeZone: .gmt, + checkCancellation: { + checks += 1 + if checks == 4 { + throw CancellationError() + } + }) + } + } + + @Test + func `pass two rejects a rollout changed after discovery`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let file = try Self.writeRollout( + root: environment.codexSessionsRoot, + ownerID: Self.uuid(6), + observations: 2) + let discovery = try CodexLineageTwoPassDiscovery.discover(includedFiles: [file], roots: []) + let descriptor = try #require(discovery.descriptors.first) + try "\n".append(to: file) + + #expect(throws: CodexLineageTwoPassDiscovery.DiscoveryError.fileChangedDuringScan) { + _ = try CodexLineageTwoPassDiscovery.loadDocument(descriptor) + } + } + + private static func writeRollout( + root: URL, + ownerID: String, + parentID: String? = nil, + observations: Int) throws -> URL + { + try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) + let file = root.appendingPathComponent("rollout-2026-07-09T00-00-00-\(ownerID).jsonl") + var lines = [#"{"type":"session_meta","payload":{"id":"\#(ownerID)""# + + (parentID.map { #", "forked_from_id":"\#($0)""# } ?? "") + "}}"] + lines += (0.. String { + String(format: "00000000-0000-4000-8000-%012d", value) + } +} + +extension String { + fileprivate func append(to fileURL: URL) throws { + let handle = try FileHandle(forWritingTo: fileURL) + defer { try? handle.close() } + try handle.seekToEnd() + try handle.write(contentsOf: Data(self.utf8)) + } +} From ea9e382c606f4562392f74d04953b695377ae8a4 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 15:25:37 -0400 Subject: [PATCH 10/12] Define Codex lineage promotion gates --- .../CodexLineagePromotionEvaluator.swift | 227 ++++++++++++++++++ .../CodexLineagePromotionEvaluatorTests.swift | 204 ++++++++++++++++ 2 files changed, 431 insertions(+) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineagePromotionEvaluator.swift create mode 100644 Tests/CodexBarTests/CodexLineagePromotionEvaluatorTests.swift diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineagePromotionEvaluator.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineagePromotionEvaluator.swift new file mode 100644 index 0000000000..300197d5dd --- /dev/null +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineagePromotionEvaluator.swift @@ -0,0 +1,227 @@ +import Foundation + +/// Evidence-based gate for promoting lineage accounting behind a reversible authority switch. +/// +/// This evaluator does not choose token totals or tune an error percentage. It verifies that the +/// independently collected correctness and operational evidence is complete enough to promote. +enum CodexLineagePromotionEvaluator { + enum CancellationStage: String, CaseIterable, Equatable, Hashable, Sendable { + case rootIndexing + case parsing + case graphConstruction + case reconciliation + case prePublication + } + + struct FamilyRoutingEvidence: Equatable, Sendable { + let primaryFamilyCount: Int + let containedFamilyCount: Int + let doubleContributionFamilyCount: Int + let permanentContainmentSupported: Bool + } + + struct PerformanceEvidence: Equatable, Sendable { + let coldMeasured: Bool + let warmMeasured: Bool + let memoryBoundMeasured: Bool + /// Set only after review finds a correctness-neutral regression material enough to block promotion. + let hasMaterialRegression: Bool + } + + struct RollbackEvidence: Equatable, Sendable { + let legacyWholeScanAvailable: Bool + let rollbackPathVerified: Bool + } + + struct Input: Equatable, Sendable { + let residualReport: CodexLineageResidualClassifier.Report + /// Finalized fork-heavy UTC days whose ledger error must be lower than legacy error. + let targetDays: Set + /// Large residuals require an explicit human-reviewed classification before promotion. + let reviewedResidualDays: Set + let adversarialGoldensPassed: Bool + let boundedDiscoveryPassed: Bool + let familyRouting: FamilyRoutingEvidence + let performance: PerformanceEvidence + let cancellationStages: Set + let atomicPublicationPassed: Bool + let rollback: RollbackEvidence + } + + enum Blocker: String, CaseIterable, Equatable, Hashable, Sendable { + case invalidResidualEvidence + case missingTargetDay + case provisionalTargetDay + case targetDayNotImproved + case aggregateErrorNotImproved + case ordinaryDayRegression + case unreviewedLargeResidual + case ledgerDefect + case adversarialGoldenFailure + case boundedDiscoveryFailure + case containmentUnavailable + case familyDoubleContribution + case performanceEvidenceMissing + case materialPerformanceRegression + case cancellationEvidenceMissing + case atomicPublicationFailure + case legacyRollbackUnavailable + case rollbackUnverified + } + + struct Decision: Equatable, Sendable { + /// Canonical case order keeps logs, snapshots, and review artifacts deterministic. + let blockers: [Blocker] + + var canPromote: Bool { + self.blockers.isEmpty + } + + /// Promotion never removes the permanent family-level containment route. + let keepsFamilyContainment: Bool + /// Legacy remains a whole-scan emergency authority until its dedicated removal work. + let keepsLegacyEmergencyRollback: Bool + } + + static func evaluate(_ input: Input) -> Decision { + var blockers: Set = [] + let report = input.residualReport + Self.addReportBlockers(report, to: &blockers) + var daysByID: [String: CodexLineageResidualClassifier.DayResult] = [:] + for day in report.days { + if daysByID.updateValue(day, forKey: day.day) != nil { + blockers.insert(.invalidResidualEvidence) + } + if day.classification == .ledgerDefect { + blockers.insert(.ledgerDefect) + } + if Self.requiresReview(day.classification), !input.reviewedResidualDays.contains(day.day) { + blockers.insert(.unreviewedLargeResidual) + } + } + Self.addTargetBlockers(input.targetDays, daysByID: daysByID, to: &blockers) + Self.addOperationalBlockers(input, to: &blockers) + + return Decision( + blockers: Blocker.allCases.filter(blockers.contains), + keepsFamilyContainment: input.familyRouting.permanentContainmentSupported, + keepsLegacyEmergencyRollback: input.rollback.legacyWholeScanAvailable) + } + + private static func addReportBlockers( + _ report: CodexLineageResidualClassifier.Report, + to blockers: inout Set) + { + if !self.hasValidShape(report) || report.invalidSampleCount > 0 { + blockers.insert(.invalidResidualEvidence) + } + if !report.improvesAggregateError { + blockers.insert(.aggregateErrorNotImproved) + } + if report.ordinaryDayRegressionCount > 0 { + blockers.insert(.ordinaryDayRegression) + } + } + + private static func addTargetBlockers( + _ targetDays: Set, + daysByID: [String: CodexLineageResidualClassifier.DayResult], + to blockers: inout Set) + { + if targetDays.isEmpty { + blockers.insert(.missingTargetDay) + } + for targetDay in targetDays { + guard let day = daysByID[targetDay] else { + blockers.insert(.missingTargetDay) + continue + } + if day.classification == .provisional { + blockers.insert(.provisionalTargetDay) + } else if day.classification == .invalidInput { + blockers.insert(.invalidResidualEvidence) + } else if let legacyError = day.legacyAbsoluteError, let ledgerError = day.ledgerAbsoluteError, + ledgerError >= legacyError + { + blockers.insert(.targetDayNotImproved) + } + } + } + + private static func addOperationalBlockers(_ input: Input, to blockers: inout Set) { + if !input.adversarialGoldensPassed { + blockers.insert(.adversarialGoldenFailure) + } + if !input.boundedDiscoveryPassed { + blockers.insert(.boundedDiscoveryFailure) + } + if !input.familyRouting.permanentContainmentSupported { + blockers.insert(.containmentUnavailable) + } + if input.familyRouting.doubleContributionFamilyCount != 0 { + blockers.insert(.familyDoubleContribution) + } + let familyCountIsInvalid = input.familyRouting.primaryFamilyCount < 0 + || input.familyRouting.containedFamilyCount < 0 + || input.familyRouting.doubleContributionFamilyCount < 0 + || (input.familyRouting.primaryFamilyCount == 0 && input.familyRouting.containedFamilyCount == 0) + if familyCountIsInvalid { + blockers.insert(.invalidResidualEvidence) + } + if !input.performance.coldMeasured || !input.performance.warmMeasured || !input.performance + .memoryBoundMeasured + { + blockers.insert(.performanceEvidenceMissing) + } + if input.performance.hasMaterialRegression { + blockers.insert(.materialPerformanceRegression) + } + if input.cancellationStages != Set(CancellationStage.allCases) { + blockers.insert(.cancellationEvidenceMissing) + } + if !input.atomicPublicationPassed { + blockers.insert(.atomicPublicationFailure) + } + if !input.rollback.legacyWholeScanAvailable { + blockers.insert(.legacyRollbackUnavailable) + } + if !input.rollback.rollbackPathVerified { + blockers.insert(.rollbackUnverified) + } + } + + private static func hasValidShape(_ report: CodexLineageResidualClassifier.Report) -> Bool { + guard report.invalidSampleCount >= 0, + report.ordinaryDayRegressionCount >= 0, + report.finalizedReferenceTokens >= 0, + report.finalizedLegacyTokens >= 0, + report.finalizedLedgerTokens >= 0, + report.legacyAbsoluteError >= 0, + report.ledgerAbsoluteError >= 0, + report.invalidSampleCount == report.days.count(where: { $0.classification == .invalidInput }), + report.legacyAbsoluteError == abs(report.finalizedLegacyTokens - report.finalizedReferenceTokens), + report.ledgerAbsoluteError == abs(report.finalizedLedgerTokens - report.finalizedReferenceTokens) + else { return false } + return report.days.allSatisfy { day in + switch day.classification { + case .invalidInput, .provisional: + day.legacyAbsoluteError == nil && day.ledgerAbsoluteError == nil + case .withinTolerance, .unavailableHistory, .unsupportedEventShape, .utcLocalAttribution, + .accountingSemantics, .containment, .ledgerDefect: + day.legacyAbsoluteError != nil && day.ledgerAbsoluteError != nil + } + } + } + + private static func requiresReview(_ classification: CodexLineageResidualClassifier.Classification) -> Bool { + switch classification { + case .withinTolerance: + false + case .invalidInput, .provisional: + false + case .unavailableHistory, .unsupportedEventShape, .utcLocalAttribution, .accountingSemantics, + .containment, .ledgerDefect: + true + } + } +} diff --git a/Tests/CodexBarTests/CodexLineagePromotionEvaluatorTests.swift b/Tests/CodexBarTests/CodexLineagePromotionEvaluatorTests.swift new file mode 100644 index 0000000000..ba29ae74af --- /dev/null +++ b/Tests/CodexBarTests/CodexLineagePromotionEvaluatorTests.swift @@ -0,0 +1,204 @@ +import Testing +@testable import CodexBarCore + +struct CodexLineagePromotionEvaluatorTests { + @Test + func `complete evidence promotes while retaining containment and legacy rollback`() { + let decision = CodexLineagePromotionEvaluator.evaluate(Self.readyInput()) + + #expect(decision.canPromote) + #expect(decision.blockers.isEmpty) + #expect(decision.keepsFamilyContainment) + #expect(decision.keepsLegacyEmergencyRollback) + } + + @Test + func `promotion is evidence based rather than a fixed aggregate percentage`() { + let report = CodexLineageResidualClassifier.classify(samples: [ + Self.sample( + day: "2026-07-09", + reference: 1_000_000, + legacy: 100_000, + ledger: 100_001, + ordinary: false, + exhaustive: true), + ]) + var input = Self.readyInput(report: report, targetDays: ["2026-07-09"]) + input = .init( + residualReport: input.residualReport, + targetDays: input.targetDays, + reviewedResidualDays: ["2026-07-09"], + adversarialGoldensPassed: input.adversarialGoldensPassed, + boundedDiscoveryPassed: input.boundedDiscoveryPassed, + familyRouting: input.familyRouting, + performance: input.performance, + cancellationStages: input.cancellationStages, + atomicPublicationPassed: input.atomicPublicationPassed, + rollback: input.rollback) + + let decision = CodexLineagePromotionEvaluator.evaluate(input) + #expect(decision.canPromote) + } + + @Test + func `ordinary regression and unreviewed residual block promotion`() { + let report = CodexLineageResidualClassifier.classify(samples: [ + Self.sample(day: "2026-07-09", reference: 1000, legacy: 500, ledger: 900, ordinary: false), + Self.sample(day: "2026-07-10", reference: 1000, legacy: 1000, ledger: 1100, ordinary: true), + ]) + let ready = Self.readyInput(report: report, targetDays: ["2026-07-09"]) + let input = CodexLineagePromotionEvaluator.Input( + residualReport: ready.residualReport, + targetDays: ready.targetDays, + reviewedResidualDays: [], + adversarialGoldensPassed: ready.adversarialGoldensPassed, + boundedDiscoveryPassed: ready.boundedDiscoveryPassed, + familyRouting: ready.familyRouting, + performance: ready.performance, + cancellationStages: ready.cancellationStages, + atomicPublicationPassed: ready.atomicPublicationPassed, + rollback: ready.rollback) + + let decision = CodexLineagePromotionEvaluator.evaluate(input) + #expect(decision.blockers.contains(.ordinaryDayRegression)) + #expect(decision.blockers.contains(.unreviewedLargeResidual)) + #expect(!decision.canPromote) + } + + @Test + func `non target large residual still requires review`() { + let report = CodexLineageResidualClassifier.classify(samples: [ + Self.sample(day: "2026-07-09", reference: 1000, legacy: 500, ledger: 950, ordinary: false), + Self.sample(day: "2026-07-10", reference: 1000, legacy: 100, ledger: 900, ordinary: false), + ]) + let ready = Self.readyInput(report: report, targetDays: ["2026-07-09"]) + let input = CodexLineagePromotionEvaluator.Input( + residualReport: ready.residualReport, + targetDays: ready.targetDays, + reviewedResidualDays: ["2026-07-09"], + adversarialGoldensPassed: ready.adversarialGoldensPassed, + boundedDiscoveryPassed: ready.boundedDiscoveryPassed, + familyRouting: ready.familyRouting, + performance: ready.performance, + cancellationStages: ready.cancellationStages, + atomicPublicationPassed: ready.atomicPublicationPassed, + rollback: ready.rollback) + + #expect(CodexLineagePromotionEvaluator.evaluate(input).blockers == [.unreviewedLargeResidual]) + } + + @Test + func `duplicate residual days fail closed without trapping`() { + let sample = Self.sample(day: "2026-07-09", reference: 1000, legacy: 500, ledger: 950, ordinary: false) + let report = CodexLineageResidualClassifier.classify(samples: [sample, sample]) + let decision = CodexLineagePromotionEvaluator.evaluate(Self.readyInput( + report: report, + targetDays: ["2026-07-09"])) + + #expect(decision.blockers.contains(.invalidResidualEvidence)) + #expect(!decision.canPromote) + } + + @Test + func `family overlap blocks promotion even when residual totals improve`() { + let ready = Self.readyInput() + let input = CodexLineagePromotionEvaluator.Input( + residualReport: ready.residualReport, + targetDays: ready.targetDays, + reviewedResidualDays: ready.reviewedResidualDays, + adversarialGoldensPassed: true, + boundedDiscoveryPassed: true, + familyRouting: .init( + primaryFamilyCount: 10, + containedFamilyCount: 2, + doubleContributionFamilyCount: 1, + permanentContainmentSupported: true), + performance: ready.performance, + cancellationStages: ready.cancellationStages, + atomicPublicationPassed: true, + rollback: ready.rollback) + + let decision = CodexLineagePromotionEvaluator.evaluate(input) + #expect(decision.blockers == [.familyDoubleContribution]) + } + + @Test + func `operational and rollback evidence are mandatory`() { + let ready = Self.readyInput() + let input = CodexLineagePromotionEvaluator.Input( + residualReport: ready.residualReport, + targetDays: ready.targetDays, + reviewedResidualDays: ready.reviewedResidualDays, + adversarialGoldensPassed: true, + boundedDiscoveryPassed: true, + familyRouting: ready.familyRouting, + performance: .init( + coldMeasured: true, + warmMeasured: false, + memoryBoundMeasured: false, + hasMaterialRegression: true), + cancellationStages: [.parsing, .reconciliation], + atomicPublicationPassed: false, + rollback: .init(legacyWholeScanAvailable: false, rollbackPathVerified: false)) + + let decision = CodexLineagePromotionEvaluator.evaluate(input) + #expect(decision.blockers.contains(.performanceEvidenceMissing)) + #expect(decision.blockers.contains(.materialPerformanceRegression)) + #expect(decision.blockers.contains(.cancellationEvidenceMissing)) + #expect(decision.blockers.contains(.atomicPublicationFailure)) + #expect(decision.blockers.contains(.legacyRollbackUnavailable)) + #expect(decision.blockers.contains(.rollbackUnverified)) + #expect(decision.blockers == CodexLineagePromotionEvaluator.Blocker.allCases.filter { + decision.blockers.contains($0) + }) + } + + private static func readyInput( + report: CodexLineageResidualClassifier.Report? = nil, + targetDays: Set = ["2026-07-09", "2026-07-10"]) -> CodexLineagePromotionEvaluator.Input + { + let report = report ?? CodexLineageResidualClassifier.classify(samples: [ + Self.sample(day: "2026-07-09", reference: 1000, legacy: 500, ledger: 950, ordinary: false), + Self.sample(day: "2026-07-10", reference: 2000, legacy: 1000, ledger: 1980, ordinary: false), + Self.sample(day: "2026-07-08", reference: 500, legacy: 500, ledger: 500, ordinary: true), + ]) + return .init( + residualReport: report, + targetDays: targetDays, + reviewedResidualDays: targetDays, + adversarialGoldensPassed: true, + boundedDiscoveryPassed: true, + familyRouting: .init( + primaryFamilyCount: 10, + containedFamilyCount: 2, + doubleContributionFamilyCount: 0, + permanentContainmentSupported: true), + performance: .init( + coldMeasured: true, + warmMeasured: true, + memoryBoundMeasured: true, + hasMaterialRegression: false), + cancellationStages: Set(CodexLineagePromotionEvaluator.CancellationStage.allCases), + atomicPublicationPassed: true, + rollback: .init(legacyWholeScanAvailable: true, rollbackPathVerified: true)) + } + + private static func sample( + day: String, + reference: Int, + legacy: Int, + ledger: Int, + ordinary: Bool, + exhaustive: Bool = false) -> CodexLineageResidualClassifier.Sample + { + .init( + day: day, + referenceTokens: reference, + isReferenceFinalized: true, + isOrdinaryDay: ordinary, + legacyTokens: legacy, + ledgerUTCTokens: ledger, + ledgerLocalTokens: ledger, + evidence: .init(localCorpusWasExhaustive: exhaustive, duplicateObservationCount: ordinary ? 0 : 1)) + } +} From 734f0f6abf092f0c754641d1fda633d65610973c Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 15:49:05 -0400 Subject: [PATCH 11/12] Add Codex lineage accounting selector --- .../Generated/CodexParserHash.generated.swift | 2 +- .../CodexLineageAccountingSelector.swift | 108 +++++++++++++++ .../Vendored/CostUsage/CostUsageScanner.swift | 121 ++++++++++++----- .../CodexLineageAccountingSelectorTests.swift | 125 ++++++++++++++++++ 4 files changed, 323 insertions(+), 33 deletions(-) create mode 100644 Sources/CodexBarCore/Providers/Codex/CodexLineageAccountingSelector.swift create mode 100644 Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index c0e0dd2e96..fa6a5f143f 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "84c52421265e9fc8" + static let value = "4169e0ab9fbb53c2" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageAccountingSelector.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageAccountingSelector.swift new file mode 100644 index 0000000000..37e6b385fc --- /dev/null +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageAccountingSelector.swift @@ -0,0 +1,108 @@ +import Foundation + +enum CodexLineageAccountingMode: String, CaseIterable, Sendable { + case legacy + case shadow + case lineage + + static let defaultMode: Self = .legacy + static let schemaVersion = 1 + + var producerKeySuffix: String { + "lineage-accounting:\(self.rawValue):v\(Self.schemaVersion)" + } +} + +/// Selects one whole-scan authority while preserving a permanent family-scoped containment route. +enum CodexLineageAccountingSelector { + typealias PackedDays = [String: [String: [Int]]] + + enum SelectionError: Error, Equatable { + case missingContainedFamilyEvidence + } + + struct ContainedDocument: Equatable, Sendable { + /// Stable logical rollout identity. Physical active/archive copies share this value. + let identity: String + let days: PackedDays + } + + struct ContainedFamily: Equatable, Sendable { + /// Legacy file contributions belonging only to this contained family. + let documents: [ContainedDocument] + } + + struct Selection: Equatable, Sendable { + let days: PackedDays + let usedLineageAuthority: Bool + let containedFamilyCount: Int + } + + static func select( + mode: CodexLineageAccountingMode, + legacyDays: PackedDays, + primaryRows: [CodexLineageLedger.DailyRow], + containedFamilies: [ContainedFamily]) -> Selection + { + guard mode == .lineage else { + return Selection(days: legacyDays, usedLineageAuthority: false, containedFamilyCount: 0) + } + var days = Self.days(from: primaryRows) + for family in containedFamilies { + Self.add(Self.containedDays(family.documents), to: &days) + } + return Selection( + days: days, + usedLineageAuthority: true, + containedFamilyCount: containedFamilies.count) + } + + /// A contained family contributes once. Physical copies of one logical rollout use an envelope; + /// distinct siblings remain additive so containment does not discard their independent work. + private static func containedDays(_ documents: [ContainedDocument]) -> PackedDays { + var documentsByIdentity: [String: [PackedDays]] = [:] + for document in documents { + documentsByIdentity[document.identity, default: []].append(document.days) + } + var result: PackedDays = [:] + for copies in documentsByIdentity.values { + var envelope: PackedDays = [:] + for copy in copies { + for (day, models) in copy { + for (model, packed) in models { + let existing = envelope[day]?[model] ?? [0, 0, 0] + envelope[day, default: [:]][model] = (0..<3).map { index in + max(existing[safe: index] ?? 0, packed[safe: index] ?? 0) + } + } + } + } + Self.add(envelope, to: &result) + } + return result + } + + private static func days(from rows: [CodexLineageLedger.DailyRow]) -> PackedDays { + var days: PackedDays = [:] + for row in rows { + var packed = days[row.day]?[row.model] ?? [0, 0, 0] + packed[0] += row.totals.input + packed[1] += row.totals.cached + packed[2] += row.totals.output + days[row.day, default: [:]][row.model] = packed + } + return days + } + + private static func add(_ source: PackedDays, to destination: inout PackedDays) { + for (day, models) in source { + for (model, packed) in models { + var value = destination[day]?[model] ?? [0, 0, 0] + for index in 0..<3 { + value[index] += packed[safe: index] ?? 0 + } + destination[day, default: [:]][model] = value + } + } + } +} diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index 88f724d30e..bb8f024a78 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -28,6 +28,7 @@ enum CostUsageScanner { var codexTraceDatabaseURL: URL? var refreshMinIntervalSeconds: TimeInterval = 60 var claudeLogProviderFilter: ClaudeLogProviderFilter = .all + var codexLineageAccountingMode: CodexLineageAccountingMode = .defaultMode /// Force a full rescan, ignoring per-file cache and incremental offsets. var forceRescan: Bool = false @@ -37,6 +38,7 @@ enum CostUsageScanner { cacheRoot: URL? = nil, codexTraceDatabaseURL: URL? = nil, claudeLogProviderFilter: ClaudeLogProviderFilter = .all, + codexLineageAccountingMode: CodexLineageAccountingMode = .defaultMode, forceRescan: Bool = false) { self.codexSessionsRoot = codexSessionsRoot @@ -44,6 +46,7 @@ enum CostUsageScanner { self.cacheRoot = cacheRoot self.codexTraceDatabaseURL = codexTraceDatabaseURL self.claudeLogProviderFilter = claudeLogProviderFilter + self.codexLineageAccountingMode = codexLineageAccountingMode self.forceRescan = forceRescan } } @@ -2613,7 +2616,11 @@ enum CostUsageScanner { options: Options, checkCancellation: CancellationCheck?) throws -> CostUsageDailyReport { - var cache = CostUsageCacheIO.load(provider: .codex, cacheRoot: options.cacheRoot) + let accountingProducerKey = Self.codexAccountingProducerKey(mode: options.codexLineageAccountingMode) + var cache = CostUsageCacheIO.load( + provider: .codex, + cacheRoot: options.cacheRoot, + producerKey: accountingProducerKey) let nowMs = Int64(now.timeIntervalSince1970 * 1000) let plan = Self.makeCodexRefreshPlan(cache: cache, range: range, now: now, nowMs: nowMs, options: options) @@ -2740,12 +2747,13 @@ enum CostUsageScanner { ? [cachedUntilKey, range.scanUntilKey].compactMap(\.self).max() ?? range.scanUntilKey : range.scanUntilKey Self.pruneDays(cache: &cache, sinceKey: retainedSinceKey, untilKey: retainedUntilKey) - try Self.recordCodexLineageShadow( + try Self.applyCodexLineageAccounting( + mode: options.codexLineageAccountingMode, files: files, roots: plan.roots, - cache: cache, - range: range, + cache: &cache, checkCancellation: checkCancellation) + Self.pruneDays(cache: &cache, sinceKey: retainedSinceKey, untilKey: retainedUntilKey) cache.roots = plan.rootsFingerprint cache.scanSinceKey = retainedSinceKey cache.scanUntilKey = retainedUntilKey @@ -2768,7 +2776,11 @@ enum CostUsageScanner { } cache.lastScanUnixMs = nowMs try checkCancellation?() - CostUsageCacheIO.save(provider: .codex, cache: cache, cacheRoot: options.cacheRoot) + CostUsageCacheIO.save( + provider: .codex, + cache: cache, + cacheRoot: options.cacheRoot, + producerKey: accountingProducerKey) } return Self.buildCodexReportFromCache( @@ -2779,48 +2791,93 @@ enum CostUsageScanner { priorityTurns: plan.priorityTurns) } - private static func recordCodexLineageShadow( + static func codexAccountingProducerKey(mode: CodexLineageAccountingMode) -> String { + let base = CostUsageCacheIO.currentProducerKey(provider: .codex) ?? "codex" + return mode == .legacy ? base : base + ":" + mode.producerKeySuffix + } + + static func shouldRunCodexLineage(mode: CodexLineageAccountingMode) -> Bool { + mode != .legacy + } + + private static func applyCodexLineageAccounting( + mode: CodexLineageAccountingMode, files: [URL], roots: [URL], - cache: CostUsageCache, - range: CostUsageDayRange, + cache: inout CostUsageCache, checkCancellation: CancellationCheck?) throws { + guard self.shouldRunCodexLineage(mode: mode) else { return } do { - let report = try CodexLineageShadow.run( + let discovery = try CodexLineageTwoPassDiscovery.discover( includedFiles: files, roots: roots, - legacyDays: cache.days, - dayRange: range.sinceKey...range.untilKey, + checkCancellation: checkCancellation) + let families = try CodexLineageEngine.prepareDescriptorFamilies( + descriptors: discovery.descriptors, + unresolvedParents: discovery.unresolvedParents, + checkCancellation: checkCancellation) + let lineage = try CodexLineageEngine.reconcileStreaming( + families: families, localTimeZone: .current, checkCancellation: checkCancellation) - self.log.info( - "Codex lineage shadow comparison completed", + let resultsByStableID = Dictionary(uniqueKeysWithValues: lineage.families.map { ($0.stableID, $0) }) + let contained = families.compactMap { family -> CodexLineageAccountingSelector.ContainedFamily? in + guard let result = resultsByStableID[family.stableID], case .contained = result.quality else { + return nil + } + let documents = family.descriptors.compactMap { descriptor -> + CodexLineageAccountingSelector.ContainedDocument? in + guard let days = cache.files[descriptor.fileURL.path]?.days else { return nil } + let identity = descriptor.scopeID + "\u{0}" + + (descriptor.metadataSessionID ?? descriptor.ownerID).lowercased() + return .init(identity: identity, days: days) + } + guard documents.count == family.descriptors.count else { return nil } + return .init(documents: documents) + } + let expectedContainedCount = lineage.families.count { + if case .contained = $0.quality { + return true + } + return false + } + if mode == .lineage, contained.count != expectedContainedCount { + throw CodexLineageAccountingSelector.SelectionError.missingContainedFamilyEvidence + } + let selection = CodexLineageAccountingSelector.select( + mode: mode, + legacyDays: cache.days, + primaryRows: lineage.report.localRows, + containedFamilies: contained) + try checkCancellation?() + + #if DEBUG + self.log.debug( + "Codex lineage accounting comparison completed", metadata: [ - "accepted": "\(report.acceptedObservationCount)", - "components": "\(report.componentCount)", - "days": "\(report.days.count)", - "duplicates": "\(report.duplicateObservationCount)", - "referencedParents": "\(report.referencedParentDocumentCount)", - "rejected": "\(report.rejectedObservationCount)", - "unresolvedParents": "\(report.unresolvedParentCount)", + "containedFamilies": "\(contained.count)", + "families": "\(lineage.diagnostics.familyCount)", + "mode": mode.rawValue, + "recomputedFamilies": "\(lineage.diagnostics.recomputedFamilyCount)", ]) - for day in report.days where day.delta != .zero { - self.log.info( - "Codex lineage shadow daily difference", - metadata: [ - "cachedDelta": "\(day.delta.cached)", - "day": "\(day.day)", - "inputDelta": "\(day.delta.input)", - "outputDelta": "\(day.delta.output)", - ]) + #endif + + if selection.usedLineageAuthority { + cache.days = selection.days + // Legacy per-file rows are not valid pricing/project evidence for ledger totals. + // Dropping them also makes rollback and the next mode-specific refresh rebuild safely. + cache.files = [:] } } catch is CancellationError { throw CancellationError() } catch { - self.log.warning( - "Codex lineage shadow comparison failed", - metadata: ["errorType": "\(type(of: error))"]) + if mode == .lineage { + throw error + } + #if DEBUG + self.log.debug("Codex lineage shadow comparison failed; legacy totals remain authoritative") + #endif } } diff --git a/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift b/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift new file mode 100644 index 0000000000..c1d75429f4 --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift @@ -0,0 +1,125 @@ +import Testing +@testable import CodexBarCore + +struct CodexLineageAccountingSelectorTests { + @Test + func `legacy and shadow modes keep legacy authority`() { + let legacy = Self.days(input: 100) + let primary = [Self.row(input: 40)] + for mode in [CodexLineageAccountingMode.legacy, .shadow] { + let selection = CodexLineageAccountingSelector.select( + mode: mode, + legacyDays: legacy, + primaryRows: primary, + containedFamilies: [.init(documents: [.init(identity: "parent", days: Self.days(input: 20))])]) + #expect(selection.days == legacy) + #expect(!selection.usedLineageAuthority) + #expect(selection.containedFamilyCount == 0) + } + } + + @Test + func `lineage mode combines primary and family containment exactly once`() { + let selection = CodexLineageAccountingSelector.select( + mode: .lineage, + legacyDays: Self.days(input: 999), + primaryRows: [Self.row(input: 100)], + containedFamilies: [ + .init(documents: [ + .init(identity: "copy", days: Self.days(input: 40)), + .init(identity: "copy", days: Self.days(input: 40)), + ]), + .init(documents: [.init(identity: "other", days: Self.days(input: 10))]), + ]) + + #expect(selection.usedLineageAuthority) + #expect(selection.containedFamilyCount == 2) + #expect(selection.days["2026-07-09"]?["gpt-5.4"]?[0] == 150) + } + + @Test + func `contained family uses component envelope instead of summing fork copies`() { + let first: CodexLineageAccountingSelector.PackedDays = [ + "2026-07-09": ["gpt-5.4": [100, 80, 5]], + ] + let copied: CodexLineageAccountingSelector.PackedDays = [ + "2026-07-09": ["gpt-5.4": [100, 60, 8]], + ] + let selection = CodexLineageAccountingSelector.select( + mode: .lineage, + legacyDays: [:], + primaryRows: [], + containedFamilies: [.init(documents: [ + .init(identity: "same", days: first), + .init(identity: "same", days: copied), + ])]) + + #expect(selection.days["2026-07-09"]?["gpt-5.4"] == [100, 80, 8]) + } + + @Test + func `contained siblings remain additive while physical copies are enveloped`() { + let selection = CodexLineageAccountingSelector.select( + mode: .lineage, + legacyDays: [:], + primaryRows: [], + containedFamilies: [.init(documents: [ + .init(identity: "child-a", days: Self.days(input: 40)), + .init(identity: "child-a", days: Self.days(input: 40)), + .init(identity: "child-b", days: Self.days(input: 10)), + ])]) + + #expect(selection.days["2026-07-09"]?["gpt-5.4"]?[0] == 50) + } + + @Test + func `mode cache suffixes are schema scoped and distinct`() { + #expect(CodexLineageAccountingMode.defaultMode == .legacy) + #expect(CodexLineageAccountingMode.shadow.producerKeySuffix != CodexLineageAccountingMode.lineage + .producerKeySuffix) + #expect(CodexLineageAccountingMode.shadow.producerKeySuffix.contains("v1")) + } + + @Test + func `scanner defaults to legacy and skips lineage execution`() { + let options = CostUsageScanner.Options() + #expect(options.codexLineageAccountingMode == .legacy) + #expect(!CostUsageScanner.shouldRunCodexLineage(mode: options.codexLineageAccountingMode)) + #expect(CostUsageScanner.shouldRunCodexLineage(mode: .shadow)) + #expect(CostUsageScanner.shouldRunCodexLineage(mode: .lineage)) + } + + @Test + func `mode specific producer key mismatch invalidates cache for rollback rebuild`() throws { + let environment = try CostUsageTestEnvironment() + defer { environment.cleanup() } + let shadowKey = CostUsageScanner.codexAccountingProducerKey(mode: .shadow) + let legacyKey = CostUsageScanner.codexAccountingProducerKey(mode: .legacy) + var shadowCache = CostUsageCache() + shadowCache.days = Self.days(input: 100) + CostUsageCacheIO.save( + provider: .codex, + cache: shadowCache, + cacheRoot: environment.cacheRoot, + producerKey: shadowKey) + + let rollbackLoad = CostUsageCacheIO.load( + provider: .codex, + cacheRoot: environment.cacheRoot, + producerKey: legacyKey) + #expect(rollbackLoad.days.isEmpty) + #expect(shadowKey != legacyKey) + } + + private static func days(input: Int) -> CodexLineageAccountingSelector.PackedDays { + ["2026-07-09": ["gpt-5.4": [input, 0, 0]]] + } + + private static func row(input: Int) -> CodexLineageLedger.DailyRow { + .init( + day: "2026-07-09", + model: "gpt-5.4", + totals: .init(input: input, cached: 0, output: 0), + costUSD: 0) + } +} From f95188c17644891ba6537ab1d76fe5187b0319e0 Mon Sep 17 00:00:00 2001 From: Bryan Font Date: Mon, 13 Jul 2026 17:52:43 -0400 Subject: [PATCH 12/12] Validate lineage accounting on local histories --- .../Generated/CodexParserHash.generated.swift | 2 +- .../Providers/Codex/CodexLineageLedger.swift | 21 +- .../Vendored/CostUsage/CostUsageScanner.swift | 11 +- .../CodexLineageAccountingSelectorTests.swift | 15 + .../CodexLineageLedgerTests.swift | 45 +++ .../CodexLineageLocalValidationTests.swift | 351 ++++++++++++++++++ 6 files changed, 436 insertions(+), 9 deletions(-) create mode 100644 Tests/CodexBarTests/CodexLineageLocalValidationTests.swift diff --git a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift b/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift index fa6a5f143f..66e60596f4 100644 --- a/Sources/CodexBarCore/Generated/CodexParserHash.generated.swift +++ b/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 = "4169e0ab9fbb53c2" + static let value = "5caa3e1eda239d03" } diff --git a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift index 7152a3aab0..8fc8e3df9d 100644 --- a/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift +++ b/Sources/CodexBarCore/Providers/Codex/CodexLineageLedger.swift @@ -374,17 +374,26 @@ enum CodexLineageLedger { } private static func hasAncestryCycle(_ documents: [Document]) -> Bool { + let owners = Set(documents.map { Self.canonicalIdentity($0.ownerID) }) let metadataOwners = Dictionary(grouping: documents.compactMap { document in - document.metadataSessionID.map { ($0, document.ownerID) } + Self.nonEmpty(document.metadataSessionID).map { + (Self.canonicalIdentity($0), Self.canonicalIdentity(document.ownerID)) + } }, by: \.0).mapValues { Set($0.map(\.1)) } var parents: [String: Set] = [:] for document in documents { guard let parent = Self.nonEmpty(document.parentSessionID) else { continue } - var targets = metadataOwners[parent] ?? [parent] - if parent != document.ownerID { - targets.remove(document.ownerID) + let owner = Self.canonicalIdentity(document.ownerID) + let canonicalParent = Self.canonicalIdentity(parent) + // Prefer an exact physical owner. A metadata alias may establish an edge only when it + // identifies one physical owner; retained aliases shared by fork siblings are ambiguous. + if owners.contains(canonicalParent) { + parents[owner, default: []].insert(canonicalParent) + } else if let targets = metadataOwners[canonicalParent], targets.count == 1, + let target = targets.first + { + parents[owner, default: []].insert(target) } - parents[document.ownerID, default: []].formUnion(targets) } var visiting: Set = [] var visited: Set = [] @@ -403,7 +412,7 @@ enum CodexLineageLedger { visited.insert(owner) return false } - return Set(documents.map(\.ownerID)).contains(where: visit) + return owners.contains(where: visit) } /// Duplicate copies can carry different model evidence. Keep the earliest physical copy, diff --git a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift index bb8f024a78..3964cac3e6 100644 --- a/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift +++ b/Sources/CodexBarCore/Vendored/CostUsage/CostUsageScanner.swift @@ -2829,8 +2829,11 @@ enum CostUsageScanner { let documents = family.descriptors.compactMap { descriptor -> CodexLineageAccountingSelector.ContainedDocument? in guard let days = cache.files[descriptor.fileURL.path]?.days else { return nil } - let identity = descriptor.scopeID + "\u{0}" - + (descriptor.metadataSessionID ?? descriptor.ownerID).lowercased() + // Active/archive copies share the filename owner. Fork children can retain an + // ancestor metadata ID, so metadata is not a safe physical-copy identity here. + let identity = Self.codexContainedDocumentIdentity( + scopeID: descriptor.scopeID, + ownerID: descriptor.ownerID) return .init(identity: identity, days: days) } guard documents.count == family.descriptors.count else { return nil } @@ -2881,6 +2884,10 @@ enum CostUsageScanner { } } + static func codexContainedDocumentIdentity(scopeID: String, ownerID: String) -> String { + scopeID + "\u{0}" + (UUID(uuidString: ownerID)?.uuidString.lowercased() ?? ownerID) + } + private static func codexFileScanContext( range: CostUsageDayRange, options: Options, diff --git a/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift b/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift index c1d75429f4..37863553a1 100644 --- a/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift +++ b/Tests/CodexBarTests/CodexLineageAccountingSelectorTests.swift @@ -72,6 +72,21 @@ struct CodexLineageAccountingSelectorTests { #expect(selection.days["2026-07-09"]?["gpt-5.4"]?[0] == 50) } + @Test + func `containment copy identity follows physical owner rather than retained metadata`() { + let first = CostUsageScanner.codexContainedDocumentIdentity( + scopeID: "home", + ownerID: "00000000-0000-4000-8000-000000000001") + let sibling = CostUsageScanner.codexContainedDocumentIdentity( + scopeID: "home", + ownerID: "00000000-0000-4000-8000-000000000002") + + #expect(first != sibling) + #expect(first == CostUsageScanner.codexContainedDocumentIdentity( + scopeID: "home", + ownerID: "00000000-0000-4000-8000-000000000001")) + } + @Test func `mode cache suffixes are schema scoped and distinct`() { #expect(CodexLineageAccountingMode.defaultMode == .legacy) diff --git a/Tests/CodexBarTests/CodexLineageLedgerTests.swift b/Tests/CodexBarTests/CodexLineageLedgerTests.swift index 4d23eb192d..f6a80c9af2 100644 --- a/Tests/CodexBarTests/CodexLineageLedgerTests.swift +++ b/Tests/CodexBarTests/CodexLineageLedgerTests.swift @@ -448,6 +448,51 @@ struct CodexLineageLedgerTests { #expect(report.families.first?.quality == .primary) } + @Test + func `retained metadata across multiple fork generations does not create sibling cycles`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let root = Self.document(owner: "root", metadata: "root", observations: [observation]) + let firstFork = Self.document( + owner: "first-fork", + metadata: "root", + parent: "root", + observations: [observation]) + let secondFork = Self.document( + owner: "second-fork", + metadata: "root", + parent: "first-fork", + observations: [observation]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [root, firstFork, secondFork], + localTimeZone: .gmt) + + #expect(report.primary.utcDays["2026-07-09"]?.input == 100) + #expect(report.families.first?.quality == .primary) + } + + @Test + func `unique metadata aliases still reveal physical ancestry cycles`() throws { + let observation = Self.observation(timestamp: "2026-07-09T12:00:00Z", input: 100, totalInput: 100) + let first = Self.document( + owner: "first-owner", + metadata: "first-alias", + parent: "second-alias", + observations: [observation]) + let second = Self.document( + owner: "second-owner", + metadata: "second-alias", + parent: "first-alias", + observations: [observation]) + + let report = try CodexLineageLedger.reconcileConservatively( + documents: [first, second], + localTimeZone: .gmt) + + #expect(report.primary.utcDays.isEmpty) + #expect(report.families.first?.quality == .contained([.ancestryCycle])) + } + @Test func `unrelated owners sharing an ungrounded metadata identity are contained`() throws { let first = Self.document( diff --git a/Tests/CodexBarTests/CodexLineageLocalValidationTests.swift b/Tests/CodexBarTests/CodexLineageLocalValidationTests.swift new file mode 100644 index 0000000000..df373f2cfb --- /dev/null +++ b/Tests/CodexBarTests/CodexLineageLocalValidationTests.swift @@ -0,0 +1,351 @@ +import Foundation +import Testing +@testable import CodexBarCore +#if os(macOS) +import Darwin +#endif + +/// Opt-in aggregate-only replay. Run with `TZ=UTC CODEXBAR_RUN_LINEAGE_VALIDATION=1 swift test --filter ...`. +/// Never print rollout paths, identities, models, or contents. +struct CodexLineageLocalValidationTests { + private enum ValidationError: Error { + case extraFileOutsideCodexHome + case extraFileOutsideRolloutRoots + case extraFileMissingFromSnapshot + case invalidReferenceTotals + } + + private struct Reference: Codable { + let tokens: Int + let finalized: Bool + } + + // The opt-in replay is intentionally linear so its immutable snapshot, scan, and comparison + // lifecycle stays auditable in one place. + // swiftlint:disable function_body_length + @Test + func `local UTC lineage validation`() throws { + guard ProcessInfo.processInfo.environment["CODEXBAR_RUN_LINEAGE_VALIDATION"] == "1" else { return } + CodexBarLog.setLogLevel(.critical) + let home = URL(fileURLWithPath: ("~/.codex" as NSString).expandingTildeInPath, isDirectory: true) + let existingRoot = ProcessInfo.processInfo.environment["CODEXBAR_LINEAGE_VALIDATION_ROOT"].map { + URL(fileURLWithPath: $0, isDirectory: true) + } + let validationRoot = existingRoot ?? FileManager.default.temporaryDirectory + .appendingPathComponent("codexbar-lineage-validation-\(UUID().uuidString)", isDirectory: true) + defer { + if existingRoot == nil { + try? FileManager.default.removeItem(at: validationRoot) + } + } + let snapshotHome = validationRoot.appendingPathComponent("codex-home", isDirectory: true) + if !FileManager.default.fileExists(atPath: snapshotHome.path) { + try Self.snapshotCodexHome(source: home, destination: snapshotHome) + } + let sessions = snapshotHome.appendingPathComponent("sessions", isDirectory: true) + let archived = snapshotHome.appendingPathComponent("archived_sessions", isDirectory: true) + let included = try Array(Set( + Self.rollouts(roots: [sessions, archived], days: Self.discoveryDays) + + (Self.extraValidationFiles(sourceHome: home, snapshotHome: snapshotHome)))) + .sorted { $0.path < $1.path } + let cacheRoot = validationRoot.appendingPathComponent("legacy", isDirectory: true) + Self.progress("snapshot-ready") + + var options = CostUsageScanner.Options( + codexSessionsRoot: sessions, + cacheRoot: cacheRoot, + codexLineageAccountingMode: .legacy, + forceRescan: true) + // A retained snapshot may be replayed, but scanner caches must never influence the result. + options.refreshMinIntervalSeconds = 0 + let since = try #require(ISO8601DateFormatter().date(from: "2026-07-05T00:00:00Z")) + let until = try #require(ISO8601DateFormatter().date(from: "2026-07-12T23:59:59Z")) + let legacyStarted = ContinuousClock.now + let legacyReport = try CostUsageScanner.loadDailyReportCancellable( + provider: .codex, + since: since, + until: until, + now: until, + options: options, + checkCancellation: nil) + let legacyDuration = legacyStarted.duration(to: .now) + let legacy = Dictionary(uniqueKeysWithValues: legacyReport.data.map { + ($0.date, ($0.inputTokens ?? 0) + ($0.outputTokens ?? 0)) + }) + let legacyCache = CostUsageCacheIO.load(provider: .codex, cacheRoot: cacheRoot) + let references = try Self.referenceTotals() + Self.progress("legacy-ready") + + let directModes: [CodexLineageAccountingMode] = switch ProcessInfo.processInfo + .environment["CODEXBAR_VALIDATE_SCANNER_MODES"] + { + case "shadow": [.shadow] + case "lineage": [.lineage] + case "all": [.shadow, .lineage] + default: [] + } + var directReports: [String: [String: Int]] = [:] + for mode in directModes { + let modeRoot = validationRoot.appendingPathComponent(mode.rawValue, isDirectory: true) + var modeOptions = CostUsageScanner.Options( + codexSessionsRoot: sessions, + cacheRoot: modeRoot, + codexLineageAccountingMode: mode, + forceRescan: true) + modeOptions.refreshMinIntervalSeconds = 0 + let report = try CostUsageScanner.loadDailyReportCancellable( + provider: .codex, + since: since, + until: until, + now: until, + options: modeOptions, + checkCancellation: nil) + directReports[mode.rawValue] = Dictionary(uniqueKeysWithValues: report.data.map { + ($0.date, ($0.inputTokens ?? 0) + ($0.outputTokens ?? 0)) + }) + } + + let lineageStarted = ContinuousClock.now + Self.progress("discovery-start") + let discovery = try CodexLineageTwoPassDiscovery.discover( + includedFiles: included, + roots: [sessions, archived]) + Self.progress("discovery-ready") + let families = try CodexLineageEngine.prepareDescriptorFamilies( + descriptors: discovery.descriptors, + unresolvedParents: discovery.unresolvedParents) + Self.progress("families-ready") + let lineage = try CodexLineageEngine.reconcileStreaming(families: families, localTimeZone: .gmt) + Self.progress("lineage-ready") + let lineageDuration = lineageStarted.duration(to: .now) + let resultsByID = Dictionary(uniqueKeysWithValues: lineage.families.map { ($0.stableID, $0) }) + var containmentReasons: [String: Int] = [:] + var containedObservationCount = 0 + for family in families { + guard let result = resultsByID[family.stableID], case let .contained(reasons) = result.quality else { + continue + } + containedObservationCount += family.observationCount + for reason in reasons { + containmentReasons[reason.rawValue, default: 0] += 1 + } + } + let containedFamilyCount = families.count { family in + guard let result = resultsByID[family.stableID] else { return false } + if case .contained = result.quality { + return true + } + return false + } + let selectableContainedFamilies = families + .compactMap { family -> CodexLineageAccountingSelector.ContainedFamily? in + guard let result = resultsByID[family.stableID], case .contained = result.quality else { return nil } + let documents = family.descriptors.compactMap { descriptor -> + CodexLineageAccountingSelector.ContainedDocument? in + guard let days = legacyCache.files[descriptor.fileURL.path]?.days else { return nil } + let identity = CostUsageScanner.codexContainedDocumentIdentity( + scopeID: descriptor.scopeID, + ownerID: descriptor.ownerID) + return .init(identity: identity, days: days) + } + return documents.count == family.descriptors.count ? .init(documents: documents) : nil + } + guard selectableContainedFamilies.count == containedFamilyCount else { + // Match the production selector's fail-closed behavior. A partial contained fallback + // would make the replay look better by silently dropping a family. + throw CodexLineageAccountingSelector.SelectionError.missingContainedFamilyEvidence + } + let selected = CodexLineageAccountingSelector.select( + mode: .lineage, + legacyDays: legacyCache.days, + primaryRows: lineage.report.utcRows, + containedFamilies: selectableContainedFamilies) + let primary = Self.tokensByDay(lineage.report.utcRows) + let selectedTokens = Self.tokensByDay(selected.days) + let contained = Dictionary(uniqueKeysWithValues: Self.referenceDays.map { day in + (day, max(0, (selectedTokens[day] ?? 0) - (primary[day] ?? 0))) + }) + + let samples = Self.referenceDays.map { day -> CodexLineageResidualClassifier.Sample in + let reference = references[day] ?? Reference(tokens: legacy[day] ?? 0, finalized: false) + return .init( + day: day, + referenceTokens: reference.tokens, + isReferenceFinalized: reference.finalized, + isOrdinaryDay: false, + legacyTokens: legacy[day] ?? 0, + ledgerUTCTokens: selectedTokens[day] ?? 0, + ledgerLocalTokens: selectedTokens[day] ?? 0, + evidence: .init( + // Date-filtered replay can prove referenced-parent closure, not full corpus + // exhaustiveness: unreferenced or deleted historical documents may be absent. + localCorpusWasExhaustive: false, + rejectedObservationCount: discovery.descriptors.reduce(0) { + $0 + $1.incompleteObservationCount + }, + unresolvedParentCount: discovery.unresolvedParents.count, + duplicateObservationCount: lineage.report.duplicateObservationCount)) + } + let classification = CodexLineageResidualClassifier.classify(samples: samples) + let ordinaryDivergenceCount = Self.ordinaryDays.count { day in + let legacyTokens = legacy[day] ?? 0 + guard legacyTokens > 0 else { return false } + return abs((selectedTokens[day] ?? 0) - legacyTokens) > Int(Double(legacyTokens) * 0.01) + } + + let output: [String: Any] = [ + "days": Self.referenceDays.map { day in + let result = classification.days.first { $0.day == day } + return [ + "day": day, + "legacy": legacy[day] ?? 0, + "primary": primary[day] ?? 0, + "contained": contained[day] ?? 0, + "selected": selectedTokens[day] ?? 0, + "shadow": directReports[CodexLineageAccountingMode.shadow.rawValue]?[day] ?? 0, + "scannerLineage": directReports[CodexLineageAccountingMode.lineage.rawValue]?[day] ?? 0, + "reference": references[day]?.tokens ?? 0, + "finalized": references[day]?.finalized ?? false, + "classification": result?.classification.rawValue ?? "missing", + ] as [String: Any] + }, + "ordinaryDays": Self.ordinaryDays.map { day in + [ + "day": day, + "legacy": legacy[day] ?? 0, + "selected": selectedTokens[day] ?? 0, + ] as [String: Any] + }, + "coverage": [ + "documents": discovery.descriptors.count, + "families": lineage.diagnostics.familyCount, + "containedFamilies": containedFamilyCount, + "selectableContainedFamilies": selectableContainedFamilies.count, + "containedObservations": containedObservationCount, + "containmentReasons": containmentReasons, + "referencedParents": discovery.referencedParentDocumentCount, + "unresolvedParents": discovery.unresolvedParents.count, + "observations": lineage.diagnostics.observationCount, + "peakFamilyObservations": lineage.diagnostics.peakFamilyObservationCount, + "duplicateObservations": lineage.report.duplicateObservationCount, + ], + "performance": [ + "legacyMilliseconds": Self.milliseconds(legacyDuration), + "lineageMilliseconds": Self.milliseconds(lineageDuration), + ], + "ordinaryDayDivergenceCount": ordinaryDivergenceCount, + "aggregateImproved": classification.improvesAggregateError, + // This replay is one validation artifact, not permission to remove the rollback path. + "supportsLegacyRemoval": false, + "legacyRemovalBlocker": "requires-reviewed-multi-run-promotion-evidence", + ] + let data = try JSONSerialization.data(withJSONObject: output, options: [.sortedKeys]) + let encoded = try #require(String(bytes: data, encoding: .utf8)) + print("CODEX_LINEAGE_VALIDATION " + encoded) + } + + // swiftlint:enable function_body_length + + private static let referenceDays = ["2026-07-09", "2026-07-10", "2026-07-11", "2026-07-12"] + private static let ordinaryDays = ["2026-07-05", "2026-07-06", "2026-07-07", "2026-07-08"] + private static let discoveryDays = Set(Self.referenceDays + Self.ordinaryDays + ["2026-07-04", "2026-07-13"]) + + /// Loads private account totals from an explicitly supplied, untracked JSON file. + /// Format: `{ "YYYY-MM-DD": { "tokens": 123, "finalized": true } }`. + private static func referenceTotals() throws -> [String: Reference] { + guard let path = ProcessInfo.processInfo.environment["CODEXBAR_LINEAGE_REFERENCE_TOTALS_FILE"] else { + return [:] + } + let data = try Data(contentsOf: URL(fileURLWithPath: path)) + guard let references = try? JSONDecoder().decode([String: Reference].self, from: data), + references.values.allSatisfy({ $0.tokens >= 0 }) + else { + throw ValidationError.invalidReferenceTotals + } + return references + } + + private static func rollouts(roots: [URL], days: Set) -> [URL] { + roots.flatMap { root -> [URL] in + guard let enumerator = FileManager.default.enumerator( + at: root, + includingPropertiesForKeys: [.isRegularFileKey], + options: [.skipsHiddenFiles, .skipsPackageDescendants]) + else { return [] } + return enumerator.compactMap { value -> URL? in + guard let url = value as? URL, url.pathExtension.lowercased() == "jsonl" else { return nil } + return days.contains(where: url.path.contains) ? url : nil + } + }.sorted { $0.path < $1.path } + } + + private static func extraValidationFiles(sourceHome: URL, snapshotHome: URL) throws -> [URL] { + guard let listPath = ProcessInfo.processInfo.environment["CODEXBAR_LINEAGE_EXTRA_FILE_LIST"], + let contents = try? String(contentsOfFile: listPath, encoding: .utf8) + else { return [] } + let canonicalSourceHome = sourceHome.standardizedFileURL.resolvingSymlinksInPath().path + return try contents.split(whereSeparator: \.isNewline).map { line in + let source = URL(fileURLWithPath: String(line)).standardizedFileURL.resolvingSymlinksInPath() + guard source.path.hasPrefix(canonicalSourceHome + "/") else { + throw ValidationError.extraFileOutsideCodexHome + } + let relative = source.path.dropFirst(canonicalSourceHome.count + 1) + guard relative.hasPrefix("sessions/") || relative.hasPrefix("archived_sessions/") else { + throw ValidationError.extraFileOutsideRolloutRoots + } + let snapshot = snapshotHome.appendingPathComponent(String(relative)).standardizedFileURL + guard FileManager.default.fileExists(atPath: snapshot.path) else { + throw ValidationError.extraFileMissingFromSnapshot + } + return snapshot + } + } + + private static func snapshotCodexHome(source: URL, destination: URL) throws { + for rootName in ["sessions", "archived_sessions"] { + let sourceRoot = source.appendingPathComponent(rootName, isDirectory: true) + let destinationRoot = destination.appendingPathComponent(rootName, isDirectory: true) + guard let enumerator = FileManager.default.enumerator( + at: sourceRoot, + includingPropertiesForKeys: [.isRegularFileKey], + options: [.skipsHiddenFiles, .skipsPackageDescendants]) + else { continue } + while let sourceFile = enumerator.nextObject() as? URL { + guard sourceFile.pathExtension.lowercased() == "jsonl" else { continue } + let relativePath = sourceFile.path.dropFirst(sourceRoot.path.count + 1) + let destinationFile = destinationRoot.appendingPathComponent(String(relativePath)) + try FileManager.default.createDirectory( + at: destinationFile.deletingLastPathComponent(), + withIntermediateDirectories: true) + try Self.cloneOrCopy(source: sourceFile, destination: destinationFile) + } + } + } + + private static func cloneOrCopy(source: URL, destination: URL) throws { + #if os(macOS) + if clonefile(source.path, destination.path, 0) == 0 { + return + } + #endif + try FileManager.default.copyItem(at: source, to: destination) + } + + private static func tokensByDay(_ rows: [CodexLineageLedger.DailyRow]) -> [String: Int] { + rows.reduce(into: [:]) { $0[$1.day, default: 0] += $1.totals.input + $1.totals.output } + } + + private static func tokensByDay(_ days: CodexLineageAccountingSelector.PackedDays) -> [String: Int] { + days.mapValues { models in models.values.reduce(0) { $0 + ($1[safe: 0] ?? 0) + ($1[safe: 2] ?? 0) } } + } + + private static func milliseconds(_ duration: Duration) -> Int64 { + let components = duration.components + return components.seconds * 1000 + Int64(components.attoseconds / 1_000_000_000_000_000) + } + + private static func progress(_ stage: String) { + print("CODEX_LINEAGE_STAGE " + stage) + fflush(stdout) + } +}