llm_cost_tracker 0.14.1 → 0.15.0

data/lib/llm_cost_tracker/capture/stream_tracker.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require "active_support/core_ext/object/deep_dup"
-require "active_support/core_ext/object/try"
-
-require_relative "sdk_payload"
-
 module LlmCostTracker
   module Capture
     class StreamTracker
@@ -21,23 +16,12 @@ module LlmCostTracker
       def wrap
         return @stream unless @stream
 
-        iterator_wrapped = false
-        if @stream.instance_variable_defined?(:@iterator)
-          iterator = @stream.instance_variable_get(:@iterator)
-          if iterator.respond_to?(:each)
-            @stream.instance_variable_set(:@iterator,
-                                          Enumerator.new do |yielder|
-                                            each_from(iterator) { |event| yielder << event }
-                                          end)
-            iterator_wrapped = true
-          end
-        end
-        each_wrapped = false
-        if !iterator_wrapped && @stream.respond_to?(:each)
+        iterator = @stream.instance_variable_get(:@iterator)
+        if iterator.respond_to?(:each)
+          wrap_iterator(iterator)
+        elsif @stream.respond_to?(:each)
           wrap_each
-          each_wrapped = true
-        end
-        unless iterator_wrapped || each_wrapped
+        else
           Logging.warn(
             "stream integration found no wrappable iterator on #{@stream.class} " \
             "(missing both `@iterator` ivar and `#each`); usage will not be captured"
@@ -52,30 +36,40 @@ module LlmCostTracker
 
       private
 
+      def wrap_iterator(iterator)
+        relayed = Enumerator.new { |yielder| relay(iterator.method(:each)) { |event| yielder << event } }
+        @stream.instance_variable_set(:@iterator, relayed)
+        close_through(iterator) if @stream.respond_to?(:close)
+      end
+
+      def close_through(iterator)
+        close = @stream.method(:close)
+        finish = method(:finish!)
+        @stream.define_singleton_method(:close) do
+          @iterator = iterator
+          close.call
+        ensure
+          finish.call(errored: false)
+        end
+      end
+
       def wrap_each
-        tracker = self
         original_each = @stream.method(:each)
+        relayed_each = ->(&block) { relay(original_each, &block) }
         @stream.define_singleton_method(:each) do |&block|
           next enum_for(:each) unless block
 
-          tracker.__send__(:each_from, original_each, &block)
+          relayed_each.call(&block)
         end
       end
 
-      def each_from(iterable)
+      def relay(source)
         errored = false
-        if iterable.respond_to?(:each)
-          iterable.each do |event|
-            capture(event)
-            yield event
-          end
-        else
-          iterable.call do |event|
-            capture(event)
-            yield event
-          end
+        source.call do |event|
+          capture(event)
+          yield event
         end
-      rescue Exception # rubocop:disable Lint/RescueException -- mark Interrupt/shutdown too, so it is not masked
+      rescue Exception # rubocop:disable Lint/RescueException
         errored = true
         raise
       ensure
@@ -83,34 +77,21 @@ module LlmCostTracker
       end
 
       def capture(event)
-        raw_payload = event.try(:deep_to_h) || event.try(:to_h) || {}
-        payload = SdkPayload.normalize(raw_payload)
-        type = event.try(:type) || payload["type"]
-        @collector.event(payload, type: type&.to_s)
+        data = event.to_h if event.respond_to?(:to_h)
+        type = event.type if event.respond_to?(:type)
+        @collector.event(data || {}, type: type&.to_s)
       rescue StandardError => e
         warn_capture_failure(e)
       end
 
       def warn_capture_failure(error)
-        should_warn = @mutex.synchronize do
-          next false if @capture_failed
-
-          @capture_failed = true
-          true
-        end
-        return unless should_warn
-
-        Logging.warn("stream integration failed to capture event: #{error.class}: #{error.message}")
+        first_failure = @mutex.synchronize { !@capture_failed && (@capture_failed = true) }
+        Logging.warn("stream integration failed to capture event: #{error.class}: #{error.message}") if first_failure
       end
 
       def finish!(errored:)
-        should_finish = @mutex.synchronize do
-          next false if @finished
-
-          @finished = true
-          true
-        end
-        return unless should_finish && @active.call
+        claimed = @mutex.synchronize { !@finished && (@finished = true) }
+        return unless claimed && @active.call
 
         begin
           @finish.call(errored)

data/lib/llm_cost_tracker/capture_verifier.rb

@@ -11,9 +11,8 @@ module LlmCostTracker
       end
 
       def report(checks = call)
-        (["LLM Cost Tracker capture verification"] + checks.map do |check|
-          "[#{check.status}] #{check.name}: #{check.message}"
-        end).join("\n")
+        lines = checks.map { |check| "[#{check.status}] #{check.name}: #{check.message}" }
+        ["LLM Cost Tracker capture verification", *lines].join("\n")
       end
 
       def healthy?(checks = call)
@@ -25,7 +24,7 @@ module LlmCostTracker
       [
         enabled_check,
         *integration_checks,
-        *storage_checks
+        *LlmCostTracker::Ingestion.verify
       ].compact
     end
 
@@ -49,11 +48,5 @@ module LlmCostTracker
         check.with(name: "sdk integration #{check.name}")
       end
     end
-
-    def storage_checks
-      LlmCostTracker::Ingestion.verify
-    rescue LlmCostTracker::Error => e
-      [Check.new(:error, "storage", e.message)]
-    end
   end
 end

data/lib/llm_cost_tracker/charges/cost_status.rb

@@ -11,12 +11,18 @@ module LlmCostTracker
       UNKNOWN = "unknown"
       INCOMPLETE = [UNKNOWN, PARTIAL].freeze
 
+      TokenCharge = Data.define(:cost, :partial) do
+        def priced? = !cost.nil?
+
+        def unpriced? = cost.nil? || partial
+      end
+      private_constant :TokenCharge
+
       def self.unknown_pricing_sql(total_cost: "total_cost", cost_status: "cost_status")
-        statuses = INCOMPLETE.map { |status| ActiveRecord::Base.connection.quote(status) }.join(", ")
+        statuses = INCOMPLETE.map { |status| ActiveRecord::Base.lease_connection.quote(status) }.join(", ")
         "#{total_cost} IS NULL OR #{cost_status} IN (#{statuses})"
       end
 
-      # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def self.call(token_usage:,
                     usage_source:,
                     token_cost:,
@@ -25,28 +31,26 @@ module LlmCostTracker
                     token_pricing_partial: false)
         return UNKNOWN if usage_source == Usage::Source::UNKNOWN
 
-        token_billable = token_usage.priced_quantities.any? { |_key, quantity| quantity.positive? }
-        service_billable = false
-        service_priced = false
-        service_unpriced = false
-        service_line_items.each do |line_item|
-          next unless line_item.billable?
+        charges = billable_charges(token_usage, token_cost, token_pricing_partial, service_line_items)
+        return for_cost(total_cost) if charges.none?(&:unpriced?)
 
-          service_billable = true
-          service_priced ||= line_item.priced?
-          service_unpriced ||= line_item.unpriced?
-          break if service_priced && service_unpriced
-        end
+        charges.any?(&:priced?) ? PARTIAL : UNKNOWN
+      end
+
+      def self.for_cost(cost)
+        return UNKNOWN if cost.nil?
 
-        priced = (token_billable && !token_cost.nil?) || service_priced || (!token_billable && !service_billable)
-        unpriced = (token_billable && (token_cost.nil? || token_pricing_partial)) || service_unpriced
-        return UNKNOWN if unpriced && !priced
-        return PARTIAL if unpriced
+        cost.zero? ? FREE : COMPLETE
+      end
 
-        return UNKNOWN if total_cost.nil?
+      def self.billable_charges(token_usage, token_cost, token_pricing_partial, service_line_items)
+        charges = service_line_items.select(&:billable?)
+        return charges unless token_usage.total_tokens.to_i.positive? ||
+                              token_usage.priced_quantities.any? { |_key, quantity| quantity.positive? }
 
-        total_cost.zero? ? FREE : COMPLETE
+        charges + [TokenCharge.new(cost: token_cost, partial: token_pricing_partial)]
       end
+      private_class_method :billable_charges
     end
   end
 end

data/lib/llm_cost_tracker/charges/line_item.rb

@@ -30,35 +30,27 @@ module LlmCostTracker
     )
 
     class LineItem
+      DIMENSION_FIELDS = %i[kind direction modality cache_state unit].freeze
+      DIMENSION_DEFAULTS = { cache_state: "none" }.freeze
+      AMOUNT_DEFAULTS = {
+        quantity: BigDecimal("0"), rate_amount: nil, rate_quantity: BigDecimal("1"), cost: nil
+      }.freeze
+      SOURCE_FIELDS = %i[pricing_basis price_key price_source].freeze
+      private_constant :DIMENSION_FIELDS, :DIMENSION_DEFAULTS, :AMOUNT_DEFAULTS, :SOURCE_FIELDS
+
       def self.build(attributes)
         attributes = attributes.to_h
-        dimension = dimension_for(attributes)
-        new(
-          kind: attributes[:kind]&.to_s || dimension&.kind,
-          direction: attributes[:direction]&.to_s || dimension&.direction,
-          modality: attributes[:modality]&.to_s || dimension&.modality,
-          cache_state: attributes[:cache_state]&.to_s || dimension&.cache_state || "none",
-          quantity: decimal_or_nil(attributes[:quantity]) || BigDecimal("0"),
-          unit: attributes[:unit]&.to_s || dimension&.unit,
-          rate_amount: decimal_or_nil(attributes[:rate_amount]),
-          rate_quantity: decimal_or_nil(attributes[:rate_quantity]) || BigDecimal("1"),
-          cost: decimal_or_nil(attributes[:cost]),
-          currency: canonical_currency(attributes[:currency]),
-          cost_status: cost_status_for(attributes),
-          pricing_basis: attributes[:pricing_basis]&.to_s,
-          price_key: attributes[:price_key]&.to_s,
-          price_source: attributes[:price_source]&.to_s,
-          price_source_version: attributes[:price_source_version],
-          provider_field: attributes[:provider_field],
-          provider_item_id: attributes[:provider_item_id],
-          details: attributes[:details] || {}
-        )
+        new(**dimension_fields(attributes), **amount_fields(attributes), **source_fields(attributes))
       end
 
       def self.from_token_usage(token_usage)
         return [] unless token_usage
 
-        token_usage.priced_quantities.filter_map do |key, quantity|
+        from_quantities(token_usage.priced_quantities)
+      end
+
+      def self.from_quantities(quantities)
+        quantities.filter_map do |key, quantity|
           next unless quantity.positive?
 
           dimension = Usage::Catalog.fetch(key)
@@ -73,14 +65,28 @@ module LlmCostTracker
         end
       end
 
-      def self.cost_status_for(attributes)
-        explicit = attributes[:cost_status]
-        return explicit.to_s if explicit
+      def self.dimension_fields(attributes)
+        dimension = dimension_for(attributes).to_h
+        DIMENSION_FIELDS.to_h do |field|
+          [field, attributes[field]&.to_s || dimension[field] || DIMENSION_DEFAULTS[field]]
+        end
+      end
 
-        cost = decimal_or_nil(attributes[:cost])
-        return CostStatus::UNKNOWN if cost.nil?
+      def self.amount_fields(attributes)
+        amounts = AMOUNT_DEFAULTS.to_h { |field, default| [field, decimal_or_nil(attributes[field]) || default] }
+        amounts.merge(
+          currency: (attributes[:currency] || LlmCostTracker::DEFAULT_CURRENCY).to_s.upcase,
+          cost_status: (attributes[:cost_status] || CostStatus.for_cost(amounts[:cost])).to_s
+        )
+      end
 
-        cost.zero? ? CostStatus::FREE : CostStatus::COMPLETE
+      def self.source_fields(attributes)
+        SOURCE_FIELDS.to_h { |field| [field, attributes[field]&.to_s] }.merge(
+          price_source_version: attributes[:price_source_version],
+          provider_field: attributes[:provider_field],
+          provider_item_id: attributes[:provider_item_id],
+          details: attributes[:details] || {}
+        )
       end
 
       def self.dimension_for(attributes)
@@ -96,11 +102,7 @@ module LlmCostTracker
         BigDecimal(value.to_s)
       end
 
-      def self.canonical_currency(value)
-        (value || LlmCostTracker::DEFAULT_CURRENCY).to_s.upcase
-      end
-
-      private_class_method :cost_status_for, :dimension_for, :decimal_or_nil, :canonical_currency
+      private_class_method :dimension_fields, :amount_fields, :source_fields, :dimension_for, :decimal_or_nil
 
       def billable?
         quantity.positive?
@@ -135,7 +137,7 @@ module LlmCostTracker
           rate_quantity: rate.quantity,
           cost: applied_cost,
           currency: rate.currency.upcase,
-          cost_status: applied_cost.zero? ? CostStatus::FREE : CostStatus::COMPLETE,
+          cost_status: CostStatus.for_cost(applied_cost),
           price_key: rate.source_key,
           price_source: rate.source,
           price_source_version: rate.source_version

data/lib/llm_cost_tracker/configuration/budgets.rb

@@ -9,14 +9,28 @@ module LlmCostTracker
     class Budgets < Section
       EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
       TOTALS_SOURCES = %i[ledger cache].freeze
-      PER_TAG_WINDOWS = %i[daily weekly monthly].freeze
+      PER_TAG_WINDOWS = %i[daily weekly monthly total calls].freeze
       PER_TAG_OPTIONS = %i[behavior on_exceeded].freeze
 
-      attributes :monthly, :daily, :per_call, :on_exceeded
+      LIMITS = %i[monthly daily per_call].freeze
+
       enum_attribute :exceeded_behavior, allowed: EXCEEDED_BEHAVIORS, default: :notify
       enum_attribute :totals_source, allowed: TOTALS_SOURCES, default: :ledger
 
-      attr_reader :per_tag
+      attr_reader(*LIMITS, :on_exceeded, :per_tag)
+
+      LIMITS.each do |name|
+        define_method(:"#{name}=") do |value|
+          ensure_mutable!
+          amount = validated_amount("budgets.#{name}", value, minimum: 0) unless value.nil?
+          instance_variable_set(:"@#{name}", value.is_a?(Numeric) ? value : amount)
+        end
+      end
+
+      def on_exceeded=(value)
+        ensure_mutable!
+        @on_exceeded = validated_callback("budgets.on_exceeded", value)
+      end
 
       def initialize(owner)
         super
@@ -35,7 +49,7 @@ module LlmCostTracker
       end
 
       def finalize!
-        @per_tag = deep_freeze(@per_tag || {})
+        @per_tag = deep_freeze(@per_tag)
       end
 
       private
@@ -48,19 +62,32 @@ module LlmCostTracker
         raise Error, "budgets.per_tag[#{key.inspect}] must be a hash" unless entry.is_a?(Hash)
 
         normalized = entry.to_h.transform_keys(&:to_sym)
-        windows, options = normalized.partition { |name, _| !PER_TAG_OPTIONS.include?(name) }.map(&:to_h)
+        {
+          windows: validated_windows(key, normalized.except(*PER_TAG_OPTIONS)),
+          behavior: validated_behavior(key, normalized[:behavior]),
+          on_exceeded: validated_callback("budgets.per_tag[#{key.inspect}][:on_exceeded]", normalized[:on_exceeded])
+        }
+      end
+
+      def validated_amount(name, value, minimum: nil)
+        number = Float(value, exception: false)
+        return BigDecimal(value.to_s) if number && (minimum ? number >= minimum : number.positive?)
+
+        raise Error, "#{name} must be a #{minimum ? 'non-negative' : 'positive'} number, got #{value.inspect}"
+      end
+
+      def validated_callback(name, value)
+        return value if value.nil? || value.respond_to?(:call)
+
+        raise Error, "#{name} must respond to call, got #{value.inspect}"
+      end
+
+      def validated_windows(key, windows)
         if windows.empty?
-          raise Error,
-                "budgets.per_tag[#{key.inspect}] needs at least one of: #{PER_TAG_WINDOWS.join(', ')}"
+          raise Error, "budgets.per_tag[#{key.inspect}] needs at least one of: #{PER_TAG_WINDOWS.join(', ')}"
         end
 
-        {
-          windows: windows.to_h do |window, limit|
-                     [validated_window(key, window), validated_limit(key, window, limit)]
-                   end,
-          behavior: validated_behavior(key, options[:behavior]),
-          on_exceeded: options[:on_exceeded]
-        }
+        windows.to_h { |window, limit| [validated_window(key, window), validated_limit(key, window, limit)] }
       end
 
       def validated_behavior(key, behavior)
@@ -81,12 +108,16 @@ module LlmCostTracker
       end
 
       def validated_limit(key, window, limit)
-        numeric = Float(limit, exception: false)
-        return BigDecimal(limit.to_s) if numeric&.positive?
+        return validated_calls(key, limit) if window == :calls
 
-        raise Error,
-              "budgets.per_tag[#{key.inspect}][#{window.inspect}] must be a positive number, " \
-              "got #{limit.inspect}"
+        validated_amount("budgets.per_tag[#{key.inspect}][#{window.inspect}]", limit)
+      end
+
+      def validated_calls(key, limit)
+        count = Integer(limit.to_s, exception: false)
+        return count if count&.positive?
+
+        raise Error, "budgets.per_tag[#{key.inspect}][:calls] must be a positive integer, got #{limit.inspect}"
       end
     end
   end

data/lib/llm_cost_tracker/configuration/capture.rb

@@ -8,7 +8,13 @@ module LlmCostTracker
       OPENAI_COMPATIBLE_PROVIDERS = {
         "openrouter.ai" => "openrouter",
         "api.deepseek.com" => "deepseek",
-        "api.groq.com" => "groq"
+        "api.groq.com" => "groq",
+        "api.x.ai" => "xai",
+        "us.api.x.ai" => "xai",
+        "api.mistral.ai" => "mistral",
+        "api.eu.mistral.ai" => "mistral",
+        "api.us.mistral.ai" => "mistral",
+        "api.perplexity.ai" => "perplexity"
       }.freeze
 
       attributes :request_stream_usage

data/lib/llm_cost_tracker/configuration/mutability.rb

@@ -18,12 +18,12 @@ module LlmCostTracker
             deep_freeze(key)
             deep_freeze(nested_value)
           end
-          value.frozen? ? value : value.freeze
+          value.freeze
         when Array, Set
           value.each { |nested_value| deep_freeze(nested_value) }
-          value.frozen? ? value : value.freeze
+          value.freeze
         when String
-          value.frozen? ? value : value.freeze
+          value.freeze
         else
           value
         end

data/lib/llm_cost_tracker/configuration/pricing.rb

@@ -29,7 +29,7 @@ module LlmCostTracker
       end
 
       def finalize!
-        @overrides = deep_freeze(@overrides || {})
+        @overrides = deep_freeze(@overrides)
       end
     end
   end

data/lib/llm_cost_tracker/configuration.rb

@@ -18,8 +18,6 @@ module LlmCostTracker
       budgets: Budgets, capture: Capture, ingestion: Ingestion, pricing: Pricing, tags: Tags
     }.freeze
 
-    SCALAR_ATTRIBUTES = %i[enabled].freeze
-
     DEPRECATED_OPTIONS = {
       monthly_budget: { to: %i[budgets monthly] },
       daily_budget: { to: %i[budgets daily] },
@@ -46,7 +44,7 @@ module LlmCostTracker
       log_level: { to: nil, note: "LlmCostTracker logs through Rails.logger, which owns the level" }
     }.freeze
 
-    attr_reader(*SCALAR_ATTRIBUTES, *SECTIONS.keys, :instrumented_integrations)
+    attr_reader(:enabled, *SECTIONS.keys, :instrumented_integrations)
 
     def initialize
       SECTIONS.each { |name, klass| instance_variable_set(:"@#{name}", klass.new(self)) }
@@ -67,11 +65,9 @@ module LlmCostTracker
       @instrumented_integrations.include?(name)
     end
 
-    SCALAR_ATTRIBUTES.each do |name|
-      define_method(:"#{name}=") do |value|
-        ensure_mutable!
-        instance_variable_set(:"@#{name}", value)
-      end
+    def enabled=(value)
+      ensure_mutable!
+      @enabled = value
     end
 
     DEPRECATED_OPTIONS.each do |old_name, spec|
@@ -101,7 +97,7 @@ module LlmCostTracker
 
     def finalize!
       SECTIONS.each_key { |name| public_send(name).finalize! }
-      @instrumented_integrations = deep_freeze(@instrumented_integrations || Set.new)
+      @instrumented_integrations = deep_freeze(@instrumented_integrations)
       @finalized = true
     end
 

data/lib/llm_cost_tracker/doctor/ingestion_check.rb

@@ -24,7 +24,17 @@ module LlmCostTracker
       private
 
       def async_ok
-        Check.new(:ok, "async ingestion", "inbox and ingestion lease tables are on the current schema")
+        quarantined = LlmCostTracker::Ingestion::InboxEntry.quarantined.count
+        if quarantined.zero?
+          return Check.new(:ok, "async ingestion", "inbox and ingestion lease tables are on the current schema")
+        end
+
+        Check.new(
+          :warn,
+          "async ingestion",
+          "#{quarantined} inbox row(s) are quarantined, so their spend is not in the ledger; " \
+          "requeue them as docs/operations.md shows once the cause is fixed"
+        )
       end
 
       def inline_check
@@ -38,11 +48,19 @@ module LlmCostTracker
         Check.new(
           :warn,
           "inline ingestion",
-          "config.ingestion.mode = :inline but found unused async ingestion tables: #{leftovers.join(', ')}. " \
+          "config.ingestion.mode = :inline but found unused async ingestion tables: #{leftovers.join(', ')}" \
+          "#{undrained_note(leftovers)}. " \
           "Set config.ingestion.mode = :async to keep the inbox path or drop the tables."
         )
       end
 
+      def undrained_note(leftovers)
+        return unless leftovers.include?(LlmCostTracker::Ingestion::InboxEntry.table_name)
+
+        rows = LlmCostTracker::Ingestion::InboxEntry.count
+        "; #{rows} inbox row(s) never reached the ledger, so drain them in :async mode first" if rows.positive?
+      end
+
       def inline_leftover_tables
         async_tables.select { |table| Probe.table_exists?(table) }
       end

data/lib/llm_cost_tracker/doctor/price_check.rb

@@ -15,29 +15,9 @@ module LlmCostTracker
         return bundled_check unless path
         return Check.new(:error, "prices", "#{path} does not exist; #{REFRESH_COMMAND}") unless File.exist?(path)
 
-        count = LlmCostTracker::Pricing::Registry.file_prices(path).size
-        metadata = LlmCostTracker::Pricing::Registry.file_metadata(path)
-        updated_at = metadata["updated_at"] || metadata[:updated_at]
-        return configured_check(:warn, path, count, "metadata.updated_at missing; #{REFRESH_COMMAND}") unless updated_at
-
-        age_days = (Date.today - Date.iso8601(updated_at.to_s)).to_i
-        if age_days > STALE_AFTER_DAYS
-          return configured_check(
-            :warn,
-            path,
-            count,
-            "updated_at=#{updated_at} is older than #{STALE_AFTER_DAYS} days; #{REFRESH_COMMAND}"
-          )
-        end
-
-        configured_check(:ok, path, count, "updated_at=#{updated_at}")
-      rescue Date::Error
-        configured_check(
-          :warn,
-          path,
-          count,
-          "metadata.updated_at=#{updated_at.inspect} is invalid; #{REFRESH_COMMAND}"
-        )
+        count = Pricing::Registry.file_prices(path).size
+        status, freshness = freshness(Pricing::Registry.file_metadata(path))
+        Check.new(status, "prices", "loaded #{count} models from #{path}; #{freshness}")
       rescue LlmCostTracker::Error => e
         Check.new(:error, "prices", e.message)
       end
@@ -45,16 +25,35 @@ module LlmCostTracker
       private
 
       def bundled_check
-        updated_at = LlmCostTracker::Pricing::Registry.metadata.fetch("updated_at", "unknown")
+        updated_at = Pricing::Registry.metadata.fetch("updated_at", "unknown")
         Check.new(
           :warn,
           "prices",
-          "using bundled prices updated_at=#{updated_at}; commit a prices_file for production releases"
+          "using bundled prices updated_at=#{updated_at}; " \
+          "commit a prices_file (config.pricing.file) for production releases"
         )
       end
 
-      def configured_check(status, path, count, freshness)
-        Check.new(status, "prices", "loaded #{count} models from #{path}; #{freshness}")
+      def freshness(metadata)
+        updated_at = metadata["updated_at"] || metadata[:updated_at]
+        return [:warn, "metadata.updated_at missing; #{REFRESH_COMMAND}"] unless updated_at
+
+        reason = staleness(updated_at)
+        reason ? [:warn, "#{reason}; #{REFRESH_COMMAND}"] : [:ok, "updated_at=#{updated_at}"]
+      rescue Date::Error
+        [:warn, "metadata.updated_at=#{updated_at.inspect} is invalid; #{REFRESH_COMMAND}"]
+      end
+
+      def staleness(updated_at)
+        file_date = Date.iso8601(updated_at.to_s)
+        if (Date.today - file_date).to_i > STALE_AFTER_DAYS
+          return "updated_at=#{updated_at} is older than #{STALE_AFTER_DAYS} days"
+        end
+
+        bundled_at = Pricing::Registry.metadata["updated_at"]
+        return unless bundled_at && file_date < Date.iso8601(bundled_at.to_s)
+
+        "updated_at=#{updated_at} is older than the bundled prices (#{bundled_at})"
       end
     end
   end

data/lib/llm_cost_tracker/doctor/probe.rb

@@ -6,7 +6,7 @@ module LlmCostTracker
   class Doctor
     module Probe
       def self.table_exists?(name)
-        LlmCostTracker::Call.connection.data_source_exists?(name)
+        LlmCostTracker::Call.lease_connection.data_source_exists?(name)
       rescue ActiveRecord::ConnectionNotEstablished, ActiveRecord::NoDatabaseError,
              ActiveRecord::ConnectionFailed, ActiveRecord::StatementInvalid
         false

data/lib/llm_cost_tracker/doctor/schema_check.rb

@@ -22,8 +22,7 @@ module LlmCostTracker
         Check.new(
           :error,
           @name,
-          "current schema required; #{errors.join('; ')}; " \
-          "run bin/rails generate llm_cost_tracker:install && bin/rails db:migrate"
+          "current schema required; #{errors.join('; ')}; see docs/upgrading.md"
         )
       end
     end