fix(gatekeeper): justify China API provider-specific cost constructs

After rebasing the China API models.dev pricing work, ProviderArchitectureGatekeeperTests failed because new provider-specific branches (Alibaba, Zai, DeepSeek) appeared in shared cost code and existing allowlist anchors shifted. Add '// Provider-specific by design:' markers at each provider-owned dispatch point, update the gatekeeper's hardcoded supportsTokenSnapshot set and shifted suppressed references, and remove obsolete CostUsageFetcher/PiSessionCostScanner allowlist entries whose anchors no longer match.

Closes provider-architecture gatekeeper failures on the China API rebase.

Author: joeVenner

Sources/CodexBarCore/CostUsageFetcher.swift

@@ -539,6 +539,7 @@ public struct CostUsageFetcher: Sendable {
             var sessions: [CostUsageSessionBreakdown] = []
             var piDaily: CostUsageDailyReport?
             var staleSnapshotUpdatedAt: Date?
+            // Provider-specific by design: only Codex builds project and session breakdowns from its local cache.
             if provider == .codex {
                 let roots = CostUsageScanner.codexSessionsRoots(options: options.scanOptions)
                 let cache = CostUsageScanner.codexCache(
@@ -579,6 +580,7 @@ public struct CostUsageFetcher: Sendable {
                     options: options.piOptions,
                     checkCancellation: checkCancellation)
                 try checkCancellation()
+                // Provider-specific by design: only Codex stores the Pi-only report for project merge.
                 if provider == .codex {
                     piDaily = piReport
                 }
@@ -647,6 +649,7 @@ public struct CostUsageFetcher: Sendable {
         let unknownModelIDs = Set(daily.data.flatMap { entry in
             entry.modelBreakdowns?.compactMap { breakdown -> String? in
                 guard breakdown.costUSD == nil else { return nil }
+                // Provider-specific by design: only Codex filters out its own unattributed model names.
                 if provider == .codex,
                    CostUsagePricing.isCodexUnattributedModel(breakdown.modelName)
                 {
@@ -1346,6 +1349,7 @@ extension CostUsageFetcher {
         includePiSessions: Bool,
         codexHomePath: String?) -> Bool
     {
+        // Provider-specific by design: Pi session mirrors exist only for the China API group, Claude, and Codex.
         let scopedCodexHomePath = codexHomePath?.trimmingCharacters(in: .whitespacesAndNewlines)
         let shouldMergePiUsage = provider != .codex || scopedCodexHomePath?.isEmpty != false
         return includePiSessions
@@ -1402,6 +1406,7 @@ extension CostUsageFetcher {
         }
 
         #if os(macOS)
+        // Provider-specific by design: Cursor remote snapshots use its macOS dashboard session.
         if provider == .cursor {
             return try await self.loadCursorTokenSnapshot(
                 now: now,

Sources/CodexBarCore/PiSessionCostScanner.swift

@@ -248,6 +248,7 @@ enum PiSessionCostScanner {
 
     private static func pricingContext(now: Date, cacheRoot: URL?) -> ModelsDevPricingContext {
         let modelsDevArtifact = ModelsDevCache.load(now: now, cacheRoot: cacheRoot).artifact
+        // Provider-specific by design: Pi pricing pulls models.dev catalogs only for the supported vendors.
         return ModelsDevPricingContext(
             catalog: modelsDevArtifact?.catalog,
             cacheRoot: cacheRoot,
@@ -840,6 +841,7 @@ enum PiSessionCostScanner {
         pricingDate: Date? = nil,
         pricingContext: ModelsDevPricingContext? = nil) -> Double?
     {
+        // Provider-specific by design: Pi cost calculation uses Codex/Claude-specific pricing normalizers.
         switch provider {
         case .codex:
             // Pi records input, cache reads, and cache writes as disjoint counts. Codex pricing
@@ -892,6 +894,7 @@ enum PiSessionCostScanner {
 
 extension PiSessionCostScanner {
     private static func mappedProvider(fromPiProvider provider: String) -> UsageProvider? {
+        // Provider-specific by design: Pi provider strings map to their respective UsageProvider values.
         switch provider.lowercased() {
         case "openai-codex":
             .codex

Sources/CodexBarCore/Vendored/CostUsage/CostUsagePricing.swift

@@ -785,6 +785,7 @@ enum CostUsagePricing {
     }
 
     private static func modelsDevProviderIDs(for provider: UsageProvider) -> [String] {
+        // Provider-specific by design: each supported provider maps to its own models.dev catalog IDs.
         switch provider {
         case .codex, .openai, .azureopenai:
             [self.codexModelsDevProviderID]

Tests/CodexBarTests/ProviderArchitectureGatekeeperTests.swift

@@ -201,11 +201,11 @@ struct ProviderArchitectureGatekeeperTests {
         ])
         #if os(macOS)
         #expect(Set(descriptors.filter(\.tokenCost.supportsTokenSnapshot).map(\.id)) == [
-            .codex, .claude, .cursor, .vertexai, .bedrock,
+            .codex, .claude, .cursor, .vertexai, .bedrock, .alibaba, .alibabatokenplan, .deepseek, .zai,
         ])
         #else
         #expect(Set(descriptors.filter(\.tokenCost.supportsTokenSnapshot).map(\.id)) == [
-            .codex, .claude, .vertexai, .bedrock,
+            .codex, .claude, .vertexai, .bedrock, .alibaba, .alibabatokenplan, .deepseek, .zai,
         ])
         #endif
         #expect(Set(descriptors.filter { $0.cli.binaryLocator != nil }.map(\.id)) == [
@@ -1353,19 +1353,19 @@ struct ProviderArchitectureGatekeeperTests {
             reason: "This provider-specific core branch passes its already-selected identity to a shared helper."),
         SuppressedProviderReference(
             path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 715,
+            line: 723,
             anchor: "provider: .codex,",
             expectedProviderIDs: ["codex"],
             reason: "This provider-specific core branch passes its already-selected identity to a shared helper."),
         SuppressedProviderReference(
             path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 790,
+            line: 798,
             anchor: "provider: .codex,",
             expectedProviderIDs: ["codex"],
             reason: "This provider-specific core branch passes its already-selected identity to a shared helper."),
         SuppressedProviderReference(
             path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 865,
+            line: 873,
             anchor: "provider: .codex,",
             expectedProviderIDs: ["codex"],
             reason: "This provider-specific core branch passes its already-selected identity to a shared helper."),
@@ -3360,54 +3360,6 @@ struct ProviderArchitectureGatekeeperTests {
             expectedReferenceCount: 1,
             expectedReferenceFingerprint: ["alibabatokenplan@0"],
             reason: "This exact shared construct dispatches a provider-owned capability at the generic integration boundary."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 539,
-            anchor: "if provider == .codex {",
-            expectedProviderIDs: ["codex"],
-            expectedReferenceCount: 1,
-            expectedReferenceFingerprint: ["codex@0"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 567,
-            anchor: "provider == .claude || (provider == .codex && options.shouldMergePiUsage)",
-            expectedProviderIDs: ["claude", "codex"],
-            expectedReferenceCount: 5,
-            expectedReferenceFingerprint: ["claude@0", "codex@0", "codex@10", "codex@15", "codex@27"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 614,
-            anchor: "options.provider == .codex || options.provider == .claude",
-            expectedProviderIDs: ["claude", "codex"],
-            expectedReferenceCount: 2,
-            expectedReferenceFingerprint: ["claude@0", "codex@0"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 641,
-            anchor: "guard provider == .codex || provider == .claude else { return nil }",
-            expectedProviderIDs: ["claude", "codex", "openai"],
-            expectedReferenceCount: 5,
-            expectedReferenceFingerprint: ["claude@0", "codex@0", "codex@4", "codex@15", "openai@15"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 1114,
-            anchor: "if provider == .vertexai {",
-            expectedProviderIDs: ["claude", "vertexai"],
-            expectedReferenceCount: 2,
-            expectedReferenceFingerprint: ["vertexai@0", "claude@2"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/CostUsageFetcher.swift",
-            line: 1365,
-            anchor: "if provider == .cursor {",
-            expectedProviderIDs: ["cursor"],
-            expectedReferenceCount: 1,
-            expectedReferenceFingerprint: ["cursor@0"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
         AllowedProviderConstruct(
             path: "Sources/CodexBarCore/LocalAgentSessionScanner.swift",
             line: 93,
@@ -3456,38 +3408,6 @@ struct ProviderArchitectureGatekeeperTests {
             expectedReferenceCount: 1,
             expectedReferenceFingerprint: ["codex@0"],
             reason: "This exact shared construct dispatches a provider-owned capability at the generic integration boundary."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/PiSessionCostScanner.swift",
-            line: 228,
-            anchor: "guard provider == .codex || provider == .claude else { return nil }",
-            expectedProviderIDs: ["claude", "codex"],
-            expectedReferenceCount: 2,
-            expectedReferenceFingerprint: ["claude@0", "codex@0"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/PiSessionCostScanner.swift",
-            line: 259,
-            anchor: "modelsDevProviderIDs: [\"anthropic\", \"openai\"]))",
-            expectedProviderIDs: ["openai"],
-            expectedReferenceCount: 1,
-            expectedReferenceFingerprint: ["openai@0"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/PiSessionCostScanner.swift",
-            line: 834,
-            anchor: "case .codex:",
-            expectedProviderIDs: ["claude", "codex"],
-            expectedReferenceCount: 2,
-            expectedReferenceFingerprint: ["codex@0", "claude@12"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
-        AllowedProviderConstruct(
-            path: "Sources/CodexBarCore/PiSessionCostScanner.swift",
-            line: 883,
-            anchor: ".codex",
-            expectedProviderIDs: ["claude", "codex"],
-            expectedReferenceCount: 2,
-            expectedReferenceFingerprint: ["codex@0", "claude@2"],
-            reason: "This exact cost scanner dispatch selects a provider-owned transcript, cache, or pricing format."),
         AllowedProviderConstruct(
             path: "Sources/CodexBarCore/ProviderEndpointOverrideValidator.swift",
             line: 9,