vehicles 0.9.0 → 0.9.2

data/lib/vehicles/providers/hosted_provider.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "time"
 
 module Vehicles
   module Providers
@@ -13,16 +14,29 @@ module Vehicles
     #
     # The images endpoint is LIVE (since 2026-07): mint a key at
     # https://vehiclesdb.com/settings/api-keys, set `config.api_key`, and
-    # `model.image` / `model.images` answer with rendered vehicle imagery.
+    # `model.image` / `model.images` answer with studio vehicle imagery.
+    # Since 0.9.2:
+    #   - a renamed/merged id's 301 is followed (same origin only);
+    #   - failures are no longer silent: `model.images_result` says why
+    #     (Vehicles::HostedResult), and 401/402/403/429/5xx/timeouts go to
+    #     `config.on_hosted_error` and a warn log line;
+    #   - payloads are cached (`config.image_cache`), so a page view does not
+    #     pay per image;
+    #   - `year:` is sent, not dropped (the API answers 422
+    #     `unsupported_filter` until year-accurate images ship);
+    #   - `exact_color: true` refuses the API's honest color fallback.
     #
     # `years` and `segment` are the wired-up seam for enrichment the API does
-    # not serve yet: they answer nil WITHOUT a request (a call to an endpoint
-    # that doesn't exist would only cost latency), so the chain falls through
-    # to the local data. They light up here when the API ships them.
+    # not serve yet: they answer nil WITHOUT a request, so the chain falls
+    # through to the local data.
     module HostedProvider
       # Every VehiclesDB API endpoint lives under this path on
       # `config.api_base_url` (https://vehiclesdb.com/api/v1/...).
       API_PREFIX = "/api/v1"
+      CACHE_SCOPE = "vehicles/images/v1"
+      # A cached hit is dropped this long before the payload's own
+      # `expires_at`, so a served URL never dies in a visitor's browser.
+      EXPIRY_MARGIN = 3600
 
       module_function
 
@@ -39,39 +53,138 @@ module Vehicles
       end
 
       # One variant URL — the common "just give me an <img src>" case.
-      # `size` picks from the API's rendered variants (:sm 320×180, :md
+      # `size` picks from the API's image variants (:sm 320×180, :md
       # 640×360, :lg 1280×720; webp).
-      def image(model, year: nil, color: nil, size: :md)
-        images(model, color: color)&.dig("variants", size.to_s, "url")
-      end
-
-      # The full images payload for a model — palette, every variant with
-      # dimensions, provenance, and the honest color fallback: `color` is what
-      # the API actually served, `requested_color` what you asked for (a color
-      # that isn't rendered yet falls back rather than 404ing).
-      #
-      # GET /api/v1/vehicles/:kind/:make_slug/:model_slug/images?color=<slug>
-      #
-      # `year`/`trim` filters are RESERVED server-side today (the API 422s on
-      # them by contract, so callers can't silently build on unimplemented
-      # semantics) — which is why `image` accepts `year:` but never sends it:
-      # serving the current rendering beats an error until the filter ships.
-      def images(model, color: nil)
-        params = {}
-        params[:color] = color.to_s unless color.to_s.empty?
-        get("#{API_PREFIX}/vehicles/#{model.kind}/#{model.make_slug}/#{model.model_slug}/images", params)
+      def image(model, year: nil, color: nil, size: :md, exact_color: false)
+        images_result(model, year: year, color: color, exact_color: exact_color).url(size)
+      end
+
+      # The full images payload (palette, every variant with dimensions,
+      # provenance, `color` served vs `requested_color` asked), or nil.
+      def images(model, color: nil, year: nil, exact_color: false)
+        result = images_result(model, color: color, year: year, exact_color: exact_color)
+        result.ok? ? result.payload : nil
+      end
+
+      # GET /api/v1/vehicles/:kind/:make_slug/:model_slug/images — a
+      # Vehicles::HostedResult, never nil, never raises.
+      def images_result(model, color: nil, year: nil, exact_color: false)
+        return HostedResult.new(reason: :no_api_key) unless available?
+
+        color = color.to_s.empty? ? nil : color.to_s
+        path = "#{API_PREFIX}/vehicles/#{model.id}/images"
+        if exact_color && color && (palette = cache_read(palette_key(model))) && !palette.include?(color)
+          return HostedResult.new(reason: :color_not_available, path: path, cached: true)
+        end
+
+        result = cached_or_fetch(model, path, color, year)
+        exact_color && color && result.ok? && result.payload["color"] != color ? color_unavailable(result) : result
+      rescue StandardError => e
+        HostedResult.new(reason: :invalid_response, error: e.class.name, path: path)
       end
 
       # --- internals -----------------------------------------------------------
 
-      # Issue a keyed GET and parse JSON. Returns nil on ANY failure (network,
-      # timeout, non-200, bad JSON) — callers treat nil as "fall back to local
-      # data". The wire rules (timeout, no retry) are Vehicles::HTTP's.
-      def get(path, params)
-        body = HTTP.get(HTTP.url(path, params),
-                        "Authorization" => "Bearer #{Vehicles.configuration.api_key}", "Accept" => "application/json")
-        body && JSON.parse(body)
-      rescue StandardError # bad JSON, a malformed api_base_url
+      def cached_or_fetch(model, path, color, year)
+        key = cache_key(model, color, year)
+        hit = cache_read(key)
+        return from_cache(hit, path) if hit.is_a?(Hash)
+
+        result = fetch(path, { color: color, year: year }.compact.transform_values(&:to_s))
+        remember(model, key, result)
+        notify(result)
+        result
+      end
+
+      # A keyed GET → HostedResult.
+      def fetch(path, params)
+        response = HTTP.request(HTTP.url(path, params),
+                                "Authorization" => "Bearer #{Vehicles.configuration.api_key}",
+                                "Accept" => "application/json")
+        return HostedResult.new(reason: response.error, path: path) if response.status.nil?
+
+        body = parse(response.body)
+        unless response.success?
+          error = body.is_a?(Hash) ? body["error"] : nil
+          return HostedResult.from_status(response.status, body_error: error, path: path)
+        end
+        return HostedResult.new(reason: :invalid_response, status: response.status, path: path) unless
+          body.is_a?(Hash) && body["variants"].is_a?(Hash)
+
+        HostedResult.new(reason: :ok, status: response.status, payload: body, path: path)
+      end
+
+      def color_unavailable(result)
+        result.with(reason: :color_not_available)
+      end
+
+      def remember(model, key, result)
+        if result.ok?
+          cache_write(key, { "payload" => result.payload, "status" => result.status }, hit_ttl(result.payload))
+          palette = result.payload["palette"]
+          cache_write(palette_key(model), palette, hit_ttl(result.payload)) if palette.is_a?(Array)
+        elsif result.reason == :not_found
+          cache_write(key, { "status" => result.status, "error" => result.error },
+                      Vehicles.configuration.image_miss_ttl)
+        end
+      end
+
+      def from_cache(entry, path)
+        if entry["payload"]
+          HostedResult.new(reason: :ok, status: entry["status"], payload: entry["payload"], path: path, cached: true)
+        else
+          HostedResult.from_status(entry["status"], body_error: entry["error"], path: path).with(cached: true)
+        end
+      end
+
+      def hit_ttl(payload)
+        ttl = Vehicles.configuration.image_cache_ttl
+        expires = payload["expires_at"] && Time.iso8601(payload["expires_at"].to_s)
+        expires ? [ttl, (expires - Time.now - EXPIRY_MARGIN).to_i].min : ttl
+      rescue ArgumentError
+        ttl
+      end
+
+      # Alerts → `config.on_hosted_error` + one warn line + an
+      # ActiveSupport notification ("request.vehicles") for every call.
+      # The path carries a model id and nothing else (no query string).
+      def notify(result)
+        Vehicles.instrument("request.vehicles", result.to_h)
+        return unless result.alert?
+
+        Vehicles.logger&.warn("[vehicles] #{result.message}")
+        Vehicles.configuration.on_hosted_error&.call(result)
+      rescue StandardError
+        nil # a broken callback must never break a page
+      end
+
+      def parse(body)
+        body.to_s.empty? ? nil : JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # The base URL is in the key so a development server's answers never
+      # serve production; the year/color complete the request identity.
+      def cache_key(model, color, year)
+        [CACHE_SCOPE, Vehicles.configuration.api_base_url, model.id, color || "-", year || "-"].join("|")
+      end
+
+      def palette_key(model)
+        [CACHE_SCOPE, Vehicles.configuration.api_base_url, model.id, "palette"].join("|")
+      end
+
+      def cache_read(key)
+        Vehicles.configuration.image_cache&.read(key)
+      rescue StandardError
+        nil
+      end
+
+      def cache_write(key, value, ttl)
+        return if ttl.to_i <= 0
+
+        Vehicles.configuration.image_cache&.write(key, value, expires_in: ttl)
+      rescue StandardError
         nil
       end
     end

data/lib/vehicles/providers/local_provider.rb

@@ -19,8 +19,8 @@ module Vehicles
       # (and ultimately yield nil) instead of raising.
       def years(_model)                                          = nil
       def segment(_model)                                        = nil
-      def image(_model, year: nil, color: nil, size: :md)        = nil
-      def images(_model, color: nil)                             = nil
+      def image(_model, year: nil, color: nil, size: :md, exact_color: false) = nil
+      def images(_model, color: nil, year: nil, exact_color: false) = nil
     end
   end
 end

data/lib/vehicles/refresh_result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # What Vehicles.refresh did, and why. Immutable; never raised.
+  #
+  #   result = Vehicles.refresh
+  #   result.status            # => :updated | :current | :rejected | :failed
+  #   result.ok?               # => true for :updated and :current
+  #   result.updated?          # => a newer dataset is now on disk (and served)
+  #   result.reason            # => nil, or why not (see REASONS)
+  #   result.version           # => the release the refresh looked at ("2026.11.2")
+  #   result.previous_version  # => the newest dataset this app already had
+  #   result.message           # => one human sentence for a log line
+  #
+  # :current  — the published release is the one you already have; nothing
+  #             was downloaded (the manifest answered).
+  # :rejected — the release exists but is not safe to serve here, so it was
+  #             NOT written: an unsupported schema, older than your data, a
+  #             checksum or count mismatch, a payload far smaller than your
+  #             data (`config.refresh_min_ratio`), or your `refresh_guard`.
+  # :failed   — the network or the CDN let you down; try again later.
+  class RefreshResult
+    STATUSES = %i[updated current rejected failed].freeze
+
+    REASONS = {
+      schema_unsupported: "the release uses a dataset schema this gem version does not read",
+      older: "the release is older than the data this app already has",
+      version_mismatch: "the payload's version is not the version the manifest announced",
+      checksum_mismatch: "the payload does not match the manifest's checksum",
+      count_mismatch: "the payload's model counts do not match the manifest",
+      below_floor: "the payload has far fewer models than the data this app already has",
+      guard: "config.refresh_guard refused the release",
+      invalid_payload: "the download is not a VehiclesDB dataset",
+      manifest_unavailable: "the release manifest could not be fetched or read",
+      download_failed: "the dataset download failed",
+      write_failed: "the dataset could not be written to config.cache_path",
+      error: "an unexpected error"
+    }.freeze
+
+    attr_reader :status, :reason, :version, :previous_version, :detail
+
+    def initialize(status:, reason: nil, version: nil, previous_version: nil, detail: nil)
+      @status = status
+      @reason = reason
+      @version = version&.to_s
+      @previous_version = previous_version&.to_s
+      @detail = detail
+      freeze
+    end
+
+    def ok? = %i[updated current].include?(status)
+    def updated? = status == :updated
+    def current? = status == :current
+    def rejected? = status == :rejected
+    def failed? = status == :failed
+
+    def message
+      case status
+      when :updated then "dataset #{previous_version} → #{version}"
+      when :current then "dataset #{previous_version} is current"
+      else
+        text = REASONS.fetch(reason, reason.to_s)
+        text = "#{text} (#{detail})" if detail
+        "refresh #{status} #{version}: #{text}".squeeze(" ")
+      end
+    end
+
+    def to_h
+      { status: status, reason: reason, version: version, previous_version: previous_version, detail: detail }
+    end
+
+    def inspect = %(#<Vehicles::RefreshResult #{status}#{" #{reason}" if reason} #{message.inspect}>)
+  end
+end

data/lib/vehicles/refresher.rb

@@ -3,33 +3,48 @@
 require "json"
 
 module Vehicles
-  # Pulls the latest published dataset from the VehiclesDB data repo (config.data_url)
-  # into a local file cache (config.cache_path). This is how data fixes and new
-  # makes reach an app WITHOUT a gem upgrade — schedule `Vehicles.refresh!` (e.g.
-  # a daily job) and loads will prefer the cached data over the bundled snapshot.
+  # Pulls the latest published dataset into `config.cache_path`, so data
+  # fixes and new makes reach an app WITHOUT a gem upgrade. Schedule
+  # `Vehicles.refresh` daily; every process then picks the new file up on its
+  # own (Vehicles::DataSource).
   #
-  # Error-isolated by design: a failed/partial download never corrupts the cache
-  # and never raises — the gem just keeps serving whatever it already had
-  # (cached, or the bundled snapshot). Atomic write so a reader never sees a
-  # half-written file.
+  # Safe by construction (0.9.2) — a release is written only when ALL hold:
+  #   1. the manifest (`config.manifest_url`, read FIRST, a few KB) announces
+  #      a dataset schema this gem reads and a version NEWER than the newest
+  #      data the app already has (bundled or cached). Same version → done,
+  #      nothing downloaded; older → refused: never a downgrade;
+  #   2. the payload is fetched from that exact release (jsDelivr `@latest`
+  #      is pinned to the announced version, so the two files cannot come
+  #      from different releases), parses, carries that version and schema,
+  #      and matches the manifest's per-kind model counts and its
+  #      `dist_files` sha256/bytes when the manifest publishes them;
+  #   3. no kind, and no (kind, country) slice, shrinks below
+  #      `config.refresh_min_ratio` (default 0.9) of the data in use: a
+  #      release that lost Spain's cars cannot empty a Spanish picker;
+  #   4. `config.refresh_guard`, if set, accepts it.
+  # Then it is written atomically (temp file + rename in the same
+  # directory). A failure at any step leaves the current data untouched.
+  # Never raises; returns a Vehicles::RefreshResult.
   module Refresher
-    MAX_REDIRECTS = 3
-
     module_function
 
-    # Download + cache the latest dataset. Returns true on success, false on any
-    # failure (network, non-200, unparseable/empty payload). Never raises.
-    def refresh!
-      config = Vehicles.configuration
-      body = fetch(config.data_url, config.refresh_timeout)
-      return false unless valid_payload?(body)
+    def refresh
+      baseline = nil
+      outcome = begin
+        baseline = DataSource.newest_version
+        run(baseline)
+      rescue StandardError => e
+        result(:failed, :error, detail: "#{e.class}: #{e.message}")
+      end
+      final = RefreshResult.new(**outcome.to_h, previous_version: baseline)
+      report(final)
+      final
+    end
 
-      write_atomic(config.cache_path, body)
-      Vehicles.reload! # drop the in-memory dataset so the next access uses fresh data
-      true
-    rescue StandardError => e
-      Vehicles.logger&.warn("[vehicles] refresh failed: #{e.class}: #{e.message}")
-      false
+    # Backward compatible boolean: true when the app now has the latest
+    # release (just written, or already current).
+    def refresh! # rubocop:disable Naming/PredicateMethod -- the pre-0.9.2 boolean API, kept for callers
+      refresh.ok?
     end
 
     # True when a refreshed dataset is cached on disk.
@@ -39,7 +54,7 @@ module Vehicles
     end
 
     def cached_path
-      cached? ? Vehicles.configuration.cache_path : nil
+      cached? ? Vehicles.configuration.cache_path.to_s : nil
     end
 
     # Remove the cached dataset (the gem falls back to the bundled snapshot).
@@ -51,49 +66,170 @@ module Vehicles
 
     # --- internals -----------------------------------------------------------
 
-    # A payload is only accepted if it parses and looks like our dataset, so a
-    # CDN error page / truncated download can never replace good data.
-    def valid_payload?(body)
-      return false if body.to_s.empty?
+    def run(baseline)
+      config = Vehicles.configuration
+      manifest = nil
+      if config.manifest_url
+        manifest = parse_json(fetch(config.manifest_url, config.refresh_timeout))
+        verdict = manifest_verdict(manifest, baseline)
+        return verdict if verdict
+      end
+
+      url = manifest ? pinned(config.data_url, manifest["version"]) : config.data_url
+      body = fetch(url, config.refresh_timeout)
+      return result(:failed, :download_failed, manifest&.dig("version")) if body.to_s.empty?
+
+      payload_verdict(body, manifest, baseline)
+    end
+
+    # nil to go on and download; otherwise the result (no manifest, an
+    # unsupported schema, or nothing newer).
+    def manifest_verdict(manifest, baseline)
+      return result(:failed, :manifest_unavailable) unless manifest.is_a?(Hash) && manifest["version"]
+
+      announced = DataSource.version(manifest["version"])
+      schema = manifest["dist_schema_version"]
+      return result(:rejected, :schema_unsupported, manifest["version"], detail: "schema #{schema}") unless
+        DataSource::SCHEMA_VERSIONS.include?(schema)
+      return result(:rejected, :invalid_payload, manifest["version"], detail: "manifest version") unless announced
+
+      compare(announced, baseline)
+    end
+
+    # A RefreshResult when the parsed payload is not a dataset this gem reads.
+    def malformed(data)
+      return result(:rejected, :invalid_payload) unless data.is_a?(Hash) && data["makes"].is_a?(Array) &&
+                                                        !data["makes"].empty?
+      return result(:rejected, :invalid_payload, data["version"], detail: "version") unless
+        DataSource.version(data["version"])
 
-      data = JSON.parse(body)
-      data.is_a?(Hash) && data["makes"].is_a?(Array) && !data["makes"].empty?
+      return if DataSource::SCHEMA_VERSIONS.include?(data["schema_version"])
+
+      result(:rejected, :schema_unsupported, data["version"], detail: "schema #{data["schema_version"]}")
+    end
+
+    def payload_verdict(body, manifest, baseline)
+      data = parse_json(body)
+      problem = malformed(data)
+      return problem if problem
+
+      version = DataSource.version(data["version"])
+      if manifest
+        problem = ReleaseChecks.manifest_mismatch(manifest, data, body, dist_key)
+        return result(:rejected, *problem.first(1), version, detail: problem[1]) if problem
+      end
+
+      verdict = compare(version, baseline)
+      return verdict if verdict
+
+      problem = ReleaseChecks.below_floor(data)
+      return result(:rejected, :below_floor, version, detail: problem) if problem
+
+      candidate = materialize(data)
+      return result(:rejected, :invalid_payload, version, detail: "models") unless candidate
+
+      guard = Vehicles.configuration.refresh_guard
+      return result(:rejected, :guard, version) if guard && !guard.call(candidate, Vehicles.dataset)
+
+      write(body, version, data)
+    end
+
+    # Every model built once, so a malformed record fails the refresh instead
+    # of a later request. nil when it does not build.
+    def materialize(data)
+      Dataset.new(data).tap(&:all_models)
+    rescue StandardError
+      nil
+    end
+
+    # nil when the candidate is newer than what we have; otherwise the result.
+    def compare(candidate, baseline)
+      return nil if baseline.nil? || candidate > baseline
+      return result(:current, nil, candidate) if candidate == baseline
+
+      result(:rejected, :older, candidate)
+    end
+
+    def write(body, version, data = nil)
+      path = Vehicles.configuration.cache_path.to_s
+      return result(:failed, :write_failed, version, detail: "no cache_path") if path.empty?
+
+      promoted = with_lock(path) do
+        # Another process may have promoted a release meanwhile: re-check the
+        # version AND the shrink floor against the newest data on disk.
+        verdict = compare(version, DataSource.newest_version)
+        next verdict if verdict
+
+        problem = data && ReleaseChecks.below_floor(data, DataSource.newest_dataset(path))
+        next result(:rejected, :below_floor, version, detail: problem) if problem
+
+        write_atomic(path, body)
+        nil
+      end
+      return promoted if promoted
+
+      Vehicles.reload!
+      result(:updated, nil, version)
+    rescue SystemCallError, IOError => e
+      result(:failed, :write_failed, version, detail: e.class.name)
+    end
+
+    # jsDelivr's `@latest` resolves per file and is cached per file, so the
+    # manifest and the payload could come from two releases. Ask for the
+    # release the manifest announced.
+    def pinned(url, version)
+      url.to_s.sub("@latest/", "@#{version}/")
+    end
+
+    def dist_key
+      Vehicles.configuration.data_url.to_s[%r{dist/[^/?#]+\z}] || "dist/vehicles.json"
+    end
+
+    def result(status, reason = nil, version = nil, detail: nil)
+      RefreshResult.new(status: status, reason: reason, version: version, detail: detail)
+    end
+
+    def report(result)
+      if result.ok?
+        Vehicles.logger&.info("[vehicles] #{result.message}")
+      else
+        Vehicles.logger&.warn("[vehicles] #{result.message}")
+      end
+      Vehicles.instrument("refresh.vehicles", result.to_h)
+    rescue StandardError
+      nil # a broken logger must not turn a refresh into an exception
+    end
+
+    def parse_json(body)
+      body.to_s.empty? ? nil : JSON.parse(body)
     rescue JSON::ParserError
-      false
-    end
-
-    def fetch(url, timeout, redirects_left = MAX_REDIRECTS)
-      require "net/http"
-      require "uri"
-
-      uri = URI(url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-      http.open_timeout = timeout
-      http.read_timeout = timeout
-
-      response = http.get(uri.request_uri, "Accept" => "application/json")
-      case response
-      when Net::HTTPSuccess
-        # Net::HTTP hands back an ASCII-8BIT body (e.g. after gzip decompression);
-        # our datasets are UTF-8 JSON, so label it correctly. Otherwise downstream
-        # writes/parses can transcode-raise under Encoding.default_internal = UTF-8.
-        response.body&.dup&.force_encoding(Encoding::UTF_8)
-      when Net::HTTPRedirection
-        return nil if redirects_left <= 0
-
-        fetch(response["location"], timeout, redirects_left - 1)
+      nil
+    end
+
+    # The dataset download (public, no key): Vehicles::HTTP.download.
+    def fetch(url, timeout) = HTTP.download(url, timeout)
+
+    # An exclusive lock next to the cache file, so two refreshes (two
+    # workers, two containers on one volume) never interleave check + write.
+    def with_lock(path)
+      require "fileutils"
+      FileUtils.mkdir_p(File.dirname(path))
+      File.open("#{path}.lock", File::RDWR | File::CREAT, 0o644) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
       end
     end
 
     def write_atomic(path, body)
       require "fileutils"
       FileUtils.mkdir_p(File.dirname(path))
-      tmp = "#{path}.#{Process.pid}.tmp"
+      tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
       # Binary write: persist the exact bytes, never transcode. Robust regardless
       # of the body's encoding or the app's Encoding.default_internal.
       File.binwrite(tmp, body)
       File.rename(tmp, path) # atomic on the same filesystem
+    ensure
+      File.delete(tmp) if tmp && File.exist?(tmp)
     end
   end
 end

data/lib/vehicles/release_checks.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Vehicles
+  # The integrity and sanity checks Refresher runs on a downloaded release
+  # before it may replace the data in use.
+  module ReleaseChecks
+    # Slices smaller than this are too small for a ratio to mean anything
+    # (a country with 12 buses can lose 2 to a merge).
+    FLOOR_MIN_BUCKET = 25
+
+    module_function
+
+    # [reason, detail] or nil.
+    def manifest_mismatch(manifest, data, body, dist_key)
+      return [:version_mismatch, "#{data["version"]} ≠ #{manifest["version"]}"] if
+        data["version"] != manifest["version"]
+
+      file = manifest.dig("dist_files", dist_key) || {}
+      return [:checksum_mismatch, "#{dist_key} bytes"] if file["bytes"].is_a?(Integer) && body.bytesize != file["bytes"]
+      return [:checksum_mismatch, dist_key] if file["sha256"] && Digest::SHA256.hexdigest(body) != file["sha256"]
+
+      expected = manifest["kinds"]
+      return nil unless expected.is_a?(Hash)
+
+      actual = kind_counts(raw_models(data))
+      expected.each do |kind, counts|
+        want = counts.is_a?(Hash) ? counts["models"] : nil
+        next unless want.is_a?(Integer)
+        return [:count_mismatch, "#{kind}: #{actual.fetch(kind, 0)} ≠ #{want}"] if actual.fetch(kind, 0) != want
+      end
+      nil
+    end
+
+    # A detail string when some kind or (kind, country) slice of the candidate
+    # is below refresh_min_ratio of the data in use; nil when all hold.
+    def below_floor(data, dataset = Vehicles.dataset)
+      ratio = Vehicles.configuration.refresh_min_ratio
+      return nil if ratio.nil?
+
+      current = dataset.all_models.map { |m| [m.kind.to_s, m.availability] }
+      before = bucket_counts(current)
+      after = bucket_counts(raw_models(data))
+      before.each do |bucket, count|
+        next if count < FLOOR_MIN_BUCKET
+        return "#{bucket.compact.join("/")}: #{after.fetch(bucket, 0)} < #{ratio} × #{count}" if
+          after.fetch(bucket, 0) < ratio * count
+      end
+      nil
+    end
+
+    # [[kind, availability], ...] from a raw payload.
+    def raw_models(data)
+      data["makes"].flat_map do |make|
+        Array(make["models"]).map { |m| [(m["kind"] || "car").to_s, Array(m["availability"])] }
+      end
+    end
+
+    def kind_counts(pairs)
+      pairs.each_with_object(Hash.new(0)) { |(kind, _), h| h[kind] += 1 }
+    end
+
+    # { [kind, nil] => n, [kind, country] => n }
+    def bucket_counts(pairs)
+      pairs.each_with_object(Hash.new(0)) do |(kind, countries), h|
+        h[[kind, nil]] += 1
+        countries.each { |c| h[[kind, c]] += 1 }
+      end
+    end
+  end
+end