vehicles 0.9.0 → 0.9.2

data/lib/vehicles/dataset_slice.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # `Vehicles.dataset_slice`: one scope of the dataset (Spain's cars, say) in
+  # the shape of the published `dist/vehicles.json`, for clients that read
+  # that file: the make-model-dropdown widget's `data` option, and the JS and
+  # Python SDKs' dataset mode. Where `Vehicles.catalog` hands a page
+  # `{ make => [names] }`, this hands it the records behind the names (slugs,
+  # kinds, aliases, forms, former ids, availability, ranks), so the client
+  # resolves stored values and produces the canonical ids
+  # (`kind/make-slug/model-slug`) the way it would on the full release.
+  #
+  # Lean on purpose. Each model keeps what resolution, ordering and scoping
+  # read: name, slug, kind, aliases, forms, former_ids, availability,
+  # global_decile, mass_decile, country_ranks and registration_years. It drops
+  # `regions` (a rollup of availability) and `body_type`. With `country:`,
+  # `availability` and `country_ranks` keep only that country: every record
+  # in the slice is evidenced there, and the other countries' entries are
+  # most of the weight. Spain's cars (data 2026.11.3): ~360 KB of JSON, ~57 KB gzipped.
+  module DatasetSlice
+    # Model keys copied as published, in dist order. The two per-country keys
+    # are projected separately.
+    MODEL_KEYS = %w[name slug kind aliases forms former_ids global_decile mass_decile].freeze
+
+    module_function
+
+    def build(dataset, kind: nil, kinds: nil, region: nil, country: nil)
+      scope = KindRule.scope(kind, kinds)
+      code = country&.to_s&.downcase
+      makes = dataset.makes(kind: kind, region: region).filter_map do |make|
+        models = make.models(region: region).select do |m|
+          KindRule.allows?(scope, m) && (code.nil? || m.available_in?(code))
+        end
+        make_record(make, models, code) unless models.empty?
+      end
+      header(dataset, makes.flat_map { |m| m["kinds"] }.uniq.sort).merge("makes" => makes)
+    end
+
+    def header(dataset, kinds)
+      { "version" => dataset.version, "schema_version" => dataset.schema_version,
+        "kinds" => kinds, "license" => dataset.license,
+        "attribution" => dataset.attribution }.compact
+    end
+
+    def make_record(make, models, code)
+      record = { "name" => make.name, "slug" => make.slug,
+                 "kinds" => models.map { |m| m.kind.to_s }.uniq.sort }
+      record["aliases"] = make.aliases unless make.aliases.empty?
+      record["former_slugs"] = make.former_slugs unless make.former_slugs.empty?
+      record.merge("models" => models.map { |m| model_record(m, code) })
+    end
+
+    def model_record(model, code)
+      record = MODEL_KEYS.each_with_object({}) do |key, out|
+        value = case key
+                when "slug" then model.model_slug
+                when "kind" then model.kind.to_s
+                else model.public_send(key)
+                end
+        out[key] = value unless value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+      record["availability"] = code ? [code] : model.availability
+      ranks = code ? model.country_ranks.slice(code) : model.country_ranks
+      record["country_ranks"] = ranks unless ranks.empty?
+      years = model.registration_years
+      record["registration_years"] = { "first" => years[:first], "last" => years[:last] } if years
+      record
+    end
+  end
+
+  # Extended onto Vehicles (see the bottom of lib/vehicles.rb).
+  module DatasetSliceExport
+    # The same scope as `catalog`, as records in the shape of the published
+    # `dist/vehicles.json` (a Hash, ready for `to_json`): what the
+    # make-model-dropdown widget's `data` option and the JS/Python SDKs'
+    # dataset mode read. Embed it in the page and the widget resolves stored
+    # values and canonical ids with no request to a CDN or the API.
+    #   Vehicles.dataset_slice(kind: :car, country: :es)
+    #   # => { "version" => "2026.11.3", "schema_version" => 2, "kinds" => ["car"],
+    #   #      "license" => "CC-BY-4.0", "attribution" => {...},
+    #   #      "makes" => [{ "name" => "SEAT", "slug" => "seat", "kinds" => ["car"],
+    #   #                    "models" => [{ "name" => "Ibiza", "slug" => "ibiza", "kind" => "car", ... }] }] }
+    # With `country:`, each record's `availability` and `country_ranks` keep
+    # only that country (Spain's cars: ~360 KB of JSON, ~57 KB gzipped).
+    # `regions` and `body_type` are left out. See Vehicles::DatasetSlice.
+    def dataset_slice(kind: nil, region: nil, country: nil, kinds: nil)
+      DatasetSlice.build(dataset, kind: kind, kinds: kinds, region: region || configuration.region, country: country)
+    end
+  end
+end

data/lib/vehicles/hosted_result.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # The outcome of one hosted VehiclesDB call, for when `nil` is not enough:
+  # WHY there is no image. `Model#image` / `#images` keep answering nil on
+  # any failure; `Model#images_result` answers one of these.
+  #
+  #   r = Vehicles.find("seat leon").images_result(color: "red", exact_color: true)
+  #   r.ok?        # => false
+  #   r.reason     # => :payment_required
+  #   r.error      # => "insufficient_credits" (the API's own code, verbatim)
+  #   r.status     # => 402
+  #   r.url(:md)   # => nil (the variant URL when ok?)
+  #
+  # `reason` is coarse and stable (REASONS); `error` is the API's code and can
+  # be finer ("no_image", "unknown_color", "unsupported_filter",
+  # "insufficient_credits", "invalid_token", …). Client-side reasons have no
+  # status: :no_api_key, :timeout, :network, :invalid_response, and
+  # :color_not_available (`exact_color: true` and the model is not available in
+  # that color — the API would have served another one).
+  class HostedResult
+    REASONS = %i[ok no_api_key not_found unauthorized payment_required rate_limited invalid_request
+                 server_error timeout network invalid_response color_not_available].freeze
+
+    # Reasons that mean "something is wrong with the integration or the
+    # service", reported through `config.on_hosted_error` and the logger. A
+    # missing image, an unavailable color or no key are normal answers.
+    ALERTS = %i[unauthorized payment_required rate_limited invalid_request server_error timeout network
+                invalid_response].freeze
+
+    attr_reader :reason, :status, :error, :payload, :path
+
+    def initialize(reason:, status: nil, error: nil, payload: nil, path: nil, cached: false)
+      @reason = reason
+      @status = status
+      @error = error&.to_s
+      @payload = payload
+      @path = path
+      @cached = cached
+      freeze
+    end
+
+    # Build from an HTTP status (and the API's JSON error body, if any).
+    def self.from_status(status, body_error: nil, path: nil)
+      reason =
+        case status
+        when 200..299 then :ok
+        when 401, 403 then :unauthorized
+        when 402 then :payment_required
+        when 404, 410 then :not_found
+        when 400, 422 then :invalid_request
+        when 429 then :rate_limited
+        when 500..599 then :server_error
+        else :invalid_response
+        end
+      new(reason: reason, status: status, error: body_error, path: path)
+    end
+
+    def ok? = reason == :ok
+    def cached? = @cached
+    def alert? = ALERTS.include?(reason)
+
+    # The variant URL for a size (:sm/:md/:lg) when ok?, else nil.
+    def url(size = :md)
+      ok? ? payload&.dig("variants", size.to_s, "url") : nil
+    end
+
+    def with(**changes)
+      self.class.new(reason: reason, status: status, error: error, payload: payload, path: path, cached: @cached,
+                     **changes)
+    end
+
+    def message
+      parts = ["VehiclesDB", status, error || reason].compact
+      "#{parts.join(" ")} on #{path}"
+    end
+
+    # An exception object for error trackers (never raised by the gem).
+    def to_error
+      HostedError.new(message).tap { |e| e.result = self }
+    end
+
+    def to_h
+      { reason: reason, status: status, error: error, path: path, cached: cached? }
+    end
+
+    def inspect = %(#<Vehicles::HostedResult #{reason}#{" #{status}" if status}#{" #{error}" if error}>)
+  end
+
+  # Report-only exception carrying a HostedResult (HostedResult#to_error).
+  class HostedError < StandardError
+    attr_accessor :result
+  end
+end

data/lib/vehicles/http.rb

@@ -1,11 +1,23 @@
 # frozen_string_literal: true
 
 module Vehicles
-  # The one way this gem talks to a VehiclesDB server: a single GET, capped by
+  # The one way this gem talks to a VehiclesDB server: a GET capped by
   # `config.api_timeout`, never retried, never raising. Shared by the hosted
   # images provider (keyed, JSON) and the plate templates (public, SVG), so
   # the latency promise and the no-silent-retry rule live in one place.
   module HTTP
+    # A finished request. `status` is nil when no response arrived; `error`
+    # is then :timeout or :network.
+    Response = Struct.new(:status, :body, :error, :uri, :location, keyword_init: true) do
+      def success? = status.is_a?(Integer) && status.between?(200, 299)
+    end
+
+    # Renamed/merged ids answer a 301 to their successor (RESOLUTION.md §1),
+    # and a gem whose data is older or newer than the server's meets them
+    # around every release. One hop is the contract; two is slack.
+    MAX_REDIRECTS = 2
+    REDIRECTS = [301, 302, 303, 307, 308].freeze
+
     module_function
 
     # `config.api_base_url` + path + query. Plain concatenation, not
@@ -24,6 +36,22 @@ module Vehicles
     # The response body of a 2xx, or nil on ANY failure (network, timeout,
     # non-2xx). Callers treat nil as "fall back".
     def get(uri, headers = {})
+      response = request(uri, headers)
+      response.body if response.success?
+    end
+
+    # A Response for a GET, following up to MAX_REDIRECTS redirects that stay
+    # on the SAME origin (scheme, host, port) — so the Authorization header
+    # never travels to another host. Never raises.
+    def request(uri, headers = {}, redirects_left = MAX_REDIRECTS)
+      response = once(uri, headers)
+      return response unless REDIRECTS.include?(response.status) && redirects_left.positive?
+
+      target = redirect_target(uri, response)
+      target ? request(target, headers, redirects_left - 1) : response
+    end
+
+    def once(uri, headers)
       require "net/http"
 
       config = Vehicles.configuration
@@ -36,12 +64,52 @@ module Vehicles
       # served image twice, so one request means one request.
       http.max_retries = 0
 
-      request = Net::HTTP::Get.new(uri)
-      headers.each { |name, value| request[name] = value }
-      response = http.request(request)
-      response.body if response.is_a?(Net::HTTPSuccess)
-    rescue StandardError => e
-      warn "[vehicles] request to VehiclesDB failed (#{e.class}); falling back" if $DEBUG
+      req = Net::HTTP::Get.new(uri)
+      headers.each { |name, value| req[name] = value }
+      res = http.request(req)
+      Response.new(status: res.code.to_i, body: res.body, uri: uri, location: res["location"])
+    rescue Net::OpenTimeout, Net::ReadTimeout, Timeout::Error
+      Response.new(status: nil, body: nil, error: :timeout, uri: uri)
+    rescue StandardError
+      Response.new(status: nil, body: nil, error: :network, uri: uri)
+    end
+
+    # The body of a public GET for the dataset refresh (jsDelivr): any
+    # redirect is followed (no credentials travel), a longer timeout
+    # (`refresh_timeout`), nil on any non-2xx. Labelled UTF-8.
+    DOWNLOAD_REDIRECTS = 3
+
+    def download(url, timeout, redirects_left = DOWNLOAD_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
+
+        download(URI.join(url, response["location"]).to_s, timeout, redirects_left - 1)
+      end
+    end
+
+    def redirect_target(uri, response)
+      return nil if response.location.to_s.empty?
+
+      target = URI.join(uri.to_s, response.location)
+      same = target.scheme == uri.scheme && target.host == uri.host && target.port == uri.port
+      same ? target : nil
+    rescue URI::Error
       nil
     end
   end

data/lib/vehicles/id_lookup.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # Canonical-id lookups, extended onto Vehicles (`Vehicles.by_id`, …). An id
+  # is "kind/make-slug/model-slug" (Model#id, RESOLUTION.md §1): the thing to
+  # store. Datasets rename and merge records append-only, listing the old id
+  # in the successor's `former_ids`, so a stored id never dead-ends.
+  module IdLookup
+    # The Model a canonical id names, or nil. With `follow: true` (the
+    # default) a RETIRED id answers its successor: the record that lists it in
+    # `former_ids`, or — once the dataset publishes make `former_slugs` — the
+    # same model under the make's new slug. An id two different records
+    # absorbed (a split) answers nil: there is no one successor.
+    #   Vehicles.by_id("car/volkswagen/golf")              # => #<Vehicles::Model "Volkswagen Golf" hatchback>
+    #   Vehicles.by_id("car/alfa-romeo/159sw")              # => the 159 (renamed record)
+    #   Vehicles.by_id("car/alfa-romeo/159sw", follow: false) # => nil
+    #   Vehicles.by_id(id, kinds: [:car])  # nil unless the answer is a car
+    def by_id(id, follow: true, kinds: nil)
+      id = id.to_s.strip
+      found = dataset.models_by_id(id).first || (follow ? dataset.successor_of(id) : nil)
+      found && KindRule.allows?(KindRule.symbols(kinds), found) ? found : nil
+    end
+
+    # The id to store NOW for a stored id: itself when live, its successor's
+    # id when retired, nil when the dataset does not know it. Run it over a
+    # column after each refresh to migrate renamed ids.
+    #   Vehicles.successor("car/alfa-romeo/159sw")  # => "car/alfa-romeo/159"
+    def successor(id)
+      by_id(id, follow: true)&.id
+    end
+
+    # Does this id name a current record (not a retired one)?
+    def live?(id)
+      !dataset.models_by_id(id.to_s.strip).empty?
+    end
+  end
+end

data/lib/vehicles/kind_rule.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # How a kind narrows a lookup, and the ONE kind-collision rule every
+  # VehiclesDB surface shares (vehiclesdb RESOLUTION.md §3; lanes B/C,
+  # 2026-11-10).
+  #
+  # A kind collision is one nameplate (same make + model slug) published as
+  # several kinds — Iveco "Daily" is a van, a truck and a bus. Not ambiguity:
+  # when the caller gave no kind, the answer is the record with
+  #   1. the lowest `mass_decile` (unranked last),
+  #   2. then the kind order PRECEDENCE (any other kind after these, by
+  #      name),
+  #   3. then the canonical id.
+  # Only among the candidates a rung itself selected: a hit is never widened
+  # to sibling kinds that did not match.
+  # Backtested on register counts, that picks the kind most registered in 87%
+  # of collision groups (the old "car wins" picked it in 43%).
+  #
+  # `kind:` (one kind) scopes the name rungs; `kinds:` (a list) is a hard
+  # filter everywhere, ids included (`kinds: []` allows nothing).
+  module KindRule
+    PRECEDENCE = %i[van car bus truck moped motorcycle].freeze
+
+    module_function
+
+    # `kind:`/`kinds:` → the allowed kinds as Symbols, or nil for "any". With
+    # both, only kinds in both count.
+    def scope(kind, kinds)
+      return nil if kind.nil? && kinds.nil?
+
+      allowed = kinds.nil? ? nil : symbols(kinds)
+      return allowed if kind.nil?
+
+      allowed ? allowed & symbols(kind) : symbols(kind)
+    end
+
+    # nil (any), one kind or a list → [Symbol] or nil.
+    def symbols(kind)
+      kind.nil? ? nil : Array(kind).map { |k| k.to_s.to_sym }
+    end
+
+    def allows?(scope, model)
+      scope.nil? || scope.include?(model.kind)
+    end
+
+    # One record among kind variants of a nameplate (see above).
+    def pick(models)
+      models.min_by do |m|
+        rank = PRECEDENCE.index(m.kind)
+        [m.mass_decile || 99, rank ? 0 : 1, rank || 0, rank ? "" : m.kind.to_s, m.id]
+      end
+    end
+
+    # The `via` steps RESOLUTION.md names: `kind_hint:van`, `kinds:car,van`.
+    def via(kind, kinds)
+      steps = []
+      steps << "kind_hint:#{kind}" if kind
+      steps << "kinds:#{Array(kinds).join(",")}" if kinds
+      steps
+    end
+  end
+end

data/lib/vehicles/labels.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Vehicles
+  # Display labels for the gem's closed vocabularies — colors, kinds, body
+  # types — in English and Spanish, so an app does not hand-maintain the same
+  # tables. Model and make NAMES are never translated: they are proper nouns
+  # (real-world spellings such as "Clase A" arrive as curated `forms`).
+  #
+  #   Vehicles.color_options(locale: :es)   # => [["Blanco", "white"], ...]
+  #   Vehicles.color("rojo")                # => #<Vehicles::Color red ...>
+  #   Vehicles.kind_label(:van, locale: :es) # => "Furgoneta"
+  #   Vehicles.kind_options(locale: :es)     # => [["Autobús", "bus"], ["Coche", "car"], ...]
+  #   Vehicles.body_type_label(:wagon, locale: :es) # => "Familiar"
+  #
+  # Locales: :en, :es ("es-MX", :es_ES … fold to :es). Anything else falls
+  # back to English, never raises. You store the slug; the label is display.
+  module Labels
+    LOCALES = %i[en es].freeze
+
+    COLORS = {
+      en: { "white" => "White", "black" => "Black", "grey" => "Grey", "silver" => "Silver", "blue" => "Blue",
+            "red" => "Red", "green" => "Green", "brown" => "Brown", "beige" => "Beige", "orange" => "Orange",
+            "yellow" => "Yellow", "gold" => "Gold", "purple" => "Purple", "other" => "Other" },
+      es: { "white" => "Blanco", "black" => "Negro", "grey" => "Gris", "silver" => "Plata", "blue" => "Azul",
+            "red" => "Rojo", "green" => "Verde", "brown" => "Marrón", "beige" => "Beige", "orange" => "Naranja",
+            "yellow" => "Amarillo", "gold" => "Dorado", "purple" => "Morado", "other" => "Otro" }
+    }.freeze
+
+    # What people type for a color besides its label, per locale (the
+    # cross-surface list, DECISIONS D2 — the SDKs carry the same one).
+    # Matched after Vehicles.normalize, so accents never matter ("marrón").
+    COLOR_SYNONYMS = {
+      en: { "gray" => "grey", "silvery" => "silver", "tan" => "beige", "cream" => "beige",
+            "burgundy" => "red", "navy" => "blue" },
+      es: { "blanca" => "white", "negra" => "black", "plateado" => "silver", "plateada" => "silver",
+            "gris" => "grey", "dorada" => "gold", "amarilla" => "yellow", "morada" => "purple",
+            "violeta" => "purple", "granate" => "red", "azul marino" => "blue", "crema" => "beige",
+            "otra" => "other" }
+    }.freeze
+
+    KINDS = {
+      en: { "car" => "Car", "motorcycle" => "Motorcycle", "moped" => "Moped", "van" => "Van",
+            "truck" => "Truck", "bus" => "Bus", "pickup" => "Pickup", "trailer" => "Trailer",
+            "quad" => "Quad", "trike" => "Trike" },
+      es: { "car" => "Coche", "motorcycle" => "Moto", "moped" => "Ciclomotor", "van" => "Furgoneta",
+            "truck" => "Camión", "bus" => "Autobús", "pickup" => "Pick-up", "trailer" => "Remolque",
+            "quad" => "Quad", "trike" => "Triciclo" }
+    }.freeze
+
+    BODY_TYPES = {
+      en: { "hatchback" => "Hatchback", "sedan" => "Sedan", "wagon" => "Wagon", "suv" => "SUV",
+            "mpv" => "MPV", "coupe" => "Coupe", "convertible" => "Convertible", "roadster" => "Roadster",
+            "pickup" => "Pickup", "van" => "Van" },
+      es: { "hatchback" => "Compacto", "sedan" => "Berlina", "wagon" => "Familiar", "suv" => "SUV",
+            "mpv" => "Monovolumen", "coupe" => "Cupé", "convertible" => "Descapotable",
+            "roadster" => "Roadster", "pickup" => "Pick-up", "van" => "Furgoneta" }
+    }.freeze
+
+    module_function
+
+    # :en/:es from anything ("es-MX", :es_ES, "ES"); English otherwise.
+    def locale(value)
+      base = value.to_s.downcase[/\A[a-z]+/]&.to_sym
+      LOCALES.include?(base) ? base : :en
+    end
+
+    def color(slug, locale = :en) = lookup(COLORS, slug, locale)
+    def kind(kind, locale = :en) = lookup(KINDS, kind, locale)
+    def body_type(type, locale = :en) = lookup(BODY_TYPES, type, locale)
+
+    # The table entry in that locale, else English, else nil.
+    def lookup(table, key, locale)
+      key = key.to_s
+      table[locale(locale)][key] || table[:en][key]
+    end
+  end
+
+  # The palette and label helpers extended onto Vehicles
+  # (`Vehicles.colors`, `Vehicles.color`, `Vehicles.kind_label`, …).
+  module LabelOptions
+    # The canonical color palette, frequency-ordered. => [Vehicles::Color, ...]
+    # With `locale:`, each Color's `name` is the label in that locale.
+    def colors(locale: nil)
+      return Colors::ALL if locale.nil? || Labels.locale(locale) == :en
+
+      Colors::ALL.map { |c| Color.new(c.slug, c.label(locale), c.hex) }
+    end
+
+    # [[label, slug], ...] for a Rails `select`, in palette order. The slug
+    # is the stable value you store; the label is in `locale` (:en default,
+    # :es; anything else falls back to English).
+    #   Vehicles.color_options(locale: :es)  # => [["Blanco", "white"], ["Negro", "black"], ...]
+    def color_options(locale: :en)
+      Colors::ALL.map { |c| [c.label(locale), c.slug] }
+    end
+
+    # Resolve a color by slug, or by name in any supported language
+    # (forgiving: case, diacritics, synonyms — "gray"→grey, "navy"→blue,
+    # "Rojo"→red, "marrón"→brown, "plateada"→silver). A Vehicles::Color, or nil.
+    # `locale:` is accepted for parity with the SDKs; every locale's names are read anyway.
+    def color(query, locale: nil)
+      q = normalize(query)
+      return nil if q.empty?
+
+      Colors::BY_SLUG[q] || Colors::LOOKUP[q]
+    end
+
+    # "Furgoneta" for (:van, locale: :es); English for unknown locales; nil
+    # for an unknown kind.
+    def kind_label(kind, locale: :en)
+      Labels.kind(kind, locale)
+    end
+
+    # [[label, kind], ...] for a kind <select>, sorted by label. Defaults to
+    # the kinds the dataset publishes.
+    #   Vehicles.kind_options(locale: :es)  # => [["Autobús", "bus"], ["Camión", "truck"], ...]
+    def kind_options(locale: :en, kinds: self.kinds)
+      kinds.map { |k| [kind_label(k, locale: locale) || k.to_s, k.to_s] }.sort_by { |label, _| normalize(label) }
+    end
+
+    # "Familiar" for (:wagon, locale: :es); nil for an unknown body type.
+    def body_type_label(body_type, locale: :en)
+      Labels.body_type(body_type, locale)
+    end
+
+    # [[label, body_type], ...] in Model::BODY_TYPES order.
+    def body_type_options(locale: :en)
+      Model::BODY_TYPES.map { |t| [body_type_label(t, locale: locale), t.to_s] }
+    end
+  end
+end

data/lib/vehicles/make.rb

@@ -17,13 +17,17 @@ module Vehicles
     # (normalized key => models in dataset order); see #build_lookup_index.
     TABLES = %i[name name_squeezed slug alias alias_squeezed alias_raw form form_squeezed].freeze
 
-    attr_reader :name, :slug, :aliases, :kinds
+    attr_reader :name, :slug, :aliases, :kinds, :former_slugs
 
     def initialize(attrs)
       @name    = attrs["name"]
       @slug    = attrs["slug"]
       @aliases = Array(attrs["aliases"]).freeze
       @kinds   = Array(attrs["kinds"]).map(&:to_sym).freeze
+      # Slugs this make was published under before a rename or merge
+      # (dataset key `former_slugs`, when the dataset publishes it; [] until
+      # then). Vehicles.make and Vehicles.by_id follow them.
+      @former_slugs = Array(attrs["former_slugs"]).map(&:to_s).freeze
       @raw_models = attrs["models"] || []
     end
 
@@ -35,14 +39,13 @@ module Vehicles
     #   models(kind: :car, region: :eu)          # European cars only
     #   models(rarity: :common)                  # just the well-known ones
     #   models(max_decile: 3)                     # top-30% by popularity
-    def models(kind: nil, body_type: nil, region: nil, rarity: nil, max_decile: nil)
+    def models(kind: nil, body_type: nil, region: nil, rarity: nil, max_decile: nil, country: nil)
       list = (@models ||= @raw_models.map { |m| Model.new(m, make: name, make_slug: slug) }.freeze)
       list = list.select { |m| m.kind == kind.to_sym }             if kind
       list = list.select { |m| m.body_type == body_type.to_sym }   if body_type
       list = list.select { |m| m.available_in_region?(region) }    if region
-      list = list.select { |m| m.rarity == rarity.to_sym }         if rarity
-      list = list.select { |m| m.global_decile && m.global_decile <= max_decile } if max_decile
-      list
+      list = by_popularity(list, rarity, max_decile)
+      country ? by_country(list, country) : list
     end
 
     # Continents this make is evidenced in (union of its models' regions).
@@ -56,6 +59,11 @@ module Vehicles
       continents.include?(region.to_sym)
     end
 
+    # Does any of its models (of `kind`) have evidence in this country?
+    def available_in?(country, kind: nil)
+      models(kind: kind).any? { |m| m.available_in?(country) }
+    end
+
     # Model display names — what you drop into a dropdown. => ["A3", "A4", ...]
     def model_names(**filters)
       models(**filters).map(&:name)
@@ -73,13 +81,15 @@ module Vehicles
     # vehicle_model validator relies on this). Fuzzy/partial matching lives in
     # `Vehicles.search`.
     #
-    # Some names exist as several kinds (Toyota "Land Cruiser" is a car, a
-    # van, a truck and a bus). Without `kind:` the car wins — it's what people
-    # mean — and pass `kind:` to pick another:
-    #   toyota.model("Land Cruiser")              # => the car
-    #   toyota.model("Land Cruiser", kind: :bus)  # => the bus
-    def model(query, kind: nil)
-      matches, how = strict_lookup(Vehicles.normalize(query), kind: kind)
+    # Some names exist as several kinds (Iveco "Daily" is a van, a truck and
+    # a bus). Without a kind the one collision rule decides (Vehicles::KindRule;
+    # until 0.9.1 the car always won). Pass `kind:` to pick
+    # one, or `kinds:` to allow only some:
+    #   iveco.model("Daily")              # => the van
+    #   iveco.model("Daily", kind: :bus)  # => the bus
+    #   iveco.model("Daily", kinds: %i[car]) # => nil (no car Daily)
+    def model(query, kind: nil, kinds: nil)
+      matches, how = strict_lookup(Vehicles.normalize(query), kind: KindRule.scope(kind, kinds))
       matches && how != :ambiguous ? pick(matches) : nil
     end
 
@@ -140,9 +150,9 @@ module Vehicles
       idx[:name].key?(key) || idx[:alias].key?(key) || idx[:slug].key?(key)
     end
 
-    # Car first, like #model: it is what people mean by a bare name.
+    # One record among kind variants of a nameplate: Vehicles::KindRule.
     def pick(matches)
-      matches.find(&:car?) || matches.first
+      KindRule.pick(matches)
     end
 
     def to_h
@@ -183,19 +193,35 @@ module Vehicles
 
       loose = of_kind(idx[:name_squeezed][query.delete(" ")], kind)
       return [nil, nil] if loose.empty?
-      return [loose, :spacing] if loose.map { |m| idx[:normalized][m] }.uniq.one?
+      # One NAMEPLATE (model slug) in several kinds is a kind collision, not
+      # ambiguity, even when a release styles the kinds' names differently.
+      return [loose, :spacing] if loose.map(&:model_slug).uniq.one?
 
       [loose, :ambiguous]
     end
 
+    # `kind` is nil (any), one kind, or a list of allowed kinds.
     def of_kind(list, kind)
       list ||= []
-      kind ? list.select { |m| m.kind == kind.to_sym } : list
+      allowed = KindRule.symbols(kind)
+      allowed ? list.select { |m| allowed.include?(m.kind) } : list
+    end
+
+    def by_popularity(list, rarity, max_decile)
+      list = list.select { |m| m.rarity == rarity.to_sym } if rarity
+      list = list.select { |m| m.global_decile && m.global_decile <= max_decile } if max_decile
+      list
+    end
+
+    # A country's own ranking first (Model#rank_in), then the make's order.
+    def by_country(list, country)
+      c = country.to_s.downcase
+      list.select { |m| m.availability.include?(c) }
+          .each_with_index.sort_by { |m, i| [m.rank_in(c) ? 0 : 1, m.rank_in(c) || 0, i] }.map(&:first)
     end
 
-    # Union of two index hits, deduplicated by IDENTITY (Model#== compares
-    # slugs, so a car and a van of the same nameplate are "equal") and put
-    # back in dataset order.
+    # Union of two index hits, deduplicated by identity and put back in
+    # dataset order.
     def in_order(first, second)
       return first || [] unless second
       return second unless first