@meterapp/vehicle-db 2.11.0 → 2.13.0

package/dist/identity-data.d.ts

@@ -0,0 +1,3 @@
+import type { IdentityGraph } from "./identity";
+declare const graph: IdentityGraph;
+export default graph;

package/dist/identity-data.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const graph = { "schemaVersion": 1, "revision": "2026-09-24.1", "identities": [{ "id": "bmw:4", "kind": "line", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series", "names": ["4 Series"], "evidenceIds": ["oem:1"] }, { "id": "bmw:4:first", "kind": "generation", "makeId": 452, "vehicleTypeId": 2, "name": "First generation", "names": [], "evidenceIds": ["oem:3"], "parentId": "bmw:4", "years": [2014], "yearBasis": "model-year", "markets": ["US"] }, { "id": "bmw:4:second", "kind": "generation", "makeId": 452, "vehicleTypeId": 2, "name": "Second generation", "names": [], "evidenceIds": ["oem:1"], "parentId": "bmw:4", "years": [2024, 2025], "yearBasis": "model-year", "markets": ["US"] }, { "id": "kia:pegas", "kind": "line", "makeId": 499, "vehicleTypeId": 2, "name": "Pegas", "names": ["Pegas"], "evidenceIds": ["oem:0"], "years": [2025], "yearBasis": "model-year", "markets": ["SA"] }, { "id": "bmw:4:second:coupe", "kind": "derivative", "makeId": 452, "vehicleTypeId": 2, "name": "Coupe", "names": ["4 Series Coupe"], "evidenceIds": ["oem:1", "oem:5"], "years": [2025, 2024], "yearBasis": "model-year", "markets": ["US"], "bodyStyle": "Coupe", "parentId": "bmw:4:second" }, { "id": "bmw:4:second:coupe:2025", "kind": "visual", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series Coupe 2025", "names": [], "evidenceIds": ["oem:1", "oem:5"], "years": [2025], "yearBasis": "model-year", "markets": ["US"], "appearanceRevision": "facelift", "parentId": "bmw:4:second:coupe" }, { "id": "bmw:4:second:convertible", "kind": "derivative", "makeId": 452, "vehicleTypeId": 2, "name": "Convertible", "names": ["4 Series Convertible"], "evidenceIds": ["oem:2", "oem:6"], "years": [2025, 2024], "yearBasis": "model-year", "markets": ["US"], "bodyStyle": "Convertible", "parentId": "bmw:4:second" }, { "id": "bmw:4:second:convertible:2025", "kind": "visual", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series Convertible 2025", "names": [], "evidenceIds": ["oem:2", "oem:6"], "years": [2025], "yearBasis": "model-year", "markets": ["US"], "appearanceRevision": "facelift", "parentId": "bmw:4:second:convertible" }, { "id": "bmw:4:first:coupe", "kind": "derivative", "makeId": 452, "vehicleTypeId": 2, "name": "Coupe", "names": ["4 Series Coupe"], "evidenceIds": ["oem:3"], "years": [2014], "yearBasis": "model-year", "markets": ["US"], "bodyStyle": "Coupe", "parentId": "bmw:4:first" }, { "id": "bmw:4:first:coupe:2014", "kind": "visual", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series Coupe 2014", "names": [], "evidenceIds": ["oem:3"], "years": [2014], "yearBasis": "model-year", "markets": ["US"], "appearanceRevision": "original", "parentId": "bmw:4:first:coupe" }, { "id": "lamborghini:huracan", "kind": "line", "makeId": 502, "vehicleTypeId": 2, "name": "Huracán", "names": ["Huracan"], "evidenceIds": ["oem:4"] }, { "id": "lamborghini:huracan:first", "kind": "generation", "makeId": 502, "vehicleTypeId": 2, "name": "Huracán generation", "names": [], "evidenceIds": ["oem:4"], "parentId": "lamborghini:huracan" }, { "id": "lamborghini:huracan:sto", "kind": "derivative", "makeId": 502, "vehicleTypeId": 2, "name": "STO", "names": ["Huracan STO"], "evidenceIds": ["oem:4"], "years": [2023], "yearBasis": "model-year", "markets": ["US"], "bodyStyle": "Coupe", "parentId": "lamborghini:huracan:first" }, { "id": "lamborghini:huracan:sto:2023", "kind": "visual", "makeId": 502, "vehicleTypeId": 2, "name": "STO exterior", "names": [], "evidenceIds": ["oem:4"], "years": [2023], "yearBasis": "model-year", "markets": ["US"], "parentId": "lamborghini:huracan:sto" }, { "id": "bmw:4:second:coupe:2024", "kind": "visual", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series Coupe 2024", "names": [], "evidenceIds": ["oem:5"], "years": [2024], "yearBasis": "model-year", "markets": ["US"], "appearanceRevision": "original", "parentId": "bmw:4:second:coupe" }, { "id": "bmw:4:second:convertible:2024", "kind": "visual", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series Convertible 2024", "names": [], "evidenceIds": ["oem:6"], "years": [2024], "yearBasis": "model-year", "markets": ["US"], "appearanceRevision": "original", "parentId": "bmw:4:second:convertible" }, { "id": "bmw:4:second:gran-coupe", "kind": "derivative", "makeId": 452, "vehicleTypeId": 2, "name": "Gran Coupe", "names": ["4 Series Gran Coupe"], "evidenceIds": ["oem:7"], "years": [2024], "yearBasis": "model-year", "markets": ["US"], "bodyStyle": "Gran Coupe", "parentId": "bmw:4:second" }, { "id": "bmw:4:second:gran-coupe:2024", "kind": "visual", "makeId": 452, "vehicleTypeId": 2, "name": "4 Series Gran Coupe 2024", "names": [], "evidenceIds": ["oem:7"], "years": [2024], "yearBasis": "model-year", "markets": ["US"], "appearanceRevision": "original", "parentId": "bmw:4:second:gran-coupe" }, { "id": "porsche:macan", "kind": "line", "makeId": 584, "vehicleTypeId": 7, "name": "Macan", "names": ["Macan"], "evidenceIds": ["porsche:macan-name"] }, { "id": "toyota:prado", "kind": "line", "makeId": 448, "vehicleTypeId": 7, "name": "Land Cruiser Prado", "names": ["Land Cruiser Prado"], "evidenceIds": ["toyota:prado-name"] }], "aliases": [{ "text": "maccane", "targetId": "porsche:macan", "kind": "misspelling", "evidenceIds": ["porsche:macan-name"] }, { "text": "Prado", "targetId": "toyota:prado", "kind": "abbreviation", "evidenceIds": ["toyota:prado-name"] }], "catalogLinks": [{ "identityId": "kia:pegas", "year": 2025, "makeId": 499, "modelId": 2554132110, "vehicleTypeId": 2, "evidenceIds": ["oem:0"] }, { "identityId": "bmw:4:second:coupe", "year": 2025, "makeId": 452, "modelId": 1126006782, "vehicleTypeId": 2, "evidenceIds": ["oem:1", "oem:5"] }, { "identityId": "bmw:4:second:convertible", "year": 2025, "makeId": 452, "modelId": 2953619411, "vehicleTypeId": 2, "evidenceIds": ["oem:2", "oem:6"] }, { "identityId": "bmw:4:first:coupe", "year": 2014, "makeId": 452, "modelId": 1126006782, "vehicleTypeId": 2, "evidenceIds": ["oem:3"] }, { "identityId": "lamborghini:huracan:sto", "year": 2023, "makeId": 502, "modelId": 1352298313, "vehicleTypeId": 2, "evidenceIds": ["oem:4"] }, { "identityId": "bmw:4:second:coupe", "year": 2024, "makeId": 452, "modelId": 1126006782, "vehicleTypeId": 2, "evidenceIds": ["oem:5"] }, { "identityId": "bmw:4:second:convertible", "year": 2024, "makeId": 452, "modelId": 2953619411, "vehicleTypeId": 2, "evidenceIds": ["oem:6"] }, { "identityId": "bmw:4:second:gran-coupe", "year": 2024, "makeId": 452, "modelId": 2889216836, "vehicleTypeId": 2, "evidenceIds": ["oem:7"] }, { "identityId": "porsche:macan", "year": 2015, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2016, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2017, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2018, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2019, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2020, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2021, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2022, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2023, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2024, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2025, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2026, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "porsche:macan", "year": 2027, "makeId": 584, "modelId": 8031, "vehicleTypeId": 7, "evidenceIds": ["porsche:macan-name"] }, { "identityId": "toyota:prado", "year": 2015, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2016, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2017, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2018, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2019, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2020, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2021, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2022, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2023, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2024, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2025, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }, { "identityId": "toyota:prado", "year": 2026, "makeId": 448, "modelId": 4481618588, "vehicleTypeId": 7, "evidenceIds": ["toyota:prado-name"] }], "evidence": [{ "id": "oem:0", "sourceId": "manufacturer-reviewed", "url": "https://www.kia.com/content/dam/kwcms/sa/en/files/trim/Pegas/LX-D389.pdf", "retrievedAt": "2026-09-24", "note": "Manufacturer specification explicitly labels Pegas 2025 MY; Saudi distributor Aljabr." }, { "id": "oem:1", "sourceId": "manufacturer-reviewed", "url": "https://www.press.bmwgroup.com/usa/article/detail/T0439311EN_US/the-new-2025-bmw-4-series-coupe-and-convertible", "retrievedAt": "2026-09-24", "note": "BMW USA explicitly identifies 2025 model year and the two body derivatives; facelift, not a new generation." }, { "id": "oem:2", "sourceId": "manufacturer-reviewed", "url": "https://www.press.bmwgroup.com/usa/article/detail/T0439311EN_US/the-new-2025-bmw-4-series-coupe-and-convertible", "retrievedAt": "2026-09-24", "note": "BMW USA explicitly identifies 2025 model year and the two body derivatives; facelift, not a new generation." }, { "id": "oem:3", "sourceId": "manufacturer-reviewed", "url": "https://www.press.bmwgroup.com/usa/article/detail/T0142773EN_US/the-all-new-bmw-4-series-coupe", "retrievedAt": "2026-09-24", "note": "BMW USA introduces the first-generation Coupe as model year 2014." }, { "id": "oem:4", "sourceId": "manufacturer-reviewed", "url": "https://preowned.lamborghini.com/en_gb/vdp/30004705-2023-Hurac%C3%A1n-EVO-LP-640-2-STO", "retrievedAt": "2026-09-24", "note": "Lamborghini official pre-owned US dealer listing explicitly identifies model year 2023 STO; no VIN or individual vehicle data retained." }, { "id": "oem:5", "sourceId": "manufacturer-reviewed", "url": "https://bmwtechinfo.bmwgroup.com/sib_attachments/B000223%20Attachment%205%202024%20BMW%20Group%20models%20reference%20guide%209_23.pdf", "retrievedAt": "2026-09-24", "note": "BMW model-year 2024 reference guide lists G22 Coupe, G23 Convertible, and G26 Gran Coupe separately." }, { "id": "oem:6", "sourceId": "manufacturer-reviewed", "url": "https://bmwtechinfo.bmwgroup.com/sib_attachments/B000223%20Attachment%205%202024%20BMW%20Group%20models%20reference%20guide%209_23.pdf", "retrievedAt": "2026-09-24", "note": "BMW model-year 2024 reference guide lists G22 Coupe, G23 Convertible, and G26 Gran Coupe separately." }, { "id": "oem:7", "sourceId": "manufacturer-reviewed", "url": "https://bmwtechinfo.bmwgroup.com/sib_attachments/B000223%20Attachment%205%202024%20BMW%20Group%20models%20reference%20guide%209_23.pdf", "retrievedAt": "2026-09-24", "note": "BMW model-year 2024 reference guide lists G22 Coupe, G23 Convertible, and G26 Gran Coupe separately." }, { "id": "porsche:macan-name", "sourceId": "porsche-catalog", "url": "https://www.porsche.com/usa/models/macan/", "retrievedAt": "2026-09-24", "note": "Macan name evidence. Reviewed maccane spelling correction is lexical only and does not choose gasoline/electric generation." }, { "id": "toyota:prado-name", "sourceId": "toyota-catalog", "url": "https://www.toyota.com.au/prado", "retrievedAt": "2026-09-24", "note": "Toyota uses both Prado and LandCruiser Prado for the model line. No mapping to other Land Cruiser lines or generations." }], "homologation": [], "visualCompatibility": [] };
+exports.default = graph;

package/dist/identity.d.ts

@@ -0,0 +1,93 @@
+/** Portable identities. These IDs never replace published numeric catalog IDs. */
+export type IdentityKind = "line" | "generation" | "derivative" | "specification" | "visual";
+export type YearBasis = "model-year" | "manufacture-year" | "registration-year" | "first-admission-year";
+export interface IdentityScope {
+    years?: number[];
+    markets?: string[];
+    yearBasis?: YearBasis;
+}
+export interface IdentityEvidence {
+    id: string;
+    sourceId: string;
+    url: string;
+    retrievedAt: string;
+    note: string;
+}
+export interface VehicleIdentity extends IdentityScope {
+    id: string;
+    kind: IdentityKind;
+    makeId: number;
+    vehicleTypeId: number;
+    name: string;
+    /** Full model phrases, excluding make/year. No suffix stripping is implied. */
+    names: string[];
+    parentId?: string;
+    codes?: string[];
+    bodyStyle?: string;
+    appearanceRevision?: string;
+    specification?: {
+        trim?: string;
+        powertrain?: string;
+        engine?: string;
+        drivetrain?: string;
+        transmission?: string;
+        rawText: string;
+    };
+    evidenceIds: string[];
+}
+export interface VehicleIdentityAlias extends IdentityScope {
+    text: string;
+    targetId: string;
+    kind: "marketing-name" | "regional-name" | "translation" | "abbreviation" | "misspelling";
+    evidenceIds: string[];
+}
+export interface IdentityCatalogLink {
+    identityId: string;
+    year: number;
+    makeId: number;
+    modelId: number;
+    vehicleTypeId: number;
+    evidenceIds: string[];
+}
+export interface VisualCompatibility extends IdentityScope {
+    id: string;
+    requestedVisualIdentityId: string;
+    assetVisualIdentityId: string;
+    decision: "allow" | "deny";
+    evidenceIds: string[];
+    rationale: string;
+    reviewedBy: string;
+    reviewedAt: string;
+    revision: string;
+}
+export interface HomologationIdentity {
+    id: string;
+    sourceId: string;
+    market: string;
+    approvalNumber?: string;
+    type?: string;
+    variant?: string;
+    version?: string;
+    derivativeId?: string;
+    evidenceIds: string[];
+}
+export interface IdentityGraph {
+    schemaVersion: 1;
+    revision: string;
+    identities: VehicleIdentity[];
+    aliases: VehicleIdentityAlias[];
+    catalogLinks: IdentityCatalogLink[];
+    evidence: IdentityEvidence[];
+    homologation: HomologationIdentity[];
+    visualCompatibility: VisualCompatibility[];
+}
+export interface ScopeContext {
+    year?: number;
+    market?: string;
+    yearBasis?: YearBasis;
+}
+/** Missing context cannot satisfy a restricted scope. */
+export declare function scopeMatches(scope: IdentityScope, context: ScopeContext): boolean;
+export declare function normalizeIdentityText(text: string): string;
+/** Direct, directional facts only; no reverse or transitive inference. */
+export declare function evaluateVisualCompatibility(rules: readonly VisualCompatibility[], requestedId: string, assetId: string, context: ScopeContext): "allow" | "deny" | "unknown";

package/dist/identity.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scopeMatches = scopeMatches;
+exports.normalizeIdentityText = normalizeIdentityText;
+exports.evaluateVisualCompatibility = evaluateVisualCompatibility;
+/** Missing context cannot satisfy a restricted scope. */
+function scopeMatches(scope, context) {
+    return (!scope.years || (context.year !== undefined && scope.years.includes(context.year))) &&
+        (!scope.markets || (context.market !== undefined && scope.markets.includes(context.market))) &&
+        (!scope.yearBasis || scope.yearBasis === context.yearBasis);
+}
+function normalizeIdentityText(text) {
+    return text.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase()
+        .replace(/[^a-z0-9\p{L}]+/gu, " ").trim().replace(/\s+/g, " ");
+}
+/** Direct, directional facts only; no reverse or transitive inference. */
+function evaluateVisualCompatibility(rules, requestedId, assetId, context) {
+    const applicable = rules.filter(rule => rule.requestedVisualIdentityId === requestedId &&
+        rule.assetVisualIdentityId === assetId && scopeMatches(rule, context));
+    if (applicable.some(rule => rule.decision === "deny"))
+        return "deny";
+    return applicable.some(rule => rule.decision === "allow") ? "allow" : "unknown";
+}

package/dist/resolve.d.ts

@@ -0,0 +1,53 @@
+import { type IdentityGraph, type IdentityKind, type ScopeContext } from "./identity";
+export type { IdentityGraph, VehicleIdentity } from "./identity";
+export interface ResolveVehicleOptions extends ScopeContext {
+    makeId?: number;
+    vehicleTypeId?: number;
+    sourceId?: string;
+    /** Default catalog. Rendering consumers should request visual depth. */
+    depth?: "catalog" | IdentityKind;
+}
+export interface ResolvedCatalogSelection {
+    year: number;
+    makeId: number;
+    modelId: number;
+    modelName: string;
+    vehicleTypeId: number;
+    sourceIds: string[];
+}
+export interface VehicleResolutionCandidate {
+    identityId?: string;
+    depth: "catalog" | IdentityKind;
+    lineage: Partial<Record<IdentityKind, string>>;
+    catalogSelections: ResolvedCatalogSelection[];
+    visualIdentityIds: string[];
+    evidenceIds: string[];
+}
+export type VehicleResolutionStatus = "MATCHED" | "UNKNOWN_MAKE" | "UNKNOWN_MODEL" | "UNRESOLVED_TOKENS" | "GENERATION_UNRESOLVED" | "AMBIGUOUS" | "YEAR_UNVERIFIED" | "SCOPE_UNVERIFIED" | "KNOWN_DERIVATIVE_UNSUPPORTED" | "INVALID_INPUT";
+export type VehicleResolution = {
+    status: "MATCHED";
+    selection: VehicleResolutionCandidate;
+    candidates: VehicleResolutionCandidate[];
+    unresolvedTokens: string[];
+    revision: string;
+} | {
+    status: Exclude<VehicleResolutionStatus, "MATCHED">;
+    candidates: VehicleResolutionCandidate[];
+    unresolvedTokens: string[];
+    revision: string;
+};
+interface Catalog {
+    makes: {
+        make_id: number;
+        make_name: string;
+    }[];
+    modelNames: string[];
+    models: readonly (readonly number[])[];
+    sources: {
+        source_id: string;
+    }[];
+}
+/** Create an isolated resolver for a validated graph and catalog, including test fixtures. */
+export declare function createVehicleResolver(catalog: Catalog, identities: IdentityGraph): (query: string, options?: ResolveVehicleOptions) => VehicleResolution;
+/** Exact identity resolution, separate from autocomplete and render availability. */
+export declare function resolveVehicle(query: string, options?: ResolveVehicleOptions): VehicleResolution;

package/dist/resolve.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createVehicleResolver = createVehicleResolver;
+exports.resolveVehicle = resolveVehicle;
+const data_1 = __importDefault(require("./data"));
+const identity_data_1 = __importDefault(require("./identity-data"));
+const identity_1 = require("./identity");
+const rank = { catalog: 0, line: 1, generation: 2, derivative: 3, specification: 4, visual: 5 };
+/** Create an isolated resolver for a validated graph and catalog, including test fixtures. */
+function createVehicleResolver(catalog, identities) {
+    const nodes = new Map(identities.identities.map(n => [n.id, n]));
+    const ancestry = (node) => {
+        const result = [node], seen = new Set([node.id]);
+        let parent = node.parentId ? nodes.get(node.parentId) : undefined;
+        while (parent && !seen.has(parent.id)) {
+            result.push(parent);
+            seen.add(parent.id);
+            parent = parent.parentId ? nodes.get(parent.parentId) : undefined;
+        }
+        return result;
+    };
+    const makeNames = catalog.makes.map(m => ({ id: m.make_id, name: (0, identity_1.normalizeIdentityText)(m.make_name) })).sort((a, b) => b.name.length - a.name.length);
+    const byMake = new Map();
+    for (const r of catalog.models) {
+        const list = byMake.get(r[1]) ?? [];
+        list.push(r);
+        byMake.set(r[1], list);
+    }
+    const names = catalog.modelNames.map(identity_1.normalizeIdentityText);
+    const select = (r) => ({ year: r[0], makeId: r[1], modelId: r[2], modelName: catalog.modelNames[r[3]], vehicleTypeId: r[4], sourceIds: catalog.sources.filter((_, i) => (r[5] & 2 ** i) !== 0).map(s => s.source_id) });
+    return function resolve(query, options = {}) {
+        const result = (status, candidates = [], unresolvedTokens = []) => status === "MATCHED"
+            ? { status, selection: candidates[0], candidates, unresolvedTokens, revision: identities.revision }
+            : { status, candidates, unresolvedTokens, revision: identities.revision };
+        if (!query.trim() || query.length > 512 || (options.year !== undefined && (!Number.isInteger(options.year) || options.year < 1886 || options.year > 2200)))
+            return result("INVALID_INPUT");
+        let text = (0, identity_1.normalizeIdentityText)(query), year = options.year;
+        // Only a leading year is inferred. Model names such as Peugeot 2008 are preserved.
+        const prefix = text.match(/^((?:19|20)\d{2})\s+/);
+        if (prefix) {
+            if (year !== undefined && year !== Number(prefix[1]))
+                return result("INVALID_INPUT");
+            year = Number(prefix[1]);
+            text = text.slice(prefix[0].length);
+        }
+        let makeId = options.makeId;
+        const make = makeNames.find(m => text === m.name || text.startsWith(m.name + " "));
+        if (make && (makeId === undefined || make.id === makeId)) {
+            makeId = make.id;
+            text = text.slice(make.name.length).trim();
+        }
+        if (makeId === undefined || !byMake.has(makeId))
+            return result("UNKNOWN_MAKE");
+        if (!text)
+            return result("UNKNOWN_MODEL");
+        const context = { year, market: options.market, yearBasis: options.yearBasis ?? "model-year" };
+        const sourceIndex = options.sourceId === undefined ? undefined : catalog.sources.findIndex(s => s.source_id === options.sourceId);
+        if (sourceIndex === -1)
+            return result("SCOPE_UNVERIFIED");
+        const rows = (byMake.get(makeId) ?? []).filter(r => (options.vehicleTypeId === undefined || r[4] === options.vehicleTypeId) && (sourceIndex === undefined || (r[5] & 2 ** sourceIndex) !== 0));
+        const scopeOk = (n) => ancestry(n).every(p => (0, identity_1.scopeMatches)(p, context));
+        const allNamed = identities.identities.filter(n => n.makeId === makeId && (options.vehicleTypeId === undefined || options.vehicleTypeId === n.vehicleTypeId) && n.names.some(s => (0, identity_1.normalizeIdentityText)(s) === text));
+        const aliases = identities.aliases.filter(a => (0, identity_1.normalizeIdentityText)(a.text) === text && nodes.get(a.targetId)?.makeId === makeId && (options.vehicleTypeId === undefined || nodes.get(a.targetId)?.vehicleTypeId === options.vehicleTypeId));
+        const named = [...new Map([...allNamed, ...aliases.filter(a => (0, identity_1.scopeMatches)(a, context)).map(a => nodes.get(a.targetId))].map(n => [n.id, n])).values()];
+        if (allNamed.length || aliases.length) {
+            let matching = named.filter(scopeOk);
+            if (!matching.length) {
+                const otherScopeFits = named.some(n => ancestry(n).every(p => (0, identity_1.scopeMatches)({ ...p, years: undefined }, context)));
+                return result(year !== undefined && otherScopeFits ? "YEAR_UNVERIFIED" : "SCOPE_UNVERIFIED");
+            }
+            const requestedDepth = options.depth ?? "catalog";
+            // A line/generation can be completed only when all scope constraints leave one child.
+            if (requestedDepth !== "catalog") {
+                matching = matching.flatMap(n => rank[n.kind] >= rank[requestedDepth] ? [n] : identities.identities.filter(child => rank[child.kind] === rank[requestedDepth] && ancestry(child).some(p => p.id === n.id) && scopeOk(child)));
+            }
+            matching = [...new Map(matching.map(n => [n.id, n])).values()];
+            if (!matching.length)
+                return result("GENERATION_UNRESOLVED");
+            const candidates = matching.map(n => {
+                const chain = ancestry(n), lineage = Object.fromEntries(chain.map(p => [p.kind, p.id]));
+                const links = identities.catalogLinks.filter(l => (l.identityId === n.id || (n.kind === "visual" && chain.some(p => p.id === l.identityId))) && (year === undefined || l.year === year));
+                const catalogSelections = rows.filter(r => links.some(l => l.year === r[0] && l.makeId === r[1] && l.modelId === r[2] && l.vehicleTypeId === r[4])).map(select);
+                const visuals = identities.identities.filter(v => v.kind === "visual" && ancestry(v).some(p => p.id === n.id) && scopeOk(v));
+                return { identityId: n.id, depth: n.kind, lineage, catalogSelections, visualIdentityIds: visuals.map(v => v.id), evidenceIds: [...new Set(chain.flatMap(p => p.evidenceIds))] };
+            });
+            if (sourceIndex !== undefined && candidates.every(c => !c.catalogSelections.length))
+                return result("SCOPE_UNVERIFIED", candidates);
+            if (candidates.length !== 1)
+                return result("AMBIGUOUS", candidates);
+            if (requestedDepth === "catalog" && !candidates[0].catalogSelections.length) {
+                const knownLinks = identities.catalogLinks.some(l => l.identityId === candidates[0].identityId);
+                return result(knownLinks && year !== undefined ? "YEAR_UNVERIFIED" : "KNOWN_DERIVATIVE_UNSUPPORTED", candidates);
+            }
+            return result("MATCHED", candidates);
+        }
+        const exact = rows.filter(r => names[r[3]] === text);
+        const yearRows = exact.filter(r => year === undefined || r[0] === year);
+        if (exact.length && !yearRows.length)
+            return result("YEAR_UNVERIFIED");
+        if (yearRows.length) {
+            const groups = new Map();
+            for (const r of yearRows) {
+                const k = `${names[r[3]]}:${r[4]}`;
+                const group = groups.get(k) ?? [];
+                group.push(r);
+                groups.set(k, group);
+            }
+            const candidates = [...groups.values()].map(rs => ({ depth: "catalog", lineage: {}, catalogSelections: rs.map(select), visualIdentityIds: [], evidenceIds: [] }));
+            if (options.market !== undefined)
+                return result("SCOPE_UNVERIFIED", candidates);
+            if (options.depth && options.depth !== "catalog")
+                return result("GENERATION_UNRESOLVED", candidates);
+            return result(candidates.length === 1 ? "MATCHED" : "AMBIGUOUS", candidates);
+        }
+        const prefixes = [...rows.map(r => names[r[3]]), ...identities.identities.filter(n => n.makeId === makeId).flatMap(n => n.names.map(identity_1.normalizeIdentityText))].filter(n => text.startsWith(n + " ")).sort((a, b) => b.length - a.length);
+        return prefixes.length ? result("UNRESOLVED_TOKENS", [], text.slice(prefixes[0].length).trim().split(" ")) : result("UNKNOWN_MODEL");
+    };
+}
+let resolver;
+/** Exact identity resolution, separate from autocomplete and render availability. */
+function resolveVehicle(query, options = {}) {
+    resolver ?? (resolver = createVehicleResolver(data_1.default, identity_data_1.default));
+    return resolver(query, options);
+}

package/dist/search.d.ts

@@ -26,6 +26,8 @@ export interface VehicleSearchVariant {
     modelId: number;
     sourceIds: string[];
 }
+/** Clearer name for the existing year-specific selection; variants remains compatible. */
+export type VehicleSearchSelection = VehicleSearchVariant;
 export interface VehicleModelSearchResult extends VehicleSearchResultBase {
     kind: "model";
     modelName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meterapp/vehicle-db",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Offline international database for cars, motorcycles, trucks, buses, MPVs, and more",
   "repository": {
     "type": "git",
@@ -23,12 +23,28 @@
       "require": "./dist/search.js",
       "default": "./dist/search.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./resolve": {
+      "types": "./dist/resolve.d.ts",
+      "require": "./dist/resolve.js",
+      "default": "./dist/resolve.js"
+    },
+    "./identity": {
+      "types": "./dist/identity.d.ts",
+      "require": "./dist/identity.js",
+      "default": "./dist/identity.js"
+    }
   },
   "typesVersions": {
     "*": {
       "search": [
         "dist/search.d.ts"
+      ],
+      "resolve": [
+        "dist/resolve.d.ts"
+      ],
+      "identity": [
+        "dist/identity.d.ts"
       ]
     }
   },
@@ -38,7 +54,7 @@
   ],
   "scripts": {
     "build:db": "npm run build:data",
-    "build:data": "tsx scripts/build-db.ts",
+    "build:data": "tsx scripts/build-db.ts && tsx scripts/build-identities.ts",
     "refresh:nhtsa": "tsx scripts/import-nhtsa.ts",
     "refresh:uk-dft": "tsx scripts/import-uk-dft.ts",
     "refresh:nzta-asia-pacific": "tsx scripts/import-nzta-asia-pacific.ts",
@@ -49,7 +65,12 @@
     "build": "npm run build:ts",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
     "prepublishOnly": "npm run build",
-    "test": "vitest run"
+    "test": "vitest run",
+    "build:identities": "tsx scripts/build-identities.ts",
+    "check:compatibility": "tsx scripts/check-compatibility.ts",
+    "refresh:fueleconomy-us": "tsx scripts/import-fueleconomy-us.ts",
+    "refresh:reviewed": "tsx scripts/import-reviewed-models.ts data/evidence/manufacturer-reviewed.json",
+    "replay": "tsx scripts/replay-catalog.ts"
   },
   "keywords": [
     "nhtsa",