audit(data): vehicles + customs duty provenance

[SoapyRED]

Summary

Data-integrity Sprint E — vehicles reference dataset + customs duty methodology.

Part A — Vehicles

• All 18 records in lib/data/vehicles-ref.json carry per-record provenance (≥2 canonical sources each — EU Directive 96/53/EC, UK gov.uk vehicle weights & licence categories, 49 CFR Part 393 / FMCSA 393.5 for US, plus manufacturer specs from Schmitz Cargobull / Krone / Faymonville / DAF / Mercedes-Benz / VW / Ford / Wabash National) + auditedAt: "2026-05-16", verified: false, decisionRationale.
• lib/calculations/vehicle-ref.ts extends VehicleSpec with the mandatory provenance: VehicleProvenance field (mirrors the container-capacity.ts pattern from PR #36).
• app/api/vehicles/route.ts surfaces provenance snake-cased — provenance.{sources, audited_at, verified, decision_rationale}. Additive; no breaking change.

Part B — Customs duty

• lib/calculations/duty.ts gains a top-of-file methodology docstring + a structured DUTY_METHODOLOGY constant — formula (CIF → duty → VAT → totals), Trade Tariff measure-type resolution (103 / 142 / 305 / 695 / 277), 8 HMRC source URLs, verified: false, decision rationale.
• app/api/duty/route.ts gains a GET handler: GET /api/duty?methodology=true → DUTY_METHODOLOGY. Any other GET shape returns 400 with the api-docs link. POST is unchanged.
• lib/data/duty-sample-fixture.json — 10-code regression fixture (0901 coffee, 2204 wine, 6110 jerseys, 8471 computers, 8703 motor cars, 3004 medicaments, 7113 jewellery, 4011 tyres, 9504 game consoles, 0207 poultry). Anchors expected description substrings + common origins + canonical Trade Tariff URLs. Data-only this sprint; smoke assertions are a follow-up chore.

Discipline

Sandbox HTTPS allowlist did not include eur-lex.europa.eu, gov.uk, trade-tariff.service.gov.uk, manufacturer domains, ecfr.gov, fmcsa.dot.gov, unece.org, or en.wikipedia.org this audit pass. Per the rule "no field changes without primary-source backing", NO field values were mutated. Every record + the methodology carry verified: false until a future audit pass with HTTPS access can re-fetch and diff per the runbook in the verification doc.

Audit docs

• docs/audit/vehicles-customs-completeness-2026-05-16.md — per-field gap report (18 vehicles, methodology, fixture).
• docs/audit/vehicles-customs-verification-2026-05-16.md — what was verified, what was deferred, runbook for flipping verified: false → verified: true.

FAULT 5 checklist applied

• CHANGELOG.md entry added (2026-05-16, Data Update tag)
• lib/changelog-data.ts entry added so /changelog renders it
• withAuditRest wrap intact on /api/vehicles and /api/duty (lint:audit PASS — 20 in-scope routes wrapped)
• lint:api-casing PASS — 38 route files clean, snake_case throughout
• lint:seo-titles PASS — 4 detail templates + 4 index pages clean, builders pass 21 fixtures
• tsc clean (npx tsc --noEmit exit 0)
• No new public page (so no sitemap entry, no nav, no homepage tool grid change)
• No MCP tool change (so no freightutils-mcp version bump, no README update)
• No openapi.json / Postman update needed (additive response fields only; no new endpoint contract)

Test plan

• Vercel preview READY (auto)
• curl -s {preview}/api/vehicles?slug=standard-curtainsider | jq '.result.provenance.sources | length' → expect ≥ 2
• curl -s {preview}/api/vehicles?slug=us-53ft-dry-van | jq '.result.provenance.verified' → expect false
• curl -s {preview}/api/vehicles?slug=luton-van | jq '.result.provenance.audited_at' → expect "2026-05-16"
• curl -s {preview}/api/duty?methodology=true | jq '.sources | length' → expect 8
• curl -s {preview}/api/duty?methodology=true | jq '.verified' → expect false
• curl -X POST {preview}/api/duty -H "content-type: application/json" -d '{"commodity_code":"0901","origin_country":"BR","customs_value":5000}' | jq '.commodity_description' → expect substring match "Coffee"
• Post-merge: same checks against https://www.freightutils.com
• Post-merge: /changelog renders the new May 16 vehicles + duty entry
• Post-merge: 10-path Sentry-quiet sweep — zero 5xx

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
freighttools	Ready	Preview, Comment	May 16, 2026 7:39am