vehicles 0.9.0 → 0.9.2

data/lib/vehicles/text_matcher.rb

@@ -21,24 +21,33 @@ module Vehicles
 
     module_function
 
-    def identify(text, kind: nil)
+    # `kind:` scopes the NAME rungs and only prefers a variant on the id
+    # rungs (an id is explicit: "bus/iveco/daily" with kind: :car is still
+    # that bus). `kinds:` is a hard constraint on EVERY rung: a record of
+    # another kind never answers, so the result is nil when it is the only
+    # answer (RESOLUTION.md §3, lanes B/C 2026-11-10).
+    def identify(text, kind: nil, kinds: nil)
       raw = text.to_s.strip
       return nil if raw.empty?
 
-      hint = ModelMatcher.kind_hint(kind)
+      hint = KindRule.via(kind, kinds)
+      allowed = KindRule.symbols(kinds)
       ds = Vehicles.dataset
-      by_id(ds.models_by_id(raw), :exact, kind, hint + ["exact:#{raw}"]) ||
-        by_id(ds.models_by_former_id(raw), :former_id, kind, hint + ["former_id:#{raw}"]) ||
-        by_make(ds, text, kind, hint)
+      by_id(scoped(ds.models_by_id(raw), allowed), :exact, kind, hint + ["exact:#{raw}"]) ||
+        by_id(scoped(ds.models_by_former_id(raw), allowed), :former_id, kind, hint + ["former_id:#{raw}"]) ||
+        by_make(ds, text, KindRule.scope(kind, kinds), hint)
     end
 
+    def scoped(hits, allowed) = hits.select { |m| KindRule.allows?(allowed, m) }
+
     # Rungs 1–2: ids are explicit, so `kind:` only chooses among kind
-    # variants of the same record. Two different records → ambiguous.
+    # variants of the same record (else the collision rule, KindRule.pick).
+    # Two different records → ambiguous.
     def by_id(hits, rung, kind, via)
       return nil if hits.empty?
       return ModelMatcher.ambiguous(hits, rung, via) unless hits.map { |m| record(m) }.uniq.one?
 
-      model = (kind && hits.find { |m| m.kind == kind.to_sym }) || hits.find(&:car?) || hits.first
+      model = (kind && hits.find { |m| m.kind == kind.to_s.to_sym }) || KindRule.pick(hits)
       ModelMatcher.build(model, hits, [rung], via)
     end
 
@@ -89,14 +98,14 @@ module Vehicles
     # 2026-07-27; RESOLUTION.md rung 6 says "no OTHER record").
     def whole_text_alias(dataset, query, kind, hint)
       hits = dataset.models_by_alias(query)
-      hits = hits.select { |m| m.kind == kind.to_sym } if kind
+      hits = scoped(hits, KindRule.symbols(kind))
       return nil if hits.empty?
-      return nil if (dataset.records_named(query) - hits.map { |m| record(m) }).any?
+      return nil if (dataset.records_named(query, KindRule.symbols(kind)) - hits.map { |m| record(m) }).any?
 
       via = hint + ["alias:#{query}"]
       return ModelMatcher.ambiguous(hits, :alias, via) unless hits.map { |m| record(m) }.uniq.one?
 
-      model = hits.find(&:car?) || hits.first
+      model = KindRule.pick(hits)
       ModelMatcher.build(model, hits, [:alias], [*via[0...-1], "#{via.last}→#{record(model)}"],
                          confidence: WHOLE_TEXT_ALIAS)
     end

data/lib/vehicles/validators/vehicle_make_validator.rb

@@ -11,17 +11,34 @@
 # Pass `allow_other: true` to accept the "Other / not in the list" escape hatch
 # (see `Vehicles.other?`) — pair it with `Vehicles.make_options(include_other:)`
 # so the dropdown and the validation agree by construction.
+#
+# Scope it like your picker (0.9.2) so a value the picker never offered fails:
+#   validates :make, vehicle_make: { kind: :car, country: :es }
+# `kind:` — the make builds that kind; `country:` — it has a model (of that
+# kind) with evidence in that country. Country evidence is presence, not
+# exhaustive eligibility: opt in only when the picker uses the same scope.
 class VehicleMakeValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
     return if value.blank?
     return if options[:allow_other] && Vehicles.other?(value)
+
     # Exact-only: a typo must fail validation, not be stored as if it were the
     # make it resembles (Vehicles.make is typo-tolerant since 0.7.8).
-    return if Vehicles.make(value, fuzzy: false)
+    make = Vehicles.make(value, fuzzy: false)
+    return if make && in_scope?(make)
 
     record.errors.add(attribute, options[:message] || "is not a recognized vehicle make")
   rescue StandardError => e
     Vehicles.logger&.error("[vehicles] vehicle_make validation error: #{e.message}")
     record.errors.add(attribute, options[:message] || "is not a recognized vehicle make")
   end
+
+  private
+
+  def in_scope?(make)
+    kind = options[:kind]
+    return false if kind && !make.kinds.include?(kind.to_sym)
+
+    options[:country].nil? || make.available_in?(options[:country], kind: kind)
+  end
 end

data/lib/vehicles/validators/vehicle_model_validator.rb

@@ -13,6 +13,12 @@
 #
 # Pass `allow_other: true` to accept the "Other / not in the list" escape hatch
 # (see `Vehicles.other?`) — pair it with `Vehicles.model_options(include_other:)`.
+#
+# Scope it like your picker (0.9.2):
+#   validates :model, vehicle_model: { make: :make, kind: :car, country: :es }
+# `kind:` / `kinds:` — only records of those kinds count; `country:` — the
+# record must have evidence in that country (opt-in: presence, not
+# exhaustive eligibility).
 class VehicleModelValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
     return if value.blank?
@@ -22,11 +28,21 @@ class VehicleModelValidator < ActiveModel::EachValidator
     make_value = record.respond_to?(make_attribute) ? record.public_send(make_attribute) : nil
     make = Vehicles.make(make_value, fuzzy: false) # exact, same rule as the make validator
     return if make.nil? # unknown make -> defer to the make validator
-    return if make.model(value)
+    return if in_scope?(make, value)
 
     record.errors.add(attribute, options[:message] || "is not a recognized #{make.name} model")
   rescue StandardError => e
     Vehicles.logger&.error("[vehicles] vehicle_model validation error: #{e.message}")
     record.errors.add(attribute, options[:message] || "is not a recognized vehicle model")
   end
+
+  private
+
+  def in_scope?(make, value)
+    scope = Vehicles::KindRule.scope(options[:kind], options[:kinds])
+    country = options[:country]
+    return !make.model(value, kinds: scope).nil? if country.nil?
+
+    (scope || make.kinds).any? { |k| make.model(value, kind: k)&.available_in?(country) }
+  end
 end

data/lib/vehicles/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Vehicles
-  VERSION = "0.9.0"
+  VERSION = "0.9.2"
 end

data/lib/vehicles.rb

@@ -3,6 +3,7 @@
 require_relative "vehicles/version"
 require_relative "vehicles/configuration"
 require_relative "vehicles/http"
+require_relative "vehicles/kind_rule"
 require_relative "vehicles/make"
 require_relative "vehicles/model"
 require_relative "vehicles/color"
@@ -12,10 +13,17 @@ require_relative "vehicles/model_matcher"
 require_relative "vehicles/text_matcher"
 require_relative "vehicles/dataset_resolution"
 require_relative "vehicles/dataset"
+require_relative "vehicles/dataset_slice"
+require_relative "vehicles/data_source"
+require_relative "vehicles/refresh_result"
+require_relative "vehicles/release_checks"
 require_relative "vehicles/refresher"
+require_relative "vehicles/hosted_result"
+require_relative "vehicles/labels"
 require_relative "vehicles/providers/local_provider"
 require_relative "vehicles/providers/hosted_provider"
 require_relative "vehicles/other_option"
+require_relative "vehicles/id_lookup"
 require_relative "vehicles/plates"
 require_relative "vehicles/plates/jurisdiction"
 require_relative "vehicles/plates/series"
@@ -53,7 +61,7 @@ module Vehicles
       @configuration = Configuration.new
       @providers = nil
       @data_path = nil
-      Dataset.reset!
+      reload!
     end
 
     # --- data access ---------------------------------------------------------
@@ -63,35 +71,59 @@ module Vehicles
       @data_path || DATA_PATH
     end
 
-    attr_writer :data_path, :logger
-
-    # The dataset file actually in effect: an explicit override wins; otherwise a
-    # refreshed cache (if present and `use_cache`); otherwise the bundled snapshot.
-    # This is how a refresh reaches the running app — no gem upgrade needed.
-    def active_data_path
-      return @data_path if @data_path
-      return Refresher.cached_path if configuration.use_cache && Refresher.cached?
+    attr_writer :logger
 
-      DATA_PATH
+    # Serve this file instead (tests, a pinned snapshot). Takes effect on the
+    # next call; nil goes back to the cache/bundled rules.
+    def data_path=(path)
+      @data_path = path&.to_s
+      reload!
     end
 
-    def dataset
-      Dataset.load(active_data_path)
-    end
+    # The explicit `data_path=` override, or nil.
+    def data_path_override = @data_path
 
-    # Pull the latest published dataset into the local cache, so data fixes / new
-    # makes land WITHOUT a gem upgrade. Returns true/false; never raises. Schedule
-    # it (e.g. a daily job — `rails g vehicles:install` sets one up).
-    def refresh!
-      Refresher.refresh!
-    end
+    # The dataset file actually in effect: an explicit override wins; otherwise
+    # a refreshed cache when usable (`use_cache`, a schema this gem reads, not
+    # older than the bundled data); otherwise the bundled snapshot. This is how
+    # a refresh reaches the running app — no gem upgrade, no restart.
+    def active_data_path = DataSource.active_path
+
+    # The Vehicles::Dataset in effect. Every process re-checks the file every
+    # `config.reload_check_interval` seconds and adopts a newer one on its own.
+    def dataset = DataSource.dataset
+
+    # Pull the latest published dataset into `config.cache_path`, so data
+    # fixes and new makes land WITHOUT a gem upgrade, safely: manifest first,
+    # never a downgrade, never a schema this gem cannot read, never a release
+    # that lost a chunk of your data (see Vehicles::Refresher). Never raises;
+    # returns a Vehicles::RefreshResult (`ok?`, `updated?`, `status`,
+    # `reason`, `message`). Schedule it daily (`rails g vehicles:install`).
+    #   result = Vehicles.refresh
+    #   Rails.logger.warn(result.message) unless result.ok?
+    def refresh = Refresher.refresh
 
-    # Drop the in-memory dataset so the next access reloads from disk (after a
-    # refresh, a cache clear, or a `data_path=` change).
+    # `refresh.ok?` — true when the app has the latest release (just written,
+    # or already current). Kept for callers of the pre-0.9.2 boolean API.
+    def refresh! = Refresher.refresh!
+
+    # Drop the in-memory dataset so the next access reloads from disk now
+    # (processes also notice a changed file on their own; see `dataset`).
     def reload!
+      DataSource.reset!
       Dataset.reset!
     end
 
+    # ActiveSupport::Notifications when present ("refresh.vehicles",
+    # "request.vehicles"); a no-op otherwise. Never raises.
+    def instrument(name, payload)
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications.instrument(name, payload)
+    rescue StandardError
+      nil
+    end
+
     # Version of the dataset currently in effect (refreshed cache or bundled),
     # e.g. "2026.06.0".
     def data_version
@@ -108,8 +140,9 @@ module Vehicles
     # Make display names. => ["Abarth", "Alfa Romeo", ...]
     #   Vehicles.makes(kind: :motorcycle, region: :as)  # continent filter
     #   Vehicles.makes(include_other: true)             # ... + the "Other" escape hatch
-    def makes(kind: nil, region: nil, include_other: false)
-      names = dataset.makes(kind: kind, region: region || configuration.region).map(&:name)
+    #   Vehicles.makes(kind: :car, country: :es)       # makes with a car evidenced in Spain
+    def makes(kind: nil, region: nil, country: nil, include_other: false)
+      names = dataset.makes(kind: kind, region: region || configuration.region, country: country).map(&:name)
       append_other_name(names, include_other)
     end
 
@@ -119,10 +152,15 @@ module Vehicles
     # With `include_other:`, an unknown make (e.g. the "Other" make itself) yields
     # just `[other_label]`, so a make→model picker never dead-ends.
     # `fuzzy:` is forwarded to `make` (typo-tolerant by default since 0.7.8).
-    def models(make, kind: nil, body_type: nil, region: nil, rarity: nil, max_decile: nil, include_other: false,
-               fuzzy: true)
+    #
+    # With `country:` (ISO alpha-2), only models evidenced there, in that
+    # country's own popularity order:
+    #   Vehicles.models("SEAT", kind: :car, country: :es)  # => ["Ibiza", "Arona", "León", ...]
+    # A name can repeat when the make sells it as several kinds (pass `kind:`).
+    def models(make, kind: nil, body_type: nil, region: nil, rarity: nil, max_decile: nil, country: nil,
+               include_other: false, fuzzy: true)
       names = make(make, fuzzy: fuzzy)&.models(kind: kind, body_type: body_type,
-                                               region: region || configuration.region,
+                                               region: region || configuration.region, country: country,
                                                rarity: rarity, max_decile: max_decile)&.map(&:name) || []
       append_other_name(names, include_other)
     end
@@ -159,8 +197,14 @@ module Vehicles
     # data, not guessing: a spelling claimed by two different models answers
     # nil. `fuzzy:` governs the MAKE typo tolerance only, as before. Need to
     # know how a pair matched, or want cleanup/typo tolerance? `match_model`.
-    def model(make_name, model_name, fuzzy: true, kind: nil)
-      (found = make(make_name, fuzzy: fuzzy)) && ModelMatcher.exact(found, model_name, kind: kind)
+    #
+    # Kind collisions (one nameplate as several kinds) follow the one rule
+    # every VehiclesDB surface shares (Vehicles::KindRule): "Iveco Daily"
+    # is the van. `kind:` picks a kind; `kinds:` allows only some (nil when
+    # none of them has that name).
+    def model(make_name, model_name, fuzzy: true, kind: nil, kinds: nil)
+      (found = make(make_name, fuzzy: fuzzy)) &&
+        ModelMatcher.exact(found, model_name, kind: KindRule.scope(kind, kinds))
     end
 
     # Resolve a stored make + model pair and say HOW: a Vehicles::ModelMatch
@@ -176,8 +220,13 @@ module Vehicles
     #   Vehicles.match_model("VW", "Sirocco").rung       # => :fuzzy
     #   Vehicles.match_model("Honda", "Honda")          # => nil
     # See Vehicles::ModelMatcher for the rungs and their rules.
-    def match_model(make_name, model_name, kind: nil)
-      ModelMatcher.match(make_name, model_name, kind: kind)
+    #
+    # Safe to write back without asking? `match.confident?` (curated rungs
+    # only, never a typo guess, never ambiguous). Scope by kind with `kind:`
+    # (one kind) or `kinds:` (a hard list: a record of another kind never
+    # answers).
+    def match_model(make_name, model_name, kind: nil, kinds: nil)
+      ModelMatcher.match(make_name, model_name, kind: kind, kinds: kinds)
     end
 
     # Resolve ONE free-text string ("vw golf", "MERCEDES-BENZ SPRINTER",
@@ -188,9 +237,12 @@ module Vehicles
     # Nothing resolves without a make except ids and whole-text aliases.
     #   Vehicles.identify("vw tuareg").model   # => Volkswagen Touareg (:fuzzy)
     #   Vehicles.identify("golf")              # => nil
-    def identify(text, kind: nil) = TextMatcher.identify(text, kind: kind)
+    # `kind:` scopes the name rungs (an explicit id still answers whatever
+    # its kind); `kinds:` is a hard filter on every rung, ids included:
+    #   Vehicles.identify("bus/iveco/daily", kinds: [:car])  # => nil
+    def identify(text, kind: nil, kinds: nil) = TextMatcher.identify(text, kind: kind, kinds: kinds)
 
-    # License plates (the bundled PRD-PLATES dataset). No argument: every
+    # License plates (the bundled plates dataset). No argument: every
     # jurisdiction. With a code: that jurisdiction (or nil — forgiving).
     #   Vehicles.plates          # => [#<Jurisdiction nl …>, …]
     #   Vehicles.plates(:nl)     # => the Netherlands entry (33 series)
@@ -223,6 +275,7 @@ module Vehicles
     #   Vehicles.top_models(kind: :car, country: :nl, limit: 10).map(&:name)
     #   Vehicles.top_models(kind: :motorcycle, region: :as, limit: 10)
     #   Vehicles.top_models(kind: :car, by: :mass_decile)  # by registration mass (data 2026.10.1+)
+    # `limit: nil` returns every match (for a per-country picker, prefer `catalog(country:)`).
     def top_models(kind: nil, country: nil, region: nil, limit: 20, by: :global_decile)
       dataset.top_models(kind: kind, country: country, region: region, limit: limit, by: by)
     end
@@ -238,43 +291,22 @@ module Vehicles
 
     # Continent codes present in the dataset. => [:af, :as, :eu, :na, :oc, :sa]
     def regions
-      @regions ||= dataset.all_models.flat_map(&:regions).uniq.sort
-    end
-
-    # --- colors (canonical reference palette) --------------------------------
-
-    # The canonical color palette, frequency-ordered. => [Vehicles::Color, ...]
-    def colors
-      Colors::ALL
-    end
-
-    # [[name, slug], ...] for a Rails `select`. Names are English — localize the
-    # labels in your app; the slug is the stable value you store.
-    def color_options
-      Colors::ALL.map { |c| [c.name, c.slug] }
-    end
-
-    # Resolve a color by slug or name (forgiving: case, diacritics, synonyms like
-    # "gray"→grey, "navy"→blue). Returns a Vehicles::Color, or nil.
-    def color(query)
-      q = normalize(query)
-      return nil if q.empty?
-
-      Colors::BY_SLUG[q] || Colors::BY_NAME[q] || Colors::BY_SLUG[Colors::SYNONYMS[q]]
+      dataset.regions
     end
 
     # [[label, value], ...] of makes for a Rails `select`.
     #   Vehicles.make_options(include_other: true)  # ... + [other_label, "other"]
-    def make_options(kind: nil, region: nil, include_other: false)
-      opts = dataset.makes(kind: kind, region: region || configuration.region).map { |m| [m.name, m.slug] }
+    def make_options(kind: nil, region: nil, country: nil, include_other: false)
+      opts = dataset.makes(kind: kind, region: region || configuration.region, country: country)
+                    .map { |m| [m.name, m.slug] }
       append_other_option(opts, include_other)
     end
 
     # [[label, value], ...] of a make's models for a Rails `select`. Unknown => [].
     #   Vehicles.model_options("audi", include_other: true)  # ... + [other_label, "other"]
-    def model_options(make, kind: nil, body_type: nil, include_other: false, fuzzy: true)
+    def model_options(make, kind: nil, body_type: nil, country: nil, include_other: false, fuzzy: true)
       found = make(make, fuzzy: fuzzy)
-      opts = found ? found.model_options(kind: kind, body_type: body_type) : []
+      opts = found ? found.model_options(kind: kind, body_type: body_type, country: country) : []
       append_other_option(opts, include_other)
     end
 
@@ -284,14 +316,27 @@ module Vehicles
 
     # A { make => [model names] } map for the given filters — everything you need
     # to build a dependent make → model picker entirely on the client: embed it
-    # once (`Vehicles.catalog(kind: :car).to_json`) and switch the model list in a
-    # few lines of JS. No endpoint, no extra request, instant. The whole car
-    # catalog is small (tens of KB), so this is the simplest path for most apps.
-    #   Vehicles.catalog(kind: :car)   # => { "Audi" => ["A3", "A4", ...], ... }
-    def catalog(kind: nil, region: nil)
-      makes(kind: kind, region: region).to_h do |name|
-        [name, models(name, kind: kind, region: region)]
-      end
+    # once and switch the model list in a few lines of JS (or hand it to the
+    # make-model-dropdown widget). No endpoint, no extra request, instant.
+    # Makes are alphabetical.
+    #
+    # Scope it to your market with `country:` (ISO alpha-2): only models with
+    # official evidence there, each make's models in that country's popularity
+    # order. That is the picker list a one-country app wants — Spain's cars are
+    # ~140 makes / ~1,300 models, ~14 KB of JSON — where the whole global car
+    # catalog is ~330 makes / ~6,000 models (~63 KB).
+    #   Vehicles.catalog(kind: :car, country: :es)["SEAT"]  # => ["Ibiza", "Arona", "León", ...]
+    #   Vehicles.catalog(kind: :car)                # => every car, worldwide
+    # Pass `kind:` for a picker: without it a nameplate sold as a car and a
+    # van appears twice.
+    # `kinds:` allows several kinds (a car-and-van picker); `[]` is empty.
+    def catalog(kind: nil, region: nil, country: nil, kinds: nil)
+      scope = KindRule.scope(kind, kinds)
+      region ||= configuration.region
+      dataset.makes(kind: kind, region: region, country: country).filter_map do |make|
+        names = make.models(region: region, country: country).select { |m| KindRule.allows?(scope, m) }.map(&:name)
+        [make.name, names.uniq] unless names.empty?
+      end.to_h
     end
 
     # --- provider resolution (hosted enrichment, optional) -------------------
@@ -363,6 +408,13 @@ module Vehicles
   # they become Vehicles singleton methods with access to `configuration` /
   # `normalize`.
   extend OtherOption
+  # Canonical-id lookups (`by_id`, `successor`, `live?`) and the en/es label
+  # helpers (`kind_label`, `kind_options`, `body_type_label`,
+  # `body_type_options`), extended the same way.
+  extend IdLookup
+  extend LabelOptions
+  # `Vehicles.dataset_slice` (lib/vehicles/dataset_slice.rb).
+  extend DatasetSliceExport
 end
 
 # Loaded after the module so its lookup tables can use Vehicles.normalize.

data/rakelib/data_refresh.rake

@@ -14,7 +14,7 @@ require "json"
 # are copied from the SAME tag's catalog/<kind>/models.json
 # (popularity.by_country[cc].rank — open CC-BY data), keyed by the full
 # kind/make/model id, so the merged file is what the pipeline's own projection
-# emits once it ships the key (vehiclesdb-pipeline emit.rb write_dist_json!,
+# emits once it ships the key (the VehiclesDB data pipeline,
 # 2026-10-10). When the projection DOES carry the key, the task asserts every
 # rank equals the catalog's and aborts on any mismatch. Output formatting is
 # the pipeline's (JSON.pretty_generate + "\n"); stripping `country_ranks`

data/rakelib/plates_refresh.rake

@@ -13,7 +13,7 @@ namespace :plates do
     rm_rf "#{root}/data/plates/_art"
     commit = `git -C #{ds} rev-parse origin/main`.strip
     File.write("#{root}/data/plates/PROVENANCE.md", <<~MD)
-      # Bundled plates dataset (PRD-PLATES, full corpus)
+      # Bundled plates dataset (full corpus)
 
       Copy of `plates/` from the public data repo (EXCLUDING `_art/`),
       refreshed on gem releases:

data/sig/vehicles.rbs

@@ -13,26 +13,35 @@ module Vehicles
   def self.data_version: () -> String?
   def self.region: () -> Symbol
 
-  def self.makes: (?kind: Symbol?, ?region: Symbol?) -> Array[String]
-  def self.models: (untyped make, ?kind: Symbol?, ?body_type: Symbol?, ?region: Symbol?) -> Array[String]
+  def self.makes: (?kind: Symbol?, ?region: Symbol?, ?country: untyped, ?include_other: bool) -> Array[String]
+  def self.models: (untyped make, ?kind: Symbol?, ?body_type: Symbol?, ?region: Symbol?, ?country: untyped) -> Array[String]
   def self.make: (untyped query) -> Make?
   def self.find: (untyped query) -> Model?
-  def self.model: (untyped make_name, untyped model_name, ?fuzzy: bool, ?kind: Symbol?) -> Model?
-  def self.match_model: (untyped make_name, untyped model_name, ?kind: Symbol?) -> ModelMatch?
-  def self.identify: (untyped text, ?kind: Symbol?) -> ModelMatch?
+  def self.model: (untyped make_name, untyped model_name, ?fuzzy: bool, ?kind: Symbol?, ?kinds: Array[Symbol]?) -> Model?
+  def self.match_model: (untyped make_name, untyped model_name, ?kind: Symbol?, ?kinds: Array[Symbol]?) -> ModelMatch?
+  def self.identify: (untyped text, ?kind: Symbol?, ?kinds: Array[Symbol]?) -> ModelMatch?
+  def self.by_id: (untyped id, ?follow: bool, ?kinds: Array[Symbol]?) -> Model?
+  def self.successor: (untyped id) -> String?
+  def self.live?: (untyped id) -> bool
   def self.search: (untyped query) -> Array[Model]
-  def self.make_options: (?kind: Symbol?, ?region: Symbol?) -> Array[[String, String]]
-  def self.model_options: (untyped make, ?kind: Symbol?, ?body_type: Symbol?) -> Array[[String, String]]
-  def self.catalog: (?kind: Symbol?, ?region: Symbol?) -> Hash[String, Array[String]]
+  def self.make_options: (?kind: Symbol?, ?region: Symbol?, ?country: untyped) -> Array[[String, String]]
+  def self.model_options: (untyped make, ?kind: Symbol?, ?body_type: Symbol?, ?country: untyped) -> Array[[String, String]]
+  def self.catalog: (?kind: Symbol?, ?region: Symbol?, ?country: untyped, ?kinds: Array[Symbol]?) -> Hash[String, Array[String]]
+  def self.dataset_slice: (?kind: Symbol?, ?region: Symbol?, ?country: untyped, ?kinds: Array[Symbol]?) -> Hash[String, untyped]
 
-  def self.colors: () -> Array[Color]
-  def self.color: (untyped query) -> Color?
-  def self.color_options: () -> Array[[String, String]]
+  def self.colors: (?locale: untyped) -> Array[Color]
+  def self.color: (untyped query, ?locale: untyped) -> Color?
+  def self.color_options: (?locale: untyped) -> Array[[String, String]]
+  def self.kind_label: (untyped kind, ?locale: untyped) -> String?
+  def self.kind_options: (?locale: untyped, ?kinds: Array[Symbol]) -> Array[[String, String]]
+  def self.body_type_label: (untyped body_type, ?locale: untyped) -> String?
+  def self.body_type_options: (?locale: untyped) -> Array[[String, String]]
 
   def self.dataset: () -> Dataset
   def self.data_path: () -> String
   def self.data_path=: (String) -> void
   def self.active_data_path: () -> String
+  def self.refresh: () -> RefreshResult
   def self.refresh!: () -> bool
   def self.reload!: () -> void
   def self.normalize: (untyped str) -> String
@@ -53,6 +62,43 @@ module Vehicles
     attr_accessor refresh_timeout: Integer
     attr_accessor plate_template_cache: untyped
     attr_accessor plate_template_ttl: Integer
+    attr_accessor manifest_url: String?
+    attr_accessor cache_dir: String
+    attr_accessor reload_check_interval: Numeric?
+    attr_accessor refresh_min_ratio: Float?
+    attr_accessor refresh_guard: (^(Dataset, Dataset) -> boolish)?
+    attr_accessor on_hosted_error: (^(HostedResult) -> void)?
+    attr_accessor image_cache: untyped
+    attr_accessor image_cache_ttl: Integer
+    attr_accessor image_miss_ttl: Integer
+  end
+
+  class RefreshResult
+    attr_reader status: Symbol
+    attr_reader reason: Symbol?
+    attr_reader version: String?
+    attr_reader previous_version: String?
+    attr_reader detail: String?
+    def ok?: () -> bool
+    def updated?: () -> bool
+    def message: () -> String
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class HostedResult
+    attr_reader reason: Symbol
+    attr_reader status: Integer?
+    attr_reader error: String?
+    attr_reader payload: Hash[String, untyped]?
+    attr_reader path: String?
+    def ok?: () -> bool
+    def cached?: () -> bool
+    def url: (?Symbol size) -> String?
+    def to_error: () -> HostedError
+  end
+
+  class HostedError < StandardError
+    attr_accessor result: HostedResult
   end
 
   module Plates
@@ -77,7 +123,8 @@ module Vehicles
     attr_reader aliases: Array[String]
     attr_reader kinds: Array[Symbol]
     def models: (?kind: Symbol?, ?body_type: Symbol?) -> Array[Model]
-    def model: (untyped query, ?kind: Symbol?) -> Model?
+    attr_reader former_slugs: Array[String]
+    def model: (untyped query, ?kind: Symbol?, ?kinds: Array[Symbol]?) -> Model?
     def model_names: (?kind: Symbol?, ?body_type: Symbol?) -> Array[String]
     def model_options: (?kind: Symbol?, ?body_type: Symbol?) -> Array[[String, String]]
     def to_h: () -> Hash[Symbol, untyped]
@@ -91,6 +138,7 @@ module Vehicles
     attr_reader via: Array[String]
     attr_reader candidates: Array[Model]
     def ambiguous?: () -> bool
+    def confident?: () -> bool
     def to_h: () -> Hash[Symbol, untyped]
   end
 
@@ -98,6 +146,7 @@ module Vehicles
     attr_reader slug: String
     attr_reader name: String
     attr_reader hex: String
+    def label: (?untyped locale) -> String
     def to_h: () -> Hash[Symbol, String]
   end
 
@@ -111,6 +160,9 @@ module Vehicles
     attr_reader body_type: Symbol
     attr_reader aliases: Array[String]
     attr_reader forms: Array[String]
+    attr_reader id: String
+    attr_reader former_ids: Array[String]
+    attr_reader registration_years: { first: Integer, last: Integer }?
     def full_name: () -> String
     def to_s: () -> String
     def slug: () -> String
@@ -122,6 +174,8 @@ module Vehicles
     def hatchback?: () -> bool
     def years: () -> Range[Integer]?
     def segment: () -> Symbol?
-    def image: (?year: Integer?, ?color: untyped) -> String?
+    def image: (?year: Integer?, ?color: untyped, ?size: Symbol, ?exact_color: bool) -> String?
+    def images: (?color: untyped, ?year: Integer?, ?exact_color: bool) -> Hash[String, untyped]?
+    def images_result: (?color: untyped, ?year: Integer?, ?exact_color: bool) -> HostedResult
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: vehicles
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-11-09 00:00:00.000000000 Z
+date: 2026-11-11 00:00:00.000000000 Z
 dependencies: []
 description: vehicles ships a curated, bundled dataset of car makes and models (with
   kind and body type) and a delightful, Rails-friendly API for vehicle dropdowns,
@@ -96,6 +96,7 @@ files:
 - data/plates/de.yml
 - data/plates/dk.yml
 - data/plates/ee.yml
+- data/plates/eg.yml
 - data/plates/es.yml
 - data/plates/fi.yml
 - data/plates/fr.yml
@@ -117,6 +118,7 @@ files:
 - data/plates/mt.yml
 - data/plates/mx.yml
 - data/plates/my.yml
+- data/plates/ng.yml
 - data/plates/nl.yml
 - data/plates/no.yml
 - data/plates/nz.yml
@@ -128,6 +130,7 @@ files:
 - data/plates/sk.yml
 - data/plates/sm.yml
 - data/plates/th.yml
+- data/plates/tr.yml
 - data/plates/ua.yml
 - data/plates/us-ak.yml
 - data/plates/us-al.yml
@@ -196,10 +199,16 @@ files:
 - lib/vehicles/color.rb
 - lib/vehicles/colors.rb
 - lib/vehicles/configuration.rb
+- lib/vehicles/data_source.rb
 - lib/vehicles/dataset.rb
 - lib/vehicles/dataset_resolution.rb
+- lib/vehicles/dataset_slice.rb
 - lib/vehicles/fuzzy.rb
+- lib/vehicles/hosted_result.rb
 - lib/vehicles/http.rb
+- lib/vehicles/id_lookup.rb
+- lib/vehicles/kind_rule.rb
+- lib/vehicles/labels.rb
 - lib/vehicles/make.rb
 - lib/vehicles/mcp_server.rb
 - lib/vehicles/model.rb
@@ -214,7 +223,9 @@ files:
 - lib/vehicles/providers/hosted_provider.rb
 - lib/vehicles/providers/local_provider.rb
 - lib/vehicles/railtie.rb
+- lib/vehicles/refresh_result.rb
 - lib/vehicles/refresher.rb
+- lib/vehicles/release_checks.rb
 - lib/vehicles/text_matcher.rb
 - lib/vehicles/validators/vehicle_make_validator.rb
 - lib/vehicles/validators/vehicle_model_validator.rb