Skip to main content
Glama
nitrovin

nitrovin

by joshuasprow
README.md
# nitrovin

An offline VIN decoder that answers like NHTSA's
[vPIC](https://vpic.nhtsa.dot.gov/). It is a Go port of `spVinDecode`, the
decoding procedure NHTSA publishes inside its monthly vPIC database, and it
ships as one binary with a month of vPIC data inside. No network, no
database, no API key.

Its goals are compatibility, answering exactly as vPIC does, and
interoperability, working with other systems through vPIC's ids, its
output shapes and standard formats; speed serves them, and is not one of
them.

Every data month is checked against NHTSA's own procedure running in
Postgres before it ships: every row of every VIN in an 18,318-VIN corpus
must match, byte for byte, or the month does not ship
([what parity means](docs/parity.md)).

```console
$ nitrovin decode -o text 1HGCM82633A004352 | grep -E '^(VIN|Make|Manufacturer Name|Model|Model Year|Body Class|Plant City|Error Code) '
VIN                               1HGCM82633A004352
Body Class                        Coupe
Make                              HONDA
Manufacturer Name                 AMERICAN HONDA MOTOR CO., INC.
Model                             Accord
Model Year                        2003
Plant City                        MARYSVILLE
Error Code                        0
```

Those are 7 of the 43 elements this VIN decodes to (`--shape nitrovin`
lists them).

The same decode is reachable six ways: a CLI, an HTTP server, JSON lines
over stdio, an MCP server for AI assistants, a Go module and a C library.
[nitrovin.app](https://nitrovin.app) runs the latest release's server for
anyone: one page that decodes a VIN as you type it and shows the
vehicle's names in every vocabulary loaded,
where your own vocabularies (or EPA's, in one click) load into your browser and translate
there without being uploaded, and a one-click demo set loads there the same way, the `/v1` API (CORS open) and MCP at
`https://nitrovin.app/mcp`, rate-limited per IP.

**Status: v0.x prereleases.** v0 means the release pipeline is not yet
signed off, not that the API may change: the contract is frozen at `/v1`.
v1.0.0 waits on the gates in
[ADR 0007](docs/adr/0007-release-and-versioning.md#before-v100).
nitrovin is not affiliated with or endorsed by NHTSA.

- [Install](#install)
- [Use it](#use-it): [CLI](#cli), [HTTP](#http), [stdio](#stdio-json-lines), [MCP](#mcp), [Go](#go-module), [C](#c-library)
- [Verify a release](#verify-a-release)
- [The data](#the-data)
- [Vocabularies](#vocabularies): translate your names for vehicles and part types
- [Parity](#parity)
- [Known limits](#known-limits)
- [Benchmarks](#benchmarks)
- [Contributing](#contributing)
- [Credits and licence](#credits-and-licence)

## Install

Every release embeds one vPIC data month; `nitrovin --version` names it.

| Channel | Command | Platforms |
| --- | --- | --- |
| Homebrew | `brew install joshuasprow/tap/nitrovin` | macOS, Linux |
| Scoop | `scoop bucket add joshuasprow https://github.com/joshuasprow/scoop-bucket` then `scoop install nitrovin` | Windows amd64, arm64 |
| winget | `JoshuaSprow.Nitrovin`, not yet submitted ([#78](https://github.com/joshuasprow/nitrovin/issues/78)) | Windows |
| Docker | `docker run --rm -p 8080:8080 ghcr.io/joshuasprow/nitrovin` | linux/amd64, linux/arm64 |
| Go 1.27+ | `go install github.com/joshuasprow/nitrovin/cmd/nitrovin@latest` | anywhere Go builds |
| Archives | [GitHub Releases](https://github.com/joshuasprow/nitrovin/releases): `nitrovin_<version>_<os>_<arch>.tar.gz` (`.zip` on Windows) | linux, darwin, windows × amd64, arm64 |
| Linux packages | the same releases: `sudo apt install ./nitrovin_<version>_linux_<arch>.deb`, `sudo dnf install ./nitrovin_<version>_linux_<arch>.rpm`, `sudo apk add --allow-untrusted ./nitrovin_<version>_linux_<arch>.apk` | linux amd64, arm64 |
| C library | the same releases: `libnitrovin_<version>_<os>_<arch>` | linux, darwin, windows × amd64, arm64 |

```console
$ nitrovin --version
nitrovin v0.1.2 (data 2026_10)
```

The binary is about 80 MB, most of it the data; an archive is about 21 MB.
The Docker image runs `nitrovin serve --addr :8080` by default, as a
non-root user, and takes any other command in its place
(`docker run --rm ghcr.io/joshuasprow/nitrovin decode 1HGCM82633A004352`).
Its tags are `vX.Y.Z`, `vX.Y`, `vX`, `latest` and `data-<YYYY_MM>`.

The Linux packages install `/usr/bin/nitrovin` and put `LICENSE` and
`NOTICE` in `/usr/share/doc/nitrovin`; removing the package removes all
three. They are release assets, not a package repository, so nothing signs
them for `apt`, `dnf` or `apk` (hence `--allow-untrusted`): verify one with
cosign before you install it,

```sh
TAG=v0.1.5
cosign verify-blob --bundle nitrovin_${TAG#v}_linux_amd64.deb.sigstore.json \
  --certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/$TAG \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com nitrovin_${TAG#v}_linux_amd64.deb
```

or check it against `checksums.txt` as [Verify a release](#verify-a-release)
shows.

The binaries are not notarized by Apple. Homebrew removes the quarantine
flag for you. A macOS binary downloaded with a browser is killed on launch
until you remove it:

```sh
xattr -d com.apple.quarantine nitrovin
```

## Use it

Every surface takes the same request and returns the same decode
([the API contract](docs/api/README.md)):

| Request field | Default | Meaning |
| --- | --- | --- |
| `vin` | required | 1–17 characters; partial (`*`) and mistyped VINs decode too |
| `model_year` | none | a model year you already know, a hint |
| `shape` | `vpic` | `vpic`: vPIC's `DecodeVinValues` keys (`Make`, `BodyClass`); `nitrovin`: keyed by variable name, with element and attribute ids |
| `full` | `false` | add `items`, every row NHTSA's procedure emits, with its source and pattern |
| `now` | the clock | the instant the decode is as of; fix it for reproducible output |

A VIN is never an error: what is wrong with it is in `error_codes` (vPIC's
codes, `[0]` is clean), with `corrected_vin` and the possible values when
the procedure suggests them. Every decode carries its `data_month` and
`decoder_version`.

### CLI

```sh
nitrovin decode 1HGCM82633A004352                           # JSON, pretty on a terminal
nitrovin decode -o text --model-year 2003 1HGCM82633A004352  # two columns
nitrovin decode --shape nitrovin --full 1HGCM82633A004352    # by variable name, with items
printf '1HGCM82633A004352,2003\n5YJ3E1EA2JF000316\n' | nitrovin decode -   # one JSON line per VIN
nitrovin info                                                # version, data month, artifact hash, elements
```

`decode -` reads one VIN per line, optionally followed by a comma or a tab
and its model year. Exit status is 0 when every VIN was decoded, whatever
its error codes; 1 when nitrovin could not answer (data that will not load,
a refused input line); 2 for a mistake on the command line, such as an
argument VIN over 17 characters. Problems go to stderr as one JSON line.
[CLI contract](docs/api/README.md#cli-nitrovin-decode).

### HTTP

```sh
nitrovin serve        # 127.0.0.1:8080; --addr, or $PORT, to change
```

```sh
curl localhost:8080/v1/decode/1HGCM82633A004352
curl 'localhost:8080/v1/decode/1HGCM82633A004352?model_year=2003&shape=nitrovin'
curl localhost:8080/v1/decode -d '[{"vin":"1HGCM82633A004352"},{"vin":"5YJ3E1EA2JF000316","shape":"nitrovin"}]'
curl localhost:8080/v1/info
curl 'localhost:8080/v1/translate?from.vin=1HGCM82633A004352'
curl localhost:8080/v1/vocabularies
curl 'localhost:8080/v1/vocabularies/vpic/entries?where.make=474&limit=5'
```

Open the address in a browser: one page, the VIN decoder, drawn as the
VIN's diagram. Type a VIN on the plate, 17 cells under the six groups
of a VIN (maker, vehicle, check digit, model year, plant, serial): each
group's card fills as its characters are typed, a partial VIN included.
A whole VIN gets the check digit's verdict, with its arithmetic behind a
button, the decoder's error codes in NHTSA's words, and a suggested VIN
as a link. Below the cards, "Also known as" shows the vehicle's names in
every vocabulary loaded ([Vocabularies](#vocabularies)), a doubt drawn
dashed. A refusal is said below the plate. The page is rendered on the
server and every answer is a
shareable URL (`/?from.vin=1HGCM82633A004352`; older `/?vin=`,
`/ui/decode`, `/ui/translate`, `/vocab` and `/ui/vocabularies` links
redirect to it, with their VIN and nothing else). The page takes a VIN
and nothing else: `model_year`,
`shape`, `full` and `now` are the API's and the command line's, and the
page ignores them. Three buttons in the header open the rest: VINs offers
examples, the VINs you decoded lately and Surprise me;
Vocabularies lists what is loaded; and Developers holds the page's URL,
`curl` and `nitrovin decode` equivalents to copy, each the plain request
for the VIN, the answer's JSON, a
link to the same VIN on NHTSA's decoder, how to install,
configure MCP and verify this version, and links to the API docs, its
release and data month. Everything works without
JavaScript; with it, the page answers as you type, the URL follows the
plate, back and forward ask the server again, and copy buttons appear.
The pages are not part of the API: they are
not in the OpenAPI document and may change.

`POST /v1/decode` takes up to 1,000 requests and returns an array of
decodes in order; `POST /v1/translate` does the same for translate
requests, and `GET /v1/translate` takes one as dotted query parameters
(`from.vocabulary=fleet&from.entry.make=Dodge&from.entry.model=Ram%201500`).
`GET /v1/vocabularies` lists what is loaded and
`GET /v1/vocabularies/{name}/entries` pages through one;
`GET` and `POST /v1/fit` read a loaded catalog: a vehicle's part types,
candidates and related vehicles, and a fitment's vehicles, with the
shelf parts and yard vehicles of loaded stock sources when asked
([Translation](docs/api/README.md#translation-translate),
[Listing](docs/api/README.md#listing-list),
[Fit](docs/api/README.md#fit-fit)). Refusals are
`application/problem+json` (RFC 9457) with a `pointer` to the offending
value. `GET /v1/openapi.json` serves the
[OpenAPI 3.1 document](docs/api/openapi.yaml); `GET /healthz` is the probe.
There are no CORS headers unless `--cors <origin>` (or `--cors '*'`) names
the browsers that may call `/v1` and `/mcp`. SIGINT or SIGTERM drains
requests in flight and exits 0.

### stdio (JSON lines)

```sh
printf '{"id":1,"vin":"1HGCM82633A004352"}\n{"id":2,"vin":"5YJ3E1EA2JF000316","shape":"nitrovin"}\nnot json\n' | nitrovin stdio
```

One request per line in, one line out per request, in order and flushed per
line: `{"id": …, "decode": {…}}` or `{"id": …, "error": {…}}`. A line with
`"op": "translate"`, `"op": "list"` or `"op": "fit"` translates, lists or
fits instead, through the `--vocab` files, and its reply is keyed
`translation`, `list` or `fit`. A bad
line gets an error line and the session goes on; EOF ends it. This is the
easiest way to keep one decoder process open from another language
(`docker run --rm -i ghcr.io/joshuasprow/nitrovin stdio` works too).
[stdio contract](docs/api/README.md#stdio-nitrovin-stdio).

### MCP

`nitrovin mcp` is an MCP server over stdio with the tools `decode_vin`,
whose arguments are the request above, and `translate`, `list` and `fit`,
which answer from the vocabularies and catalog `--vocab` loads
([tool definitions](docs/api/mcp-tools.json)). For Claude Desktop
(`~/Library/Application Support/Claude/claude_desktop_config.json` on
macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and Cursor
(`~/.cursor/mcp.json`) the entry is the same:

```json
{
  "mcpServers": {
    "nitrovin": {
      "command": "/opt/homebrew/bin/nitrovin",
      "args": ["mcp"]
    }
  }
}
```

Use the absolute path `which nitrovin` prints: desktop apps do not see your
shell's `PATH`. With Docker instead, `"command": "docker"` and
`"args": ["run", "--rm", "-i", "ghcr.io/joshuasprow/nitrovin", "mcp"]`.
A client that installs from the [MCP Registry](https://registry.modelcontextprotocol.io)
finds this server as `io.github.joshuasprow/nitrovin`: the Docker image at
the release tag, run with `mcp`.
To try it without a client, save the snippet as `claude_desktop_config.json`
and call the tool with the MCP Inspector:

```sh
npx @modelcontextprotocol/inspector --cli --config claude_desktop_config.json --server nitrovin \
  --method tools/call --tool-name decode_vin --tool-arg vin=1HGCM82633A004352
```

`nitrovin serve` serves the same server over Streamable HTTP at `/mcp`,
stateless and with JSON responses, for clients that take a URL instead of a
command (`"url": "http://127.0.0.1:8080/mcp"`):

```sh
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/mcp --transport http \
  --method tools/call --tool-name decode_vin --tool-arg vin=1HGCM82633A004352
```

Or use the hosted one, `https://nitrovin.app/mcp`, with no install.

### Go module

```sh
go get github.com/joshuasprow/nitrovin/pkg/nitrovin@latest
```

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/joshuasprow/nitrovin/pkg/contract"
	"github.com/joshuasprow/nitrovin/pkg/nitrovin"
)

func main() {
	d, err := nitrovin.Embedded() // or nitrovin.Open("nitrovin-2026_10.artifact")
	if err != nil {
		log.Fatal(err)
	}
	req, err := contract.ParseRequest([]byte(`{"vin": "1HGCM82633A004352"}`))
	if err != nil {
		log.Fatal(err)
	}
	dec, err := d.Decode(req) // a VIN is never an error: see dec.ErrorCodes
	if err != nil {
		log.Fatal(err)
	}
	out, err := json.Marshal(dec)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(out))
}
```

A `Decoder` is safe for concurrent use. `nitrovin.Embedded` links the data,
about 61 MB, into your binary, and the module download includes it (a
20 MB zip of `github.com/joshuasprow/nitrovin-data`); `nitrovin.Open` loads
an artifact file instead, and a binary that never calls `Embedded` does not
carry the data. Every `pkg/` package is public API:
[pkg.go.dev](https://pkg.go.dev/github.com/joshuasprow/nitrovin/pkg/nitrovin).

### C library

`libnitrovin` (`.so`, `.dylib`, `.dll`) and `nitrovin.h` carry no data:
`nitrovin_open` loads an artifact, the same file `--data` takes, from a
[nitrovin-data release](https://github.com/joshuasprow/nitrovin-data/releases).
`nitrovin_decode` takes one stdio request line and returns exactly the
reply line `nitrovin stdio` would write; `nitrovin_open_vocab` opens the
artifact with vocabularies beside it, for translate, list and fit lines
([the C library](docs/c-library.md)).

```c
#include <stdio.h>
#include "nitrovin.h"

int main(void) {
  char *err = NULL;
  nitrovin_t *h = nitrovin_open("nitrovin-2026_10.artifact", &err);
  if (h == NULL) {
    fprintf(stderr, "%s\n", err);
    nitrovin_free(err);
    return 1;
  }
  char *reply = nitrovin_decode(h, "{\"id\":1,\"vin\":\"1HGCM82633A004352\"}");
  puts(reply); /* {"id":1,"decode":{...}}, as `nitrovin stdio` writes it */
  nitrovin_free(reply);
  nitrovin_close(h);
  return 0;
}
```

```sh
cc -o decode decode.c -L. -lnitrovin -Wl,-rpath,. && ./decode
```

Free every returned string with `nitrovin_free`, never `free()`, and never
unload the library. [docs/c-library.md](docs/c-library.md) has the
downloads, Python through ctypes, and the rules;
[the C ABI contract](docs/api/README.md#c-abi-libnitrovin-nitrovinh) is
authoritative.

## Verify a release

Releases are signed with [cosign](https://github.com/sigstore/cosign)
keyless signatures from GitHub Actions: no key to fetch, the certificate
names the workflow that built the release. Every asset has a
`<asset>.sigstore.json` bundle and a line in `checksums.txt`.

nitrovin, from the directory you downloaded the assets to:

```sh
TAG=v0.1.2
cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/$TAG \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
sha256sum --check --ignore-missing checksums.txt
cosign verify ghcr.io/joshuasprow/nitrovin:$TAG \
  --certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/$TAG \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

nitrovin-data, the data releases (signed from `main`, not from a tag):

```sh
cosign verify-blob --bundle checksums.txt.sigstore.json \
  --certificate-identity https://github.com/joshuasprow/nitrovin-data/.github/workflows/release.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
sha256sum --check checksums.txt
```

`cosign verify-blob --bundle <asset>.sigstore.json … <asset>` checks one
asset directly. A signature from any other workflow or tag is rejected.

## The data

The data is NHTSA's [vPIC](https://vpic.nhtsa.dot.gov/) (Vehicle Product
Information Catalog). NHTSA publishes it once a month as a Postgres dump on
[its downloads page](https://vpic.nhtsa.dot.gov/downloads/), and the
decoding procedure this project ports ships inside that dump. NHTSA's
[terms of use](https://www.nhtsa.gov/about-nhtsa/terms-use) say the
information "is considered public information and may be distributed or
copied", and NHTSA disclaims any warranty on it; as a work of the U.S.
Government it has no copyright (17 U.S.C. § 105). The reading behind this is
[the dump research](https://github.com/joshuasprow/nitrovin/blob/research/nhtsa-dump/docs/research/nhtsa-dump.md#6-terms-of-use).
See [`NOTICE`](NOTICE).

A **data month** (`YYYY_MM`) names one dump. nitrovin converts a dump into
an **artifact**, a 61 MB indexed file that is the same bytes whenever the
same dump is converted, and
[nitrovin-data](https://github.com/joshuasprow/nitrovin-data/releases)
releases it as `v<format>.<YYYYMM>.<rebuild>` (`v1.202610.1`). Each data
release keeps, forever: the artifact, NHTSA's dump zip (so a month can be
re-checked after NHTSA stops hosting it), `manifest.json` (the dump's URL,
size and SHA-256, the artifact's blake3, row counts, the importer commit),
the month's frozen parity key, its stale-cache list and the EPA vocabulary
([Vocabularies](#vocabularies)).

```console
$ nitrovin info | jq '{decoder_version, data_month, data_source, artifact_hash}'
{
  "decoder_version": "v0.1.2",
  "data_month": "2026_10",
  "data_source": "embedded",
  "artifact_hash": "blake3:7518c5b46c4264fe94a8e5158cb1949b000e50803b36d388fec9ebe914a780cb"
}
```

To decode against another month, download its artifact and pass it with
`--data` (any command) or `NITROVIN_DATA`; `--data` wins, then
`NITROVIN_DATA`, then the embedded data:

```sh
nitrovin --data nitrovin-2026_10.artifact info
NITROVIN_DATA=nitrovin-2026_10.artifact nitrovin serve
```

An artifact loads when its format major matches the binary's (format 1
today); a mismatch is an error naming both. When NHTSA publishes a month,
an unattended refresh builds it, gates it and, if it passes, cuts a patch
release of nitrovin with it through every channel, so updating nitrovin is
how you get new data. A month that fails ships nothing and the previous
month stays current. There is no `nitrovin update`.

A decode is a function of the VIN, the model-year hint, `now`, the data
month and the decoder version, and it carries all five; the same five give
the same bytes. Live vPIC runs on newer data than any monthly dump, so it
can answer differently from nitrovin on the same day.

## Vocabularies

Your own names for vehicles and part types (a yard's inventory, a parts
catalog's codes) load beside the data as vocabulary files, and nitrovin
translates a VIN or a name into every loaded vocabulary's names. A file is
JSON Lines, a header and one line per entry
([`vocabulary.schema.json`](docs/api/vocabulary.schema.json)), in one of
three kinds: a **vocabulary** maps its entries onto vPIC's makes and models
(by id, with optional model-year ranges and qualifiers such as Drive Type)
or onto a part-type spine; an **extension set** mints the vehicles vPIC
lacks; a **spine** declares the part types a part vocabulary maps onto.
Matching is exact after one fixed normalization (case and spaces): rules
and fuzzy matching belong to whoever builds the file.
[docs/vocabularies.md](docs/vocabularies.md) is how to write one, check
it, and translate, list and fit on every surface. A **catalog** (which
parts fit which vehicles) loads the same way, and `nitrovin fit` reads it,
and so do **stock files**: shelf parts and yard vehicles a fit answers
beside its candidates. A stock source can instead be a Postgres table or
view read at request time, a **connector**: a stock file of one header
line naming the relation and the environment variable holding its DSN
([Connectors](docs/vocabularies.md#connectors)). It is the one thing
nitrovin reads over a network, and only the `nitrovin` binary links its
driver.

Name files or directories with `--vocab` (repeatable, any command) or
`NITROVIN_VOCAB`. A file with a fault stops nitrovin from starting; where a
file disagrees with the data month (an id NHTSA dropped, say) nitrovin
warns on stderr and in `nitrovin info`, and serves it anyway. `nitrovin
vocab check` fails on both, for your CI. From a checkout, with the
synthetic vocabularies in [`testdata/vocab`](testdata/vocab):

```sh
nitrovin vocab check testdata/vocab
nitrovin --vocab testdata/vocab list                                  # what is loaded
nitrovin --vocab testdata/vocab list fleet --where make=dodge         # a vocabulary's entries, paged
nitrovin --vocab testdata/vocab translate --to fleet 1C6RR7LT5FS123456 # a VIN to your names
nitrovin --vocab testdata/vocab serve                                 # /v1/translate, /v1/vocabularies
```

`serve`'s page shows a VIN's names in every vocabulary loaded on vPIC's
spine, the server's own files with or without JavaScript. Its Vocabularies
button opens a dialog that lists what is loaded, each file marked by where
it is kept and with its drift; with JavaScript, the dialog loads your own files, picked or dropped on the
page, into your browser, where they stay: a Service Worker keeps them in
IndexedDB and
translates with the same Go, built to WebAssembly, linking them with the
server's files, which `serve` publishes with the data month's spine bundle
under `/ui/r/<release>/` ([docs/vocabularies.md](docs/vocabularies.md)).
Release builds include the worker, and EPA's vocabulary (below) as a
one-click load into the browser; a `go install` build serves the page
without them, and says so.

The **demo set** in [`pkg/ui/demo`](pkg/ui/demo) is a small, invented
catalog of popular vPIC models with its part and vehicle vocabularies, an
extension set, a shelf and a yard, every number and stock row made up.
With the worker, the dialog offers it as one **Load demo**, which
compiles its catalog in your browser; `nitrovin --vocab pkg/ui/demo
serve` serves the same files
([The demo set](docs/vocabularies.md#the-demo-set)).

Each data release also carries `epa-vehicles.jsonl`, a vocabulary of the
names EPA's fuel-economy data
([vehicles.csv](https://www.fueleconomy.gov/feg/download.shtml)) gives makes
and models, mapped onto that month's vPIC makes and models with Drive Type
and Series qualifiers where the name implies them. The monthly refresh builds
it from that day's vehicles.csv against the new month and publishes it only
if it loads with no fault; its version is EPA's newest record date and the
data month (`2026-11-03+2026_10`), and the refresh PR reports its drift.
Download it from the release of the month your binary embeds (`nitrovin
--version` names it), or the latest:

```sh
curl -fsSLO https://github.com/joshuasprow/nitrovin-data/releases/latest/download/epa-vehicles.jsonl
nitrovin --vocab epa-vehicles.jsonl info | jq '.vocabularies[] | {name, version, drift}'
nitrovin --vocab epa-vehicles.jsonl translate --to epa-vehicles 1C6RR7LT5FS123456
```

A vocabulary built against another month loads too, with a drift warning for
each id NHTSA has changed since. `checksums.txt` on the same release covers
it ([Verify a release](#verify-a-release)). nitrovin ships no other
vocabulary, and [nitrovin.app](https://nitrovin.app) loads none on the
server: its page offers EPA's to load into your browser.

## Parity

nitrovin's answer for a VIN is NHTSA's procedure's answer, not an
approximation of it: every row the procedure emits, all 15 columns, exact
strings, compared as a multiset per VIN. There is no tolerance and no
per-VIN excuse list. The oracle is NHTSA's own `spvindecode` run in Postgres
17 on the month's dump, with one stale cache table emptied: the dump's
cache of valid characters contradicts the dump's own pattern rows, and live
vPIC answers the way the recomputation does. That is the one registered
[deviation](docs/deviations/README.md), [`stale-cache`](docs/deviations/stale-cache.md),
and the corpus VINs it touches are listed with each data release.

The 2026_10 data in v0.1.2 passed
[refresh run 42662006323](https://github.com/joshuasprow/nitrovin/actions/runs/42662006323):
18,339 calls and 966,232 rows, 0 disagreements; every one of the month's
13,014 WMIs and 25,283 of its 25,293 VinSchemas reached; 52 stale-cache
calls; all 7 deviation witnesses agree with live vPIC on 253 fields. Its
report is the body of
[the refresh PR](https://github.com/joshuasprow/nitrovin/pull/80).

[docs/parity.md](docs/parity.md) explains the corpus and the gates, where
each month's report lives, and how to re-run a release's parity check
yourself in a second.

## Known limits

- **10 VinSchemas are never exercised.** In 2026_10, schemas 4329, 5046,
  6173, 11117, 11146, 11395, 11396, 13555, 15597 and 21187 lose to another
  schema on the same WMI and years on every VIN tried, so no gated VIN
  reaches them ([run 42662006323](https://github.com/joshuasprow/nitrovin/actions/runs/42662006323),
  [#72](https://github.com/joshuasprow/nitrovin/issues/72)).
- **Deviations are classes, never VINs.** Where nitrovin disagrees with
  NHTSA's procedure, it is a bug unless a registered class proves a defect
  in NHTSA's data, with a mechanical detector and a VIN on which live vPIC
  agrees with nitrovin ([ADR 0006](docs/adr/0006-deviations-are-detected-classes.md),
  [the registry](docs/deviations/README.md)). There is one class.
- **The `vpic` layout is not live `DecodeVinValues` byte for byte.** It has
  no `VIN` key, has `PlantAddress`, lacks vPIC's ten always-empty legacy
  keys, and joins multi-valued elements in byte order where vPIC's order is
  unstable ([details](docs/api/README.md#layout-vpic-the-default)). Parity
  is gated on the items both layouts are built from.
- **Element names and codes are data, not API.** NHTSA renames them between
  months; pin `element_id` and `attribute_id` for anything long-lived.
- **Over 17 characters is refused.** NHTSA's procedure raises on it, so
  there is no answer to match.
- **Not drop-in for vPIC's URLs.** `serve` has its own `/v1` routes, not
  vPIC's `/api/vehicles/...`.
- **winget** is not live yet ([#78](https://github.com/joshuasprow/nitrovin/issues/78)).
  **macOS binaries are not notarized** (see [Install](#install)).
- **The C library** cannot be unloaded, needs glibc 2.17+ on Linux (no
  musl), and macOS 11+.

## Benchmarks

Correctness first. On a random 2,000 of the corpus's VINs, nitrovin and
ultravin each agree with the freshened Postgres oracle on 2,000 of 2,000
decodes; corgi v2 and v3 emit other output and are not comparable; NHTSA
Postgres is the oracle itself; NHTSA MSSQL and the web API were not
compared ([the correctness aside](docs/benchmarks.md#correctness-aside)).
Speed is context for the goals, not one of them: a budget to meet, not a
race to win.

How many VINs each engine decodes **per second**, every row measured on
one machine over one corpus, against NHTSA's own `spVinDecode` in SQL
Server (55.8 VIN/s here).

| engine | VIN/s | vs NHTSA MSSQL |
|---|---:|---:|
| **nitrovin**: Go module, 12 cores, sorted input | **154,313** | ~2,766× faster |
| **nitrovin**: Go module, 12 cores | **146,881** | ~2,632× faster |
| **nitrovin**: Go module, 4 cores, sorted input | **92,743** | ~1,662× faster |
| **nitrovin**: Go module, 4 cores | **82,173** | ~1,473× faster |
| **nitrovin**: Go module, 1 core, sorted input | **26,435** | ~474× faster |
| **nitrovin**: Go module, 1 core | **23,987** | ~430× faster |
| **nitrovin**: CLI, `nitrovin decode -`, one process | **14,524** | ~260× faster |
| ultravin: 12 cores, sorted input | 5,288,394 | ~94,779× faster |
| ultravin: 12 cores | 2,340,410 | ~41,945× faster |
| ultravin: 4 cores, sorted input | 2,688,609 | ~48,186× faster |
| ultravin: 4 cores | 1,062,987 | ~19,051× faster |
| ultravin: 1 core, sorted input | 656,545 | ~11,767× faster |
| ultravin: 1 core | 301,844 | ~5,410× faster |
| corgi v3: `@cardog/corgi` 3.0.1-beta.0 (binary index), not NHTSA's procedure | 149,565 | ~2,681× faster |
| corgi v2: `@cardog/corgi` 2.0.1 (SQLite) | 60 | ~1.1× faster |
| NHTSA MSSQL: `spVinDecode` (SQL Server) | 55.8 | 1× (baseline) |
| NHTSA Postgres: `spvindecode` | 66 | ~1.2× faster |
| NHTSA vPIC web API: rate limit, *cited, not measured* | ~10 | ~5.6× slower |

Measured 2026-11-10 on an Apple M5 Pro (6 performance and 12 efficiency
cores, 48 GB): nitrovin v0.1.8 (`4834e5c`, data 2026_10), ultravin
`deb4e2f` on the same month. The corpus is 20,000,000 unique synthetic
VINs from ultravin's generator, about 95% valid and 5% with one realistic
defect (a typo, a wrong check digit or two swapped characters); sorted
rows decode the same VINs byte-sorted, and corgi v2 and the two SQL
procedures a fixed random 2,000 of them. Each figure is the median of two
fresh-process trials, the second round in reverse order, with the decode
clock frozen where an engine has one. The method and the generator are
[ultravin's](https://github.com/blackthorn-interstellar/ultravin#benchmarks);
its published figures, from another machine, are not used.

The host was shared with other work (one-minute load average 1.9 to 4.0
when trials started). SQL Server ran under Docker's x86 emulation, which
understates it against native hardware. corgi v3 is a prerelease that
answers about 20 summary fields from its own index and calls 19.5% of
these VINs valid, so it does other work than the procedure. The web API
row is [a published rate limit](https://cardog.app/blog/corgi-vin-decoder),
not a decode. On the sample, nitrovin and ultravin both agree with the
freshened Postgres oracle on every element of all 2,000 VINs. Most of
nitrovin's per-VIN time is the procedure's own work: its decode passes
(up to four per VIN) take 46% of a CPU profile, filling in vehicle-type
defaults 24%, laying out the `vpic` attributes 14%. A one-VIN `nitrovin
decode` process takes about 10 ms and 32 MB of memory.
[Method, every trial, versions and how to reproduce each row](docs/benchmarks.md).

## Contributing

Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md)
covers building, the tests, the Postgres oracle on your own machine, and the
rules for a change that touches decoding. Decisions live in
[`docs/adr/`](docs/adr), words in [`GLOSSARY.md`](GLOSSARY.md), and the plan
in the [wayfinder map](https://github.com/joshuasprow/nitrovin/issues?q=label%3Awayfinder%3Amap).

## Credits and licence

MIT, see [`LICENSE`](LICENSE). The data is NHTSA's. The port's structure,
its parity method and its deviation registry follow
[ultravin](https://github.com/blackthorn-interstellar/ultravin) by Bryce
Drennan (MIT), the reference implementation; no ultravin source is copied,
and the committed parity corpus includes ultravin's VIN lists. Details in
[`NOTICE`](NOTICE).