llm_cost_tracker 0.7.3 → 0.9.0

data/lib/llm_cost_tracker/capture/stream_collector.rb

@@ -2,29 +2,39 @@
 
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/object/deep_dup"
+require "json"
 
 require_relative "stream"
+require_relative "../pricing/mode"
+require_relative "../timing"
 
 module LlmCostTracker
   module Capture
     class StreamCollector
       attr_reader :provider
 
-      def initialize(provider:, model:, latency_ms: nil, provider_response_id: nil, pricing_mode: nil, metadata: {},
-                     context_tags: nil)
+      def initialize(provider:, model:, latency_ms: nil, provider_response_id: nil, provider_project_id: nil,
+                     provider_api_key_id: nil, provider_workspace_id: nil, batch: nil, pricing_mode: nil,
+                     metadata: {}, context_tags: nil, request: nil)
         @provider = provider.to_s
         @model = model
         @latency_ms = latency_ms
         @provider_response_id = provider_response_id
+        @provider_project_id = provider_project_id
+        @provider_api_key_id = provider_api_key_id
+        @provider_workspace_id = provider_workspace_id
+        @batch = batch
         @pricing_mode = pricing_mode
         @metadata = (metadata || {}).deep_dup
         @context_tags = (context_tags || LlmCostTracker::Tags::Context.tags).deep_dup
+        @request = request
         @events = []
         @captured_bytes = 0
         @overflowed = false
         @explicit_usage = nil
-        @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @started_at = LlmCostTracker::Timing.now_monotonic
         @finished = false
+        @recording = false
         @mutex = Mutex.new
       end
 
@@ -66,19 +76,35 @@ module LlmCostTracker
         @mutex.synchronize do
           ensure_open!
           @provider_response_id = extra.delete(:provider_response_id) || @provider_response_id
-          @explicit_usage = TokenUsage.from_hash(extra.merge(
-                                                   input_tokens: input_tokens.to_i,
-                                                   output_tokens: output_tokens.to_i
-                                                 ))
+          @provider_project_id = extra.delete(:provider_project_id) || @provider_project_id
+          @provider_api_key_id = extra.delete(:provider_api_key_id) || @provider_api_key_id
+          @provider_workspace_id = extra.delete(:provider_workspace_id) || @provider_workspace_id
+          batch = extra.delete(:batch)
+          @batch = batch unless batch.nil?
+          @explicit_usage = TokenUsage.build(
+            **extra.slice(*TokenUsage.members),
+            input_tokens: input_tokens,
+            output_tokens: output_tokens
+          )
         end
         self
       end
 
       def finish!(errored: false)
-        snapshot = @mutex.synchronize do
-          return if @finished
+        snapshot = claim_recording_slot
+        return if snapshot.nil?
 
-          @finished = true
+        record_snapshot(snapshot, errored: errored)
+      end
+
+      private
+
+      def claim_recording_slot
+        @mutex.synchronize do
+          return nil if @finished || @recording
+
+          @recording = true
+          pricing_mode = Pricing.normalize_mode(@pricing_mode)
           {
             events: @events.dup,
             overflowed: @overflowed,
@@ -86,27 +112,65 @@ module LlmCostTracker
             model: @model,
             latency_ms: @latency_ms,
             provider_response_id: @provider_response_id,
-            pricing_mode: @pricing_mode,
+            capture_dimensions: capture_dimensions(pricing_mode),
+            pricing_mode: pricing_mode,
             metadata: @metadata.deep_dup,
-            context_tags: @context_tags.deep_dup
+            context_tags: @context_tags.deep_dup,
+            request: @request
           }
         end
+      end
+
+      def record_snapshot(snapshot, errored:)
+        save_succeeded = false
+        begin
+          capture = build_usage_capture(snapshot)
+          provider_response_id = capture.provider_response_id || snapshot[:provider_response_id]
+          capture = capture.with(provider_response_id: provider_response_id)
+
+          Tracker.record(
+            capture: capture,
+            latency_ms: snapshot[:latency_ms] || LlmCostTracker::Timing.elapsed_ms(@started_at),
+            pricing_mode: pricing_mode_for(capture: capture, snapshot: snapshot),
+            metadata: (errored ? { stream_errored: true } : {}).merge(snapshot[:metadata]),
+            context_tags: snapshot[:context_tags]
+          ) { |stage| save_succeeded = true if stage == :after_save }
+        ensure
+          @mutex.synchronize do
+            @finished = save_succeeded
+            @recording = false
+          end
+        end
+      end
 
-        capture = build_usage_capture(snapshot)
-        provider_response_id = capture.provider_response_id || snapshot[:provider_response_id]
-        capture = capture.with(provider_response_id: provider_response_id)
+      HOST_DERIVED_MODE_TOKENS = %i[data_residency].freeze
+      STANDARD_LIKE_MODE_TOKENS = %i[standard standard_only auto default].freeze
+      private_constant :HOST_DERIVED_MODE_TOKENS, :STANDARD_LIKE_MODE_TOKENS
 
-        Tracker.record(
-          capture: capture,
-          latency_ms: snapshot[:latency_ms] ||
-            ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at) * 1000).round,
-          pricing_mode: snapshot[:pricing_mode],
-          metadata: (errored ? { stream_errored: true } : {}).merge(snapshot[:metadata]),
-          context_tags: snapshot[:context_tags]
-        )
+      def pricing_mode_for(capture:, snapshot:)
+        merge_pricing_modes(capture.pricing_mode, snapshot[:pricing_mode])
       end
 
-      private
+      def merge_pricing_modes(provider_mode, request_mode)
+        return Pricing.normalize_mode(request_mode) if provider_mode.to_s.strip.empty?
+
+        provider_tokens = Pricing::Mode.tokenize(provider_mode) - STANDARD_LIKE_MODE_TOKENS
+        request_host_tokens = Pricing::Mode.tokenize(request_mode || "") & HOST_DERIVED_MODE_TOKENS
+        combined = provider_tokens | request_host_tokens
+        return nil if combined.empty?
+
+        Pricing.normalize_mode(combined.join("_"))
+      end
+
+      def capture_dimensions(pricing_mode)
+        batch = @batch.nil? ? UsageCapture.batch_from_pricing_mode?(pricing_mode).presence : @batch
+        {
+          provider_project_id: @provider_project_id.to_s.strip.presence,
+          provider_api_key_id: @provider_api_key_id.to_s.strip.presence,
+          provider_workspace_id: @provider_workspace_id.to_s.strip.presence,
+          batch: batch
+        }.compact
+      end
 
       def ensure_open!
         return unless @finished
@@ -120,16 +184,25 @@ module LlmCostTracker
 
         capture = Parsers.find_for_provider(@provider)&.parse_stream(
           response_status: 200,
-          events: snapshot[:events]
+          events: snapshot[:events],
+          request_body: request_body_for(snapshot[:request])
         )
         if capture
           model = present_model(capture.model) || present_model(snapshot[:model]) || UsageCapture::UNKNOWN_MODEL
-          return capture.with(provider: @provider, model: model)
+          return capture.with(provider: @provider, model: model, **snapshot.fetch(:capture_dimensions))
         end
 
         build_unknown_usage(snapshot)
       end
 
+      def request_body_for(request)
+        return nil unless request
+
+        JSON.generate(request)
+      rescue StandardError
+        nil
+      end
+
       def present_model(value)
         return nil if value.nil?
 
@@ -145,7 +218,9 @@ module LlmCostTracker
           model: snapshot[:model] || UsageCapture::UNKNOWN_MODEL,
           token_usage: snapshot[:explicit_usage],
           stream: true,
-          usage_source: :manual
+          usage_source: :manual,
+          pricing_mode: snapshot[:pricing_mode],
+          **snapshot.fetch(:capture_dimensions)
         )
       end
 
@@ -155,33 +230,45 @@ module LlmCostTracker
           model: snapshot[:model] || UsageCapture::UNKNOWN_MODEL,
           token_usage: TokenUsage.build(input_tokens: 0, output_tokens: 0, total_tokens: 0),
           stream: true,
-          usage_source: :unknown
+          usage_source: :unknown,
+          pricing_mode: snapshot[:pricing_mode],
+          **snapshot.fetch(:capture_dimensions)
         )
       end
 
+      IGNORED_PAYLOAD_KEYS = %w[b64_json partial_image_b64].freeze
+      private_constant :IGNORED_PAYLOAD_KEYS
+
+      HEAVY_STRING_BYTES = 8 * 1024
+      private_constant :HEAVY_STRING_BYTES
+
       def capture_event(data, type:)
-        size = type.to_s.bytesize + estimated_bytes(data) + 32
+        event = { event: type, data: strip_heavy_payload(data) }
+        size = JSON.generate(event).bytesize
         if @captured_bytes + size <= Capture::Stream::LIMIT_BYTES
-          @events << { event: type, data: data.deep_dup }
+          @events << event.deep_dup
           @captured_bytes += size
         else
           @overflowed = true
-          @events.clear
         end
+      rescue JSON::JSONError, TypeError, SystemStackError
+        @overflowed = true
       end
 
-      def estimated_bytes(value)
+      def strip_heavy_payload(value)
         case value
         when Hash
-          value.sum { |key, nested| estimated_bytes(key) + estimated_bytes(nested) + 4 }
+          value.each_with_object({}) do |(key, nested), out|
+            next if IGNORED_PAYLOAD_KEYS.include?(key.to_s)
+
+            out[key] = strip_heavy_payload(nested)
+          end
         when Array
-          value.sum { |nested| estimated_bytes(nested) + 2 }
+          value.map { |nested| strip_heavy_payload(nested) }
         when String
-          value.bytesize + 2
-        when Numeric, true, false, nil
-          value.to_s.bytesize
+          value.bytesize > HEAVY_STRING_BYTES ? "" : value
         else
-          value.to_s.bytesize + 2
+          value
         end
       end
     end

data/lib/llm_cost_tracker/capture/stream_tracker.rb

@@ -12,8 +12,9 @@ module LlmCostTracker
         @stream = stream
         @collector = collector
         @active = active
-        @finish = finish || proc { |errored:| @collector.finish!(errored: errored) }
-        @finished = false
+        @finish = finish || proc { |errored| collector.finish!(errored: errored) }
+        @finished_ref = [false]
+        @attempted_ref = [false]
         @capture_failed = false
         @mutex = Mutex.new
       end
@@ -33,6 +34,7 @@ module LlmCostTracker
         end
         wrap_each if !iterator_wrapped && @stream.respond_to?(:each)
 
+        register_orphan_finalizer
         @stream
       rescue StandardError => e
         Logging.warn("stream integration failed to install wrapper: #{e.class}: #{e.message}")
@@ -120,14 +122,47 @@ module LlmCostTracker
 
       def finish!(errored:)
         should_finish = @mutex.synchronize do
-          next false if @finished
+          @attempted_ref[0] = true
+          next false if @finished_ref[0]
 
-          @finished = true
+          @finished_ref[0] = true
           true
         end
         return unless should_finish && @active.call
 
-        @finish.call(errored: errored)
+        begin
+          @finish.call(errored)
+        rescue StandardError
+          @mutex.synchronize { @finished_ref[0] = false }
+          raise
+        end
+      end
+
+      def register_orphan_finalizer
+        finished_ref = @finished_ref
+        attempted_ref = @attempted_ref
+        finish_proc = @finish
+        active_proc = @active
+        mutex = @mutex
+        finalizer = lambda do |_object_id|
+          should_finish = mutex.synchronize do
+            next false if finished_ref[0] || attempted_ref[0]
+
+            finished_ref[0] = true
+            attempted_ref[0] = true
+            true
+          end
+          next unless should_finish && active_proc.call
+
+          begin
+            finish_proc.call(false)
+          rescue StandardError
+            nil
+          end
+        end
+        ObjectSpace.define_finalizer(@stream, finalizer)
+      rescue TypeError, ArgumentError
+        nil
       end
     end
   end

data/lib/llm_cost_tracker/configuration.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "pricing/registry"
 require_relative "tags/key"
-require_relative "configuration/instrumentation"
 
 module LlmCostTracker
   class Configuration
-    include ConfigurationInstrumentation
-
     OPENAI_COMPATIBLE_PROVIDERS = {
       "openrouter.ai" => "openrouter",
       "api.deepseek.com" => "deepseek",
@@ -16,8 +14,8 @@ module LlmCostTracker
 
     BUDGET_EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
     UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
-    SHARED_SCALAR_ATTRIBUTES = %i[enabled on_budget_exceeded monthly_budget daily_budget per_call_budget log_level
-                                  prices_file max_tag_count max_tag_value_bytesize].freeze
+    SHARED_SCALAR_ATTRIBUTES = %i[enabled default_tags on_budget_exceeded monthly_budget daily_budget per_call_budget
+                                  log_level prices_file max_tag_count max_tag_value_bytesize].freeze
     SHARED_ENUM_ATTRIBUTES = {
       budget_exceeded_behavior: [BUDGET_EXCEEDED_BEHAVIORS, :notify],
       unknown_pricing_behavior: [UNKNOWN_PRICING_BEHAVIORS, :warn]
@@ -27,13 +25,17 @@ module LlmCostTracker
     attr_reader(
       *SHARED_SCALAR_ATTRIBUTES,
       :budget_exceeded_behavior,
-      :default_tags,
-      :pricing_overrides,
+      :durable_ingestion,
       :instrumented_integrations,
+      :pricing_overrides,
       :report_tag_breakdowns,
       :redacted_tag_keys,
       :unknown_pricing_behavior,
-      :openai_compatible_providers
+      :openai_compatible_providers,
+      :reconciliation_importers,
+      :reconciliation_enabled,
+      :auto_enable_stream_usage,
+      :cache_rollups
     )
 
     def initialize
@@ -49,19 +51,61 @@ module LlmCostTracker
       @prices_file        = nil
       @max_tag_count      = 50
       @max_tag_value_bytesize = 1024
-      @pricing_overrides = {}
-      @instrumented_integrations = []
+      self.pricing_overrides = {}
+      @instrumented_integrations = Set.new
       @report_tag_breakdowns = []
       @redacted_tag_keys = DEFAULT_REDACTED_TAG_KEYS.dup
       self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
+      @reconciliation_importers = {}
+      @reconciliation_enabled = false
+      @auto_enable_stream_usage = true
+      @durable_ingestion = false
+      @cache_rollups = false
       @finalized = false
     end
 
-    def default_tags=(value)
+    def durable_ingestion=(value)
+      ensure_shared_configuration_mutable!
+      @durable_ingestion = value
+    end
+
+    def cache_rollups=(value)
+      ensure_shared_configuration_mutable!
+      @cache_rollups = value
+    end
+
+    def reconciliation_enabled=(value)
       ensure_shared_configuration_mutable!
-      @default_tags = value
+      @reconciliation_enabled = value
     end
 
+    def auto_enable_stream_usage=(value)
+      ensure_shared_configuration_mutable!
+      @auto_enable_stream_usage = value
+    end
+
+    def reconciliation_importers=(importers)
+      ensure_shared_configuration_mutable!
+      raise Error, RECONCILIATION_DISABLED_MESSAGE unless @reconciliation_enabled
+
+      @reconciliation_importers = (importers || {}).to_h do |source, importer|
+        raise Error, "reconciliation_importers[#{source}] must respond to call" unless importer.respond_to?(:call)
+
+        [source.to_sym, importer]
+      end
+    end
+
+    def register_reconciliation_importer(source, &block)
+      ensure_shared_configuration_mutable!
+      raise Error, RECONCILIATION_DISABLED_MESSAGE unless @reconciliation_enabled
+      raise Error, "register_reconciliation_importer requires a block" unless block
+
+      @reconciliation_importers[source.to_sym] = block
+    end
+
+    RECONCILIATION_DISABLED_MESSAGE = "reconciliation is disabled; set config.reconciliation_enabled = true first"
+    private_constant :RECONCILIATION_DISABLED_MESSAGE
+
     def openai_compatible_providers=(providers)
       ensure_shared_configuration_mutable!
       @openai_compatible_providers = normalize_openai_compatible_providers(providers)
@@ -69,7 +113,9 @@ module LlmCostTracker
 
     def pricing_overrides=(value)
       ensure_shared_configuration_mutable!
-      @pricing_overrides = value
+      @pricing_overrides = Pricing::Registry.normalize_price_table(value || {})
+    rescue ArgumentError => e
+      raise Error, "invalid pricing_overrides: #{e.message}"
     end
 
     def report_tag_breakdowns=(value)
@@ -82,6 +128,15 @@ module LlmCostTracker
       @redacted_tag_keys = Array(value).map(&:to_s)
     end
 
+    def instrument(*names)
+      ensure_shared_configuration_mutable!
+      @instrumented_integrations.merge(normalize_instrumentation_names(names))
+    end
+
+    def instrumented?(name)
+      @instrumented_integrations.include?(name)
+    end
+
     SHARED_SCALAR_ATTRIBUTES.each do |name|
       define_method("#{name}=") do |value|
         ensure_shared_configuration_mutable!
@@ -99,10 +154,12 @@ module LlmCostTracker
     def finalize!
       @default_tags = deep_freeze(@default_tags || {})
       @pricing_overrides = deep_freeze(@pricing_overrides || {})
-      @instrumented_integrations = deep_freeze(@instrumented_integrations || [])
+      @instrumented_integrations = deep_freeze(@instrumented_integrations || Set.new)
       @report_tag_breakdowns = deep_freeze(Array(@report_tag_breakdowns))
       @redacted_tag_keys = deep_freeze(Array(@redacted_tag_keys))
-      @openai_compatible_providers = deep_freeze(@openai_compatible_providers || {})
+      @openai_compatible_providers = deep_freeze(
+        normalize_openai_compatible_providers(@openai_compatible_providers)
+      )
       @finalized = true
       self
     end
@@ -115,7 +172,6 @@ module LlmCostTracker
 
     def normalize_enum(name, value, allowed, default:)
       value = default if value.nil?
-      value = value.to_sym
       return value if allowed.include?(value)
 
       raise Error, "Unknown #{name}: #{value.inspect}. Use one of: #{allowed.join(', ')}"
@@ -127,6 +183,19 @@ module LlmCostTracker
       end
     end
 
+    def normalize_instrumentation_names(names)
+      names = names.flatten
+      integrations = Integrations.names
+      return integrations if names == [:all]
+
+      names.each do |name|
+        next if integrations.include?(name)
+
+        raise Error, "Unknown integration: #{name.inspect}. Use one of: #{integrations.join(', ')}"
+      end
+      names
+    end
+
     def ensure_shared_configuration_mutable!
       return unless finalized?
 
@@ -141,7 +210,7 @@ module LlmCostTracker
           deep_freeze(nested_value)
         end
         value.frozen? ? value : value.freeze
-      when Array
+      when Array, Set
         value.each { |nested_value| deep_freeze(nested_value) }
         value.frozen? ? value : value.freeze
       when String

data/lib/llm_cost_tracker/dashboard_setup_state.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "ledger/schema/calls"
+require_relative "ledger/schema/call_line_items"
+require_relative "ledger/schema/call_tags"
+require_relative "ledger/schema/call_rollups"
+
+module LlmCostTracker
+  module DashboardSetupState
+    SetupRequired = Data.define(:message, :details)
+    DOCS_HINT = "See docs/upgrading.md for the migration path."
+    MUTEX = Mutex.new
+
+    CORE_SCHEMA_CHECKS = [
+      [
+        LlmCostTracker::Ledger::Schema::Calls,
+        "The llm_cost_tracker_calls table does not match the current LLM Cost Tracker schema."
+      ],
+      [
+        LlmCostTracker::Ledger::Schema::CallLineItems,
+        "The llm_cost_tracker_call_line_items table does not match the current LLM Cost Tracker schema."
+      ],
+      [
+        LlmCostTracker::Ledger::Schema::CallTags,
+        "The llm_cost_tracker_call_tags table does not match the current LLM Cost Tracker schema."
+      ]
+    ].freeze
+
+    OPTIONAL_CALL_ROLLUPS_CHECK = [
+      LlmCostTracker::Ledger::Schema::CallRollups,
+      "The llm_cost_tracker_call_rollups table does not match the current LLM Cost Tracker schema."
+    ].freeze
+
+    private_constant :MUTEX, :CORE_SCHEMA_CHECKS, :OPTIONAL_CALL_ROLLUPS_CHECK, :DOCS_HINT
+
+    class << self
+      def current
+        return @cached if defined?(@cached)
+
+        MUTEX.synchronize do
+          @cached = compute unless defined?(@cached)
+        end
+        @cached
+      end
+
+      def reset!
+        MUTEX.synchronize do
+          remove_instance_variable(:@cached) if defined?(@cached)
+        end
+      end
+
+      private
+
+      def compute
+        LlmCostTracker::Logging.debug("DashboardSetupState recomputing")
+        return calls_table_missing unless LlmCostTracker::Call.table_exists?
+
+        core_drift = drift_in(schema_checks_for_current_config)
+        return core_drift if core_drift
+        return nil unless LlmCostTracker.reconciliation_enabled?
+
+        reconciliation_drift
+      end
+
+      def schema_checks_for_current_config
+        return CORE_SCHEMA_CHECKS unless LlmCostTracker.configuration.cache_rollups
+
+        CORE_SCHEMA_CHECKS + [OPTIONAL_CALL_ROLLUPS_CHECK]
+      end
+
+      def drift_in(checks)
+        checks.each do |schema, message|
+          errors = schema.current_schema_errors
+          next if errors.empty?
+
+          return SetupRequired.new(message: message, details: errors + [DOCS_HINT])
+        end
+        nil
+      end
+
+      def reconciliation_drift
+        LlmCostTracker.const_get(:Reconciliation) # autoload reconciliation + its ledger schemas
+        connection = ActiveRecord::Base.connection
+        LlmCostTracker::Reconciliation::SCHEMA_TABLES.each do |schema, table|
+          unless connection.data_source_exists?(table)
+            return SetupRequired.new(
+              message: "The #{table} table is required when reconciliation is enabled.",
+              details: ["run bin/rails generate llm_cost_tracker:reconciliation && bin/rails db:migrate", DOCS_HINT]
+            )
+          end
+
+          errors = schema.current_schema_errors
+          next if errors.empty?
+
+          message = "The #{table} table does not match the current LLM Cost Tracker schema."
+          return SetupRequired.new(message: message, details: errors + [DOCS_HINT])
+        end
+        nil
+      end
+
+      def calls_table_missing
+        SetupRequired.new(
+          message: "The llm_cost_tracker_calls table is not available yet.",
+          details: nil
+        )
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/doctor/cost_drift_check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+require_relative "check"
+require_relative "probe"
+require_relative "../ledger/rollups"
+
+module LlmCostTracker
+  class Doctor
+    class CostDriftCheck
+      SAMPLE_SIZE = 200
+      EPSILON = BigDecimal("0.00000001")
+
+      def call
+        return unless Probe.table_exists?("llm_cost_tracker_calls")
+        return unless Probe.table_exists?("llm_cost_tracker_call_line_items")
+
+        sampled = LlmCostTracker::Call
+                  .where.not(total_cost: nil)
+                  .where(cost_status: %w[complete free partial])
+                  .order(id: :desc)
+                  .limit(SAMPLE_SIZE)
+                  .pluck(:id, :total_cost, :cost_status)
+        return Check.new(:ok, "cost drift", "no priced calls to inspect") if sampled.empty?
+
+        line_item_totals = LlmCostTracker::CallLineItem
+                           .where(llm_cost_tracker_call_id: sampled.map(&:first))
+                           .where(currency: Ledger::Rollups::DEFAULT_CURRENCY)
+                           .group(:llm_cost_tracker_call_id)
+                           .sum(:cost)
+
+        drifted = sampled.filter_map do |id, total_cost, cost_status|
+          line_total = line_item_totals[id] || BigDecimal("0")
+          header = BigDecimal(total_cost.to_s)
+          next if cost_status == "partial" && header >= line_total
+          next if (header - line_total).abs <= EPSILON
+
+          "##{id}: header=#{header.to_s('F')} line_items=#{line_total.to_s('F')}"
+        end
+
+        if drifted.empty?
+          return Check.new(:ok, "cost drift",
+                           "header total_cost matches line items in #{sampled.size} sampled calls")
+        end
+
+        Check.new(
+          :warn,
+          "cost drift",
+          "header total_cost diverges from line items in #{drifted.size}/#{sampled.size} sampled calls: " \
+          "#{drifted.first(5).join('; ')}#{'; ...' if drifted.size > 5}"
+        )
+      end
+    end
+  end
+end