Skip to content

v0.4.2

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 19 Nov 04:22
· 45 commits to main since this release
e1126d0

nitrovin 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.2

Linux 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  # Alpine

MCP 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.com

Changelog

  • 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