vehicles 0.9.0 → 0.9.2

data/lib/generators/vehicles/templates/initializer.rb

@@ -6,16 +6,21 @@
 # dataset, so it works with zero configuration. Uncomment what you need.
 
 Vehicles.configure do |config|
-  # Default region for queries. Today the bundled data covers the EU market;
-  # :us / :gb / :au / :nz / :ca packs are on the roadmap (the API is already
-  # region-aware, so adding them won't change your code).
+  # Optional default CONTINENT filter (:eu/:na/:as/:sa/:oc/:af). The bundled
+  # data is global; nil (the default) means every market. For one COUNTRY,
+  # pass `country:` where you build pickers: Vehicles.catalog(kind: :car, country: :es).
   # config.region = :eu
 
-  # Optional: a VehiclesDB API key unlocks hosted enrichment — production years,
-  # model images (year- and color-accurate), and market segments — on the same
-  # Vehicles::Model objects you already use. Without a key, everything still
-  # works on the bundled data; those richer fields just return nil.
+  # Optional: a VehiclesDB API key unlocks studio model images
+  # (`model.image(color: "red")`) on the same Vehicles::Model objects you already
+  # use. Without a key, everything still works on the bundled data; images are nil.
   # config.api_key = ENV["VEHICLESDB_API_KEY"]
+  #
+  # Image payloads are cached (in-process by default); share them across
+  # processes with Rails.cache. Hosted failures (bad key, out of credits, rate
+  # limited, timeouts) are never raised: report them here.
+  # config.image_cache = Rails.cache
+  # config.on_hosted_error = ->(result) { Rails.error.report(result.to_error, handled: true) }
 
   # Optional: your own make aliases, merged over the built-ins. Matched
   # forgivingly (case/diacritics-insensitive).
@@ -30,11 +35,15 @@ Vehicles.configure do |config|
 
   # --- Data refresh (optional) ----------------------------------------------
   # The gem works offline with its bundled snapshot. To get data fixes and new
-  # makes WITHOUT upgrading the gem, schedule VehiclesRefreshJob (see app/jobs)
-  # — it pulls the latest published dataset into a local cache, which loads
-  # prefer over the bundled copy. Defaults below are sensible; override if needed.
+  # makes WITHOUT upgrading the gem, schedule VehiclesRefreshJob (see app/jobs).
+  # It writes a checked release to `cache_path`; every process serves it once
+  # it is newer than the bundled data, re-checking the file every few seconds.
+  #
+  # Web and jobs in separate containers (Kamal, Docker)? Point both at ONE
+  # shared volume so a refresh run by the job container reaches the web one:
+  # config.cache_dir = Rails.root.join("storage", "vehicles")  # or ENV VEHICLES_CACHE_DIR
   #
-  # config.data_url   = "https://cdn.jsdelivr.net/gh/vehiclesdb/vehiclesdb@latest/dist/vehicles.json"
-  # config.cache_path = Rails.root.join("tmp", "cache", "vehicles", "vehicles.json")
   # config.use_cache  = true   # set false to always use the bundled snapshot (fully offline/deterministic)
+  # config.refresh_min_ratio = 0.9  # refuse a release that shrinks a kind or a country below 90%
+  # config.refresh_guard = ->(new_data, current) { true } # your own last check (Vehicles::Dataset objects)
 end

data/lib/generators/vehicles/templates/vehicles_refresh_job.rb

@@ -8,13 +8,17 @@
 #     class: VehiclesRefreshJob
 #     schedule: every day at 3am
 #
-# It's safe to run anytime: it never raises, and a failed/partial download leaves
-# your current data untouched (the gem keeps serving the cache, or the bundled
-# snapshot if there's no cache yet).
+# Safe to run anytime and from ONE place: it reads the release manifest first
+# (nothing is downloaded when you are current), never downgrades, never writes
+# a release your gem version cannot read or one that lost a chunk of your data,
+# and never raises. Every process (web workers, other containers sharing
+# `config.cache_dir`) picks the new file up on its own within a few seconds.
 class VehiclesRefreshJob < ApplicationJob
   queue_as :default
 
   def perform
-    Vehicles.refresh!
+    # Vehicles.refresh! (true/false) works too; the result says why.
+    result = Vehicles.refresh
+    Rails.logger.warn("[vehicles] #{result.message}") unless result.ok?
   end
 end

data/lib/vehicles/color.rb

@@ -5,7 +5,8 @@ module Vehicles
   # palette every consumer (and, in time, the hosted VehiclesDB image API) can
   # share, so "red" means the same thing — and maps to the same image variant —
   # everywhere. Display names are English; localize in your app (the slug is the
-  # stable, locale-independent key you store). `hex` is a representative swatch
+  # stable, locale-independent key you store; `label(:es)` gives the Spanish
+  # one). `hex` is a representative swatch
   # for UI chips / future color-accurate imagery.
   class Color
     attr_reader :slug, :name, :hex
@@ -17,6 +18,12 @@ module Vehicles
       freeze
     end
 
+    # The display label in a locale (:en, :es; others fall back to English).
+    #   Vehicles.color("red").label(:es)  # => "Rojo"
+    def label(locale = :en)
+      Labels.color(slug, locale) || name
+    end
+
     def to_h
       { slug: slug, name: name, hex: hex }
     end

data/lib/vehicles/colors.rb

@@ -24,18 +24,22 @@ module Vehicles
       Color.new("other",  "Other",  "#9AA0A6")
     ].freeze
 
-    # Accept a few common spellings/synonyms so lookups are forgiving like the
-    # rest of the gem (normalized keys → canonical slug).
-    SYNONYMS = {
-      "gray" => "grey",
-      "silvery" => "silver",
-      "tan" => "beige",
-      "cream" => "beige",
-      "burgundy" => "red",
-      "navy" => "blue"
-    }.freeze
+    # English spellings/synonyms (normalized keys → canonical slug). Every
+    # locale's synonyms live in Labels::COLOR_SYNONYMS.
+    SYNONYMS = Labels::COLOR_SYNONYMS[:en]
 
     BY_SLUG = ALL.to_h { |c| [c.slug, c] }.freeze
     BY_NAME = ALL.to_h { |c| [Vehicles.normalize(c.name), c] }.freeze
+
+    # Every normalized label and synonym in every locale → Color, so "Rojo",
+    # "gris", "marrón", "plateada" and "navy" all resolve (Vehicles.color).
+    LOOKUP = begin
+      table = {}
+      Labels::LOCALES.each do |locale|
+        Labels::COLORS[locale].each { |slug, label| table[Vehicles.normalize(label)] ||= BY_SLUG[slug] }
+        Labels::COLOR_SYNONYMS[locale].each { |key, slug| table[Vehicles.normalize(key)] ||= BY_SLUG[slug] }
+      end
+      table.freeze
+    end
   end
 end

data/lib/vehicles/configuration.rb

@@ -38,7 +38,7 @@ module Vehicles
     # carry nothing personal, so a long TTL is safe; the server re-renders
     # them only when VehiclesDB's plate art changes.
     attr_writer :plate_template_cache
-    attr_accessor :plate_template_ttl
+    attr_accessor :plate_template_ttl, :image_cache_ttl, :image_miss_ttl
 
     def plate_template_cache
       @plate_template_cache ||= Plates::TemplateCache.new
@@ -64,10 +64,36 @@ module Vehicles
     # VehiclesDB data repo via jsDelivr's CDN (always-latest release tag).
     attr_accessor :data_url
 
+    # The release manifest `refresh` reads FIRST (version, schema, per-kind
+    # counts, checksum when published): a few KB that decide whether the
+    # 8 MB payload is worth downloading at all. Derived from `data_url`
+    # (".../dist/vehicles.json" → ".../manifest.json") until you set it; set
+    # nil for a self-hosted payload that has no manifest.
+    attr_writer :manifest_url
+
+    def manifest_url
+      return @manifest_url unless @manifest_url == :derived
+
+      url = data_url.to_s
+      url.match?(%r{/dist/[^/]+\.json\z}) ? url.sub(%r{/dist/[^/]+\.json\z}, "/manifest.json") : nil
+    end
+
     # Where a refreshed dataset is cached on disk. Defaults to the app's cache dir
-    # (Rails) or the system temp dir. The refresh writes here; loads prefer it.
+    # (Rails) or the system temp dir — or to $VEHICLES_CACHE_DIR when set. The
+    # refresh writes here; every process serves it when it is usable (see
+    # Vehicles::DataSource). Several containers (web + jobs) share ONE refresh
+    # by pointing this at a shared volume: `config.cache_dir = "/rails/storage/vehicles"`.
     attr_accessor :cache_path
 
+    # Directory form of `cache_path` (the file is <dir>/vehicles.json).
+    def cache_dir=(dir)
+      @cache_path = File.join(dir.to_s, "vehicles.json")
+    end
+
+    def cache_dir
+      File.dirname(cache_path.to_s)
+    end
+
     # Prefer a refreshed (cached) dataset over the bundled one when present.
     # Set false to always use the bundled snapshot (fully offline/deterministic).
     attr_accessor :use_cache
@@ -75,6 +101,48 @@ module Vehicles
     # Network timeout (seconds) for a refresh download.
     attr_accessor :refresh_timeout
 
+    # How often (seconds) a process checks whether the dataset file changed
+    # (one File.stat), so a refresh made by ANY process or container reaches
+    # it without a restart. nil = never (only `Vehicles.reload!`).
+    attr_accessor :reload_check_interval
+
+    # A release is refused when any kind, or any (kind, country) slice with at
+    # least 25 models, would shrink below this share of the data in use.
+    # nil disables the check.
+    attr_accessor :refresh_min_ratio
+
+    # Optional last word on a release: ->(candidate, current) { … } with two
+    # Vehicles::Dataset objects; falsy refuses it. Runs after every built-in
+    # check, e.g. "Spain's cars must not shrink":
+    #   config.refresh_guard = ->(new, old) {
+    #     new.top_models(kind: :car, country: :es, limit: nil).size >=
+    #       old.top_models(kind: :car, country: :es, limit: nil).size
+    #   }
+    attr_accessor :refresh_guard
+
+    # --- hosted API (optional) -----------------------------------------------
+
+    # Called with a Vehicles::HostedResult whenever a hosted call fails
+    # (401/402/403/429, 5xx, timeout, network…; not for a plain "no image"
+    # 404). Use it to report to your error tracker. Never allowed to raise
+    # into your page: its own errors are swallowed.
+    #   config.on_hosted_error = ->(r) { Rails.error.report(r.to_error, handled: true) }
+    attr_accessor :on_hosted_error
+
+    # Image payloads are cached so a page view does not pay per image: any
+    # store with read(key) / write(key, value, expires_in:) (Rails.cache
+    # shares it across processes). In-process by default; false disables.
+    # A hit is kept `image_cache_ttl` seconds (capped by the payload's
+    # `expires_at` when the API sends one), a definitive miss (404)
+    # `image_miss_ttl`. Errors (401/402/429/timeouts) are never cached.
+    attr_writer :image_cache
+
+    def image_cache
+      return nil if @image_cache == false
+
+      @image_cache ||= Plates::TemplateCache.new
+    end
+
     def initialize
       @region          = nil # no continent filter by default (global dataset)
       @api_key         = nil
@@ -86,6 +154,13 @@ module Vehicles
       @cache_path      = default_cache_path
       @use_cache       = true
       @refresh_timeout = 5
+      @manifest_url    = :derived
+      @reload_check_interval = 5
+      @refresh_min_ratio = 0.9
+      @refresh_guard   = nil
+      @on_hosted_error = nil
+      @image_cache_ttl = 86_400 # a day; variant URLs live ~30 days
+      @image_miss_ttl  = 600
       @plate_template_ttl = 86_400 # a day, the server's own shared-cache lifetime
     end
 
@@ -98,9 +173,13 @@ module Vehicles
 
     private
 
-    # tmp/cache/vehicles under a Rails app, else a stable spot in the system temp
+    # $VEHICLES_CACHE_DIR when set (a shared volume), else tmp/cache/vehicles
+    # under a Rails app, else a stable spot in the system temp
     # dir. Refreshable data, so a cache-style location is appropriate.
     def default_cache_path
+      shared = ENV["VEHICLES_CACHE_DIR"].to_s
+      return File.join(shared, "vehicles.json") unless shared.empty?
+
       base =
         if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
           Rails.root.join("tmp", "cache", "vehicles")

data/lib/vehicles/data_source.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Vehicles
+  # Which dataset file this process serves, and when it switches to another.
+  # Behind Vehicles.dataset; not called directly.
+  #
+  # The rules (0.9.2):
+  #   - an explicit `Vehicles.data_path=` always wins;
+  #   - otherwise a refreshed cache (`config.cache_path`) is served only when
+  #     it is USABLE: a schema this gem reads, and not older than the data
+  #     bundled in the gem. A cache an older gem left behind loses to a newer
+  #     gem's bundled data instead of silently downgrading it;
+  #   - every process notices a new file: at most every
+  #     `config.reload_check_interval` seconds (default 5) a call stats the
+  #     file in effect and the cache, and reloads when either changed. So a
+  #     refresh run by a job, another worker or another container (cache on a
+  #     shared volume) reaches every web worker without a restart or a hook;
+  #   - a file that cannot be read or parsed never replaces the dataset in
+  #     memory: the process keeps serving what it has.
+  module DataSource
+    class Error < StandardError; end
+
+    # Dataset `schema_version`s this gem reads. A payload or cache with any
+    # other schema is never loaded or promoted.
+    SCHEMA_VERSIONS = [2].freeze
+
+    # How much of a file's start holds "version"/"schema_version" (both open
+    # every dist/vehicles.json), so checking a file never parses 8 MB.
+    HEADER_BYTES = 4096
+
+    Snapshot = Struct.new(:path, :stamp, :dataset, :checked_at)
+
+    LOCK = Mutex.new
+
+    module_function
+
+    # The Dataset to serve now. Lock-free on the hot path; the stat check and
+    # any reload happen under LOCK, once, whoever gets there first.
+    def dataset
+      snap = @snapshot
+      return snap.dataset if snap && !due?(snap)
+
+      LOCK.synchronize { sync }
+    end
+
+    def reset!
+      LOCK.synchronize do
+        @snapshot = nil
+        @headers = nil
+        @unloadable = nil
+      end
+    end
+
+    # The file Vehicles.dataset loads (see the rules above).
+    def active_path
+      return Vehicles.data_path_override if Vehicles.data_path_override
+
+      cache = Vehicles.configuration.cache_path.to_s
+      return cache if Vehicles.configuration.use_cache && usable_cache?(cache)
+
+      Vehicles::DATA_PATH
+    end
+
+    # A cache file the gem may serve: present, a supported schema, a valid
+    # version, and not older than the bundled data.
+    def usable_cache?(path)
+      return false if path.empty? || !File.file?(path)
+
+      head = header(path)
+      bundled = header(Vehicles::DATA_PATH)
+      compatible?(head) && head[:version] >= bundled[:version]
+    end
+
+    # { version: Gem::Version or nil, schema_version: Integer or nil } of a
+    # dataset file, memoized per file stamp (a changed file is re-read).
+    def header(path)
+      stamp = stamp(path)
+      cached = (@headers ||= {})[path]
+      return cached[1] if cached && cached[0] == stamp
+
+      parsed = read_header(path)
+      @headers[path] = [stamp, parsed]
+      parsed
+    end
+
+    def compatible?(head)
+      SCHEMA_VERSIONS.include?(head[:schema_version]) && !head[:version].nil?
+    end
+
+    # "2026.11.2" → Gem::Version, or nil when it is not a version.
+    def version(str)
+      str = str.to_s
+      Gem::Version.correct?(str) && !str.empty? ? Gem::Version.new(str) : nil
+    end
+
+    # [mtime, size, inode] — a rename onto the path changes the inode, so a
+    # promoted file is noticed even within one mtime tick. nil when missing.
+    def stamp(path)
+      st = File.stat(path)
+      [st.mtime, st.size, st.ino]
+    rescue SystemCallError
+      nil
+    end
+
+    # The newest dataset this app already has: the bundled one, or a usable
+    # cache (whatever `use_cache` says — a refresh never writes an older file).
+    # (and, unless `data_path=` pins a file, the dataset this process keeps
+    # in memory: it never goes back to older data on its own).
+    def newest_version
+      bundled = header(Vehicles::DATA_PATH)[:version]
+      cache = Vehicles.configuration.cache_path.to_s
+      cached = usable_cache?(cache) ? header(cache)[:version] : nil
+      memory = Vehicles.data_path_override ? nil : version(Vehicles.dataset.version)
+      [bundled, cached, memory].compact.max
+    end
+
+    # The cache file when another process promoted something newer than what
+    # this process has loaded, else the dataset in memory.
+    def newest_dataset(path)
+      current = Vehicles.dataset
+      loaded = version(current.version)
+      return current unless usable_cache?(path)
+      return current if loaded && header(path)[:version] <= loaded
+
+      build(path)
+    end
+
+    # --- internals -----------------------------------------------------------
+
+    def due?(snap, now = clock)
+      interval = Vehicles.configuration.reload_check_interval
+      !interval.nil? && now - snap.checked_at >= interval.to_f
+    end
+
+    def sync
+      snap = @snapshot
+      now = clock
+      return snap.dataset if snap && !due?(snap, now)
+
+      path = active_path
+      stamp = stamp(path)
+      # Unchanged, the very file that already failed to load, or older than
+      # what is in memory (a cache deleted or replaced by an older/unreadable
+      # file): keep serving. Only `reload!` goes back to older data.
+      if snap && ((snap.path == path && snap.stamp == stamp) || @unloadable == [path, stamp] || older?(path, snap))
+        snap.checked_at = now
+        return snap.dataset
+      end
+
+      load_snapshot(path, stamp, now, snap)
+    end
+
+    def older?(path, snap)
+      candidate = header(path)[:version]
+      current = version(snap.dataset.version)
+      current && (candidate.nil? || candidate < current)
+    end
+
+    # Parse and fully build a dataset file, or raise: a file that parses but
+    # is not a whole dataset (no makes, a malformed model) must fail HERE,
+    # not later inside a request.
+    def build(path, previous = nil)
+      raw = JSON.parse(File.read(path))
+      raise Error, "#{path}: no makes" unless raw.is_a?(Hash) && raw["makes"].is_a?(Array) && raw["makes"].any?
+
+      # The header was checked on an earlier read; another process may have
+      # replaced the file since. Check what was actually parsed.
+      unless path == Vehicles::DATA_PATH || Vehicles.data_path_override
+        head = { version: version(raw["version"]), schema_version: raw["schema_version"] }
+        raise Error, "#{path}: unusable" unless compatible?(head) &&
+                                                head[:version] >= header(Vehicles::DATA_PATH)[:version]
+      end
+
+      if previous && !Vehicles.data_path_override && version(raw["version"]) < version(previous.version)
+        raise Error, "#{path}: older than the dataset in memory"
+      end
+
+      Dataset.new(raw).tap(&:all_models)
+    end
+
+    def load_snapshot(path, stamp, now, previous)
+      dataset = build(path, previous&.dataset)
+
+      if previous && previous.dataset.version != dataset.version
+        Vehicles.logger&.info("[vehicles] dataset #{previous.dataset.version} → #{dataset.version} (#{path})")
+      end
+      @snapshot = Snapshot.new(path, stamp, dataset, now)
+      dataset
+    rescue StandardError => e
+      raise if path == Vehicles::DATA_PATH && previous.nil? # the gem's own data: a packaging bug, say so
+
+      Vehicles.logger&.warn("[vehicles] could not load #{path} (#{e.class}); keeping the dataset in use")
+      @unloadable = [path, stamp]
+      if previous
+        previous.checked_at = now
+        previous.dataset
+      else
+        load_snapshot(Vehicles::DATA_PATH, stamp(Vehicles::DATA_PATH), now, nil)
+      end
+    end
+
+    def read_header(path)
+      head = File.open(path, "rb") { |f| f.read(HEADER_BYTES) }.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      version = head[/"version"\s*:\s*"([^"]*)"/, 1]
+      schema = head[/"schema_version"\s*:\s*(\d+)/, 1]
+      if version.nil? || schema.nil? # not at the top: read it the slow way
+        raw = JSON.parse(File.read(path))
+        version = raw["version"] if raw.is_a?(Hash)
+        schema = raw["schema_version"] if raw.is_a?(Hash)
+      end
+      { version: version(version), schema_version: schema&.to_i }
+    rescue StandardError
+      { version: nil, schema_version: nil }
+    end
+
+    def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/vehicles/dataset.rb

@@ -37,12 +37,16 @@ module Vehicles
       end
     end
 
-    attr_reader :version, :schema_version, :region
+    attr_reader :version, :schema_version, :region, :license, :attribution
 
     def initialize(raw)
       @version        = raw["version"]
       @schema_version = raw["schema_version"]
       @region         = raw["region"]
+      # The licence id and the credit block the release publishes (CC-BY
+      # 4.0), carried into Vehicles.dataset_slice so a slice keeps them.
+      @license        = raw["license"]
+      @attribution    = raw["attribution"]
 
       # Name-alphabetical, diacritic-insensitive — the dataset file arrives
       # slug-sorted, which differs subtly ("Austin-Healey" vs "Austin Morris").
@@ -61,6 +65,12 @@ module Vehicles
           @exact[a.downcase] ||= make
         end
       end
+      index_former_slugs
+    end
+
+    # The make that now carries a retired make slug ("mg-roewe" → MG), or nil.
+    def make_by_former_slug(slug)
+      @by_former_slug[slug.to_s]
     end
 
     # All makes, optionally filtered by kind and/or continent. `region:` is a
@@ -69,10 +79,11 @@ module Vehicles
     # this?"; on today's global snapshot both readings return European makes
     # for `region: :eu`, so existing callers are unaffected.) An unmapped
     # continent honestly returns [].
-    def makes(kind: nil, region: nil)
+    def makes(kind: nil, region: nil, country: nil)
       list = @makes
       list = list.select { |m| m.kinds.include?(kind.to_sym) } if kind
       list = list.select { |m| m.in_region?(region) }          if region
+      list = list.select { |m| m.available_in?(country, kind: kind) } if country
       list
     end
 
@@ -152,6 +163,11 @@ module Vehicles
       @all_models ||= @makes.flat_map(&:models).freeze
     end
 
+    # Continent codes present in the snapshot. => [:af, :as, :eu, ...]
+    def regions
+      @regions ||= all_models.flat_map(&:regions).uniq.sort.freeze
+    end
+
     # Every kind present in the snapshot. => [:bus, :car, :moped, ...]
     def kinds
       @kinds ||= @makes.flat_map(&:kinds).uniq.sort.freeze
@@ -178,6 +194,7 @@ module Vehicles
     # chosen decile only breaks ties among models ranked equally there.
     #   top_models(kind: :car, by: :mass_decile, limit: 10)
     #   top_models(kind: :motorcycle, region: :as, limit: 10)  # by continent
+    # `limit: nil` returns every match.
     def top_models(kind: nil, country: nil, region: nil, limit: 20, by: :global_decile)
       raise ArgumentError, "by: must be :global_decile or :mass_decile" unless RANKINGS.include?(by)
 
@@ -186,14 +203,17 @@ module Vehicles
       list = list.select { |m| m.kind == kind.to_sym } if kind
       list = list.select { |m| m.availability.include?(c) } if c
       list = list.select { |m| m.available_in_region?(region) } if region
-      list.sort_by do |m|
-        rank = c && m.rank_in(c)
-        [rank ? 0 : 1, rank || 0, m.public_send(by), -m.availability.size, m.name]
-      end.first(limit)
+      sorted = list.sort_by { |m| popularity_key(m, c, by) }
+      limit ? sorted.first(limit) : sorted
     end
 
     RANKINGS = %i[global_decile mass_decile].freeze
 
+    def popularity_key(model, country, by)
+      rank = country && model.rank_in(country)
+      [rank ? 0 : 1, rank || 0, model.public_send(by), -model.availability.size, model.name]
+    end
+
     # Every model matching optional kind/region/rarity filters, ranked by
     # popularity. The "give me a sensible slice" entry point.
     def all_models_filtered(kind: nil, region: nil, rarity: nil, max_decile: nil)
@@ -214,6 +234,18 @@ module Vehicles
 
     private
 
+    # Former make slugs (a renamed or merged make) answer last: a current
+    # name, slug or alias always wins over a retired slug.
+    def index_former_slugs
+      @by_former_slug = {}
+      @makes.each do |make|
+        make.former_slugs.each do |old|
+          @by_former_slug[old] ||= make
+          index(old, make)
+        end
+      end
+    end
+
     def index(key, make)
       @index[Vehicles.normalize(key)] ||= make
     end

data/lib/vehicles/dataset_resolution.rb

@@ -21,12 +21,48 @@ module Vehicles
     end
 
     # Records ("make/model" slugs, any make) NAMED this (normalized).
-    def records_named(key)
-      resolution_index[:name][key] || []
+    # `kinds` (a list, or nil for any) limits which records count.
+    def records_named(key, kinds = nil)
+      (resolution_index[:name][key] || []).select { |m| KindRule.allows?(kinds, m) }
+                                          .map { |m| "#{m.make_slug}/#{m.model_slug}" }.uniq
+    end
+
+    # The `via` step for a make reached through something other than its own
+    # name or slug: a retired make slug (`former_make_slug:old→new`,
+    # RESOLUTION.md) or an alias (`make_alias:key→slug`).
+    def make_step(make, key)
+      old = key.tr(" ", "-")
+      return "former_make_slug:#{old}→#{make.slug}" if make_by_former_slug(old).equal?(make)
+
+      "make_alias:#{key}→#{make.slug}"
+    end
+
+    # The live Model a retired id now answers to (Vehicles.by_id), or nil:
+    #   1. the record that lists the id in `former_ids` (one record; its kind
+    #      variant of the id's kind, else the collision rule);
+    #   2. failing that, the make's new slug (make `former_slugs`): the same
+    #      model slug under it, exactly or through ITS former ids.
+    def successor_of(id)
+      found = absorbed(id)
+      return found if found
+
+      kind, make_slug, model_slug = id.to_s.split("/", 3)
+      return nil unless model_slug && (make = make_by_former_slug(make_slug))
+
+      moved = "#{kind}/#{make.slug}/#{model_slug}"
+      models_by_id(moved).first || absorbed(moved)
     end
 
     private
 
+    def absorbed(id)
+      hits = models_by_former_id(id)
+      return nil if hits.empty? || hits.map { |m| [m.make_slug, m.model_slug] }.uniq.size > 1
+
+      kind = id.to_s.split("/", 2).first
+      hits.find { |m| m.kind.to_s == kind } || KindRule.pick(hits)
+    end
+
     # Built once on first use; arrays keep dataset order.
     def resolution_index
       @resolution_index ||= begin
@@ -44,7 +80,7 @@ module Vehicles
         key = Vehicles.normalize(a)
         (idx[:alias][key] ||= []) << model unless key.empty?
       end
-      (idx[:name][Vehicles.normalize(model.name)] ||= []) << record
+      (idx[:name][Vehicles.normalize(model.name)] ||= []) << model
     end
   end
 end