Repository navigation
v0.4.2
Pre-releasenitrovin v0.4.2 with NHTSA vPIC data month 2026_11 embedded.
brew install joshuasprow/tap/nitrovin
scoop bucket add joshuasprow https://github.com/joshuasprow/scoop-bucket && scoop install nitrovin
go install github.com/joshuasprow/nitrovin/cmd/nitrovin@v0.4.2
docker run --rm -p 8080:8080 ghcr.io/joshuasprow/nitrovin:v0.4.2Linux packages, for amd64 and arm64 (put arm64 for amd64):
sudo apt install ./nitrovin_0.4.2_linux_amd64.deb # Debian, Ubuntu
sudo dnf install ./nitrovin_0.4.2_linux_amd64.rpm # Fedora, RHEL
sudo apk add --allow-untrusted ./nitrovin_0.4.2_linux_amd64.apk # AlpineMCP clients that read the MCP Registry find the
server as io.github.joshuasprow/nitrovin (this image, run with mcp; server.json here).
vocabulary.schema.json and decode.schema.json here are this release's schemas: a
vocabulary, catalog or stock file's lines, and every wire type.
Every asset has a cosign keyless bundle. To verify the release, then one
asset directly:
cosign verify-blob --bundle checksums.txt.sigstore.json \
--certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/v0.4.2 \
--certificate-oidc-issuer https://token.actions.githubusercontent.com checksums.txt
sha256sum --check --ignore-missing checksums.txt
cosign verify-blob --bundle nitrovin_0.4.2_linux_amd64.deb.sigstore.json \
--certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/v0.4.2 \
--certificate-oidc-issuer https://token.actions.githubusercontent.com nitrovin_0.4.2_linux_amd64.deb
cosign verify ghcr.io/joshuasprow/nitrovin:v0.4.2 \
--certificate-identity https://github.com/joshuasprow/nitrovin/.github/workflows/release.yml@refs/tags/v0.4.2 \
--certificate-oidc-issuer https://token.actions.githubusercontent.comChangelog
- 514d7cc contract: month-bound tests follow the pinned data month (#312) (#317)
- 1dfb0d1 docs: AGENTS.md states the repository's rules for coding agents (#313) (#314)
- 92d2bfb docs: DESIGN.md states the page's look and which parts of it are settled (#318)
- 24bbab7 docs: public text names no private repository or deployer (#315) (#316)
- e1126d0 ui: decoded cards are manila tags on pinstripe-tape lines (#319)
Benchmarks
bench/vocab on AMD EPYC 9V74 80-Core Processor, linux/amd64, go1.27.4. Requests run on one core: p50 / p99, then throughput. The budgets are stated for the reference machine (Apple M5 Pro class); a CI runner measures about 2× slower, so these numbers are reported beside them, not held to them. To reproduce them: CONTRIBUTING.md.
Decode alone (1HGCM82633A004352): 41 / 199 µs · 17k/s. Budget: ≥ 20k VIN/s and < 1 ms.
Model values, first ask (Series and Drive Type on a Decoder just loaded, ADR 0015): 340 ms. No budget; ADR 0015 measured 0.14-0.16 s.
| fixture, 13 entries | EPA, 5,747 entries | MVL-1M (synthetic), 1,000,000 entries | budget | |
|---|---|---|---|---|
| load, 1 core | 62 ms, 2.06 GB peak | 69 ms, 2.06 GB peak | 4.49 s, 2.06 GB peak | < 100 ms up to EPA scale; < 2 s and < 1 GB peak at 1M |
| load, 4 cores | 60 ms, 1.21 GB peak | 58 ms, 1.21 GB peak | 3.06 s, 1.42 GB peak | < 100 ms up to EPA scale; < 2 s and < 1 GB peak at 1M |
| translate VIN (decode + translate) | 47 / 168 µs · 15k/s | 42 / 152 µs · 18k/s | 53 / 205 µs · 13k/s | p99 < 1 ms |
| translate name | 1.9 / 16 µs · 356k/s | 2.1 / 17 µs · 332k/s | 2.3 / 12 µs · 295k/s | p99 < 1 ms |
| translate spine id (vPIC model → vocabulary) | 2.0 / 15 µs · 368k/s | 2.8 / 20 µs · 265k/s | 6.5 / 40 µs · 111k/s | p99 < 1 ms |
| list, first page | 2.6 / 33 µs · 187k/s | 25 / 170 µs · 21k/s | 23 / 154 µs · 22k/s | p99 < 1 ms at 1M |
| list, next page (cursor) | — | 27 / 172 µs · 20k/s | 25 / 147 µs · 22k/s | p99 < 1 ms at 1M |
| list, where first field | 0.6 / 2.6 µs · 901k/s | 27 / 193 µs · 19k/s | 8.3 / 78 µs · 65k/s | p99 < 1 ms at 1M |
list vpic where make |
21 / 195 µs · 19k/s | 22 / 166 µs · 21k/s | 24 / 172 µs · 22k/s | p99 < 1 ms at 1M |
list vpic where model and element |
12 / 88 µs · 43k/s | 13 / 92 µs · 41k/s | 12 / 89 µs · 43k/s | none set |
Catalog (synthetic, ADR 0017: 790,000 fitments, 1,896,000 applications, 100,000 redirects), as JSON Lines and compiled (ADR 0021). Budgets: JSON Lines ≤ 15 s on one core, ≤ 1.5 GiB peak, file ≤ 500 MB; compiled ≤ 1 s on one core, ≤ 512 MiB peak, ≤ 256 MiB retained, file ≤ 500 MB.
| JSON Lines | compiled | budget | |
|---|---|---|---|
| file | 358 MB | 361 MB | ≤ 500 MB |
| load, 1 core: time, peak, retained heap | 6.31 s, 1.23 GB, 418 MB | 9.7 ms, 1.17 GB, 4 MB | |
| load, 4 cores: time, peak, retained heap | 3.54 s, 1.22 GB, 419 MB | 8.1 ms, 1.21 GB, 4 MB | |
| compile, 1 core: time, peak in process | — | 7.35 s, 1.17 GB | time recorded; ≤ 256 MiB peak |
| check, 1 core: time, peak in process | 7.33 s, 1.17 GB | — | ≤ 512 MiB peak |
| by vehicle (a part type, a vehicle, a year) | 0.9 / 1.8 µs | 8.3 / 58 µs · 2 / 2 reads | p99 ≤ 5 ms |
| by vehicle, every part type | 147 / 227 µs | 250 / 565 µs · 1 / 1 reads | p99 ≤ 10 ms |
| by number | 1.1 / 2.0 µs | 6.4 / 41 µs · 1 / 1 reads | p99 ≤ 1 ms |
| redirect | 0.5 / 1.0 µs | 10 / 53 µs · 1 / 1 reads | |
| a page of 1,000 fitments | 5.5 / 29 µs | 211 / 754 µs · 1 / 1 reads | ≤ 8 reads |
Fit (the catalog-scale fixture, one core): p50 / p99 · throughput, and the compiled form's reads per request, p99 / most.
| JSON Lines | compiled | items | budget | reads | read budget | |
|---|---|---|---|---|---|---|
| candidates (vehicle, year, part type) | 8.2 / 50 µs · 83k/s | 28 / 250 µs · 27k/s | 1 | p99 ≤ 5 ms | 3 / 3 | ≤ 10 |
| part types (vehicle, year) | 324 / 893 µs · 2.5k/s | 348 µs / 2.9 ms · 2.1k/s | 120 | p99 ≤ 10 ms | 2 / 2 | ≤ 20 |
| related vehicles | 287 / 819 µs · 2.9k/s | 369 µs / 1.2 ms · 2.3k/s | 11 | p99 ≤ 50 ms | 1 / 1 | ≤ 100 |
| part types, no year | 1.5 / 19 ms · 425/s | 1.2 / 3.6 ms · 587/s | 205 | p99 ≤ 10 ms | 2 / 2 | ≤ 20 |
| related vehicles, no year | 1.6 / 9.3 ms · 514/s | 1.4 / 4.5 ms · 559/s | 105 | p99 ≤ 50 ms | 1 / 1 | ≤ 100 |
| reverse (one fitment key) | 8.8 / 57 µs · 75k/s | 16 / 70 µs · 49k/s | 3 | p99 ≤ 1 ms per key | 1 / 1 | ≤ 2 |
Fit, wide variants (the fixture and a share of fitments of 50–500 applications on vehicles at random, compiled, one core): p99 · reads p99 / most · the most bytes a request read.
| 0.1% wide (382 MB) | 0.3% wide (424 MB) | 1% wide (575 MB) | 1% wide, other years and qualifiers (574 MB) | budget | read budget | |
|---|---|---|---|---|---|---|
| candidates (vehicle, year, part type) | 244 µs · 3 / 3 reads · 8 KB | 248 µs · 3 / 3 reads · 8 KB | 238 µs · 3 / 3 reads · 8 KB | 250 µs · 3 / 3 reads · 8 KB | p99 ≤ 5 ms | ≤ 10 |
| part types (vehicle, year) | 3.4 ms · 2 / 2 reads · 225 KB | 3.3 ms · 2 / 2 reads · 245 KB | 3.5 ms · 2 / 2 reads · 315 KB | 3.9 ms · 2 / 2 reads · 316 KB | p99 ≤ 10 ms | ≤ 20 |
| related vehicles | 5.8 ms · 4 / 4 reads · 1.6 MB | 8.3 ms · 10 / 10 reads · 4.0 MB | 12 ms · 24 / 25 reads · 11.8 MB | 18 ms · 21 / 26 reads · 14.4 MB | p99 ≤ 50 ms | ≤ 100 |
| part types, no year | 4.0 ms · 2 / 2 reads · 225 KB | 4.6 ms · 2 / 2 reads · 245 KB | 7.1 ms · 2 / 2 reads · 315 KB | 6.6 ms · 2 / 2 reads · 316 KB | p99 ≤ 10 ms | ≤ 20 |
| related vehicles, no year | 13 ms · 3 / 3 reads · 1.7 MB | 19 ms · 6 / 6 reads · 4.7 MB | 41 ms · 16 / 16 reads · 15.2 MB | 41 ms · 16 / 16 reads · 15.2 MB | p99 ≤ 50 ms | ≤ 100 |
| reverse (one fitment key) | 69 µs · 1 / 1 reads · 15 KB | 75 µs · 1 / 1 reads · 15 KB | 78 µs · 1 / 1 reads · 15 KB | 79 µs · 1 / 1 reads · 15 KB | p99 ≤ 1 ms per key | ≤ 2 |
| candidates of a wide fitment's part type | 238 µs · 3 / 3 reads · 7 KB | 279 µs · 3 / 3 reads · 8 KB | 430 µs · 3 / 3 reads · 12 KB | 475 µs · 3 / 3 reads · 12 KB | p99 ≤ 5 ms | ≤ 10 |