# Provider integration — October 15, 2026

## Files and architecture
- `data/providers.json`: expanded company-location records with provenance. This adds to the embedded seed rather than replacing Waymo, Tesla or DockDuty.
- `ingestion/normalizeProviders.js`: normalization, nullable status, canonical merge, fetch adapter and provider summary helper.
- `index.html`: minimal hooks for loading, category filtering, operating-now view, details and CSV/JSON exports. Approved styling, map geometry, watches and DockDuty context remain.
- `data/research-gaps.json`: requested-provider exclusions and unresolved research.
- `tests/providers.test.cjs`: automated DOM/data regression tests.

Serve this directory over HTTP; opening index.html directly may prevent JSON loading. An unavailable provider file yields a visible warning and embedded-data fallback. A malformed provider import is rejected as a unit, not silently partially loaded.

## Schema mapping
Original fields, IDs, stages, commercial-status values, evidence/history/signals are preserved. Added fields: category, metro_area, operating_now, earning_revenue_now, source_title, supervision, revenue_model and location_precision.
- record_type maps robotaxi/transit to Passenger service; trucking/industrial yards to Freight / logistics; delivery to Delivery; developers to Technology testing. DockDuty remains Infrastructure.
- Commercial status describes passenger access. Freight/delivery may have Paid service stage and No public rides; explicit revenue evidence is separate.
- Nullable activity fields: true = reported, false = specifically inactive/not earning, null = unknown. Never coerce unknown to false. After 45 days, current positive or negative activity claims become unknown except confirmed Suspended/Exited and infrastructure records.
- Public rides includes only recent passenger activity with public-pilot/paid stage; fare may be unknown. Freight and supplier testing are excluded.
- Launch radar applies only to passenger entries. Supervised commercial service does not become driverless merely because stage is Paid service.
- State-only records have null latitude/longitude and stay searchable without a false map pin. Representative city points are not service boundaries.
- Announced is the minimum taxonomy bucket for authorization-only evidence or recruitment intent, not confirmation of testing or a new launch. Notes explain this compromise.
- Evidence dates may be conservative month/year anchors. Such entries have null publication_date and explicit date_precision; the detail panel labels approximate anchors.
- Observation history dates are tracker observations, not inferred transition dates.

## Merge and storage
Load order: embedded seed → provider import → saved browser overrides. Company + state + city + record_type is the canonical key (selected operator aliases consolidated). Existing canonical IDs are retained; custom records and saved user claims win. Distinct passenger/delivery activities remain separate. DockDuty is filled if missing and same-market links are recalculated without implying affiliation.

Use **Bundled data** to remove saved overrides and load the updated combined import. JSON import validates and merges rather than wiping bundled entries. JSON export keeps raw claims plus computed current_status; CSV exports effective nullable current fields (unknown is blank). Neither export verifies claims.

## Evidence and scope
This is a researched import, **not a real-time feed or exhaustive U.S. registry**. The earlier expanded research import was retained with attributed sources; this integration pass spot-checked selected current directories/regulator data and added Magna, AutoX authorization history and legacy Olli activity. A full independent re-audit of every inherited claim is outstanding.

Five requested providers are explicitly covered in the gap registry rather than fabricated map records: Tortoise, Vayu Robotics, Applied Intuition, Luminar and Ouster. Supplier relationships, headquarters, press-release datelines and contracted fleets do not establish current city operations or realized revenue.

Low-confidence records (<60) include Stack AV New Stanton, Outrider Brighton, Refraction AI Austin, Bosch San Jose, MOIA Los Angeles/Orlando and Coco city entries. Coco current activity/revenue and Torc New Mexico current activity are unknown pending stronger evidence. Historical/medium-confidence records also require fresh verification. Zoox Las Vegas fares, per-city freight revenue, MOIA supervision outside Austin and current legacy delivery activity remain unresolved. See the gap file and individual notes.

## Validation
Run `node tests/providers.test.cjs` from this directory (requires jsdom). All 39 automated checks passed on this review: 65 supplemental records / 37 supplemental providers; 103 merged records / 40 providers; 14 entries without precise pins. Checks cover taxonomy, merge idempotency, saved/custom overrides, stale/nullable status, DockDuty context, filters, details, export handlers, watch persistence, theme switching, bundled reset, and offline/malformed-file fallback. Export handlers are tested, not downloaded-file contents. jsdom is not a visual browser; mobile layout and browser rendering remain unverified.

## Future live feeds
Replace ProviderIngestion.load() with a validated local API/ingestion service. Keep source URL/title, activity date versus retrieval date, authorization scope, category, supervision and nullable revenue/activity independent. Secrets and cross-origin regulator scraping belong in that future local service, not static browser code. No polling, monitoring or scraping was added.