schema(usb): publish typed transport roles and board identity profiles for fbuild

[zackees]

Parent consumer: FastLED/fbuild#1047
Related Pico identity audit: #46

Goal

Publish a versioned, machine-readable USB identity contract that lets fbuild remove every production VID/PID literal and consume FastLED/boards as the only source of USB identities. Test fixtures are the sole exception. This includes board runtime identities, bootloader identities, generic USB-UART bridges, debug probes, recovery transports, reset semantics, and board/environment-to-identity relationships.

Current gap

The public usb-ids.json / usb-vids.proto.zstd artifact currently publishes only:

• VID + vendor name;
• PID + one product name.

That is enough for display, but not enough to replace fbuild runtime tables. fbuild still embeds identity knowledge in:

• crates/fbuild-config/assets/boards/json/** (hundreds of build.vid / build.pid rows used for firmware USB defines);
• crates/fbuild-config/src/board/mcu_vid.rs and online-data-tools/seed_mcu_to_vid.json;
• crates/fbuild-serial/src/boards.rs family/reset classification;
• crates/fbuild-serial/src/bootloader_watcher.rs;
• crates/fbuild-daemon/src/handlers/operations/deploy_port.rs;
• crates/fbuild-deploy/src/{probe_rs,lpc_debugger_reflash}.rs and Teensy loader discovery;
• the bundled vendor archive/runtime fallback.

Product-name heuristics are not an acceptable replacement: a single VID:PID may collide across boards, and roles such as runtime CDC, BOOTSEL MSC, HalfKay HID, DFU, CMSIS-DAP, UART bridge, or recovery probe are behavioral facts.

Required published contract

Extend the boards publication pipeline with an additive, versioned artifact (or backward-compatible fields in the protobuf plus an equivalent JSON artifact) that represents both:

1. USB identities keyed by normalized VID:PID, with provenance and typed semantics:
   • roles: runtime serial, USB-UART bridge, bootloader MSC/HID/DFU/UF2, debug probe, recovery transport;
   • reset/transition behavior where known (for example 1200-bps touch/DTR, expected boot identity, expected runtime identity);
   • platform/family/generation constraints such as RP2040 versus RP2350;
   • interface/composite notes when a PID alone is insufficient.
2. Board aliases/environments keyed by stable board ID, mapping the board to one or more identity profiles with priority and purpose (compile-time firmware VID/PID, upload/runtime serial, bootloader, probe).

The artifact must preserve collisions and alternates rather than collapsing them to one display product. Every semantic record must retain source URL/immutable upstream reference and source class.

Initial migration inventory

At minimum, publish provenance-backed profiles for every production identity currently consumed by fbuild, including:

• Raspberry Pi RP2040/RP2350 BOOTSEL and runtime CDC;
• Espressif native USB and USB-serial/JTAG;
• Arduino and clone runtime/bootloader identities;
• CP210x, CH340/CH9102, and FTDI USB-UART bridges;
• SAMD UF2/DFU identities;
• Teensy runtime serial and HalfKay loader;
• NXP LPC-Link2/DAPLink runtime, probe, and DFU recovery identities;
• all board JSON VID/PID pairs currently embedded in fbuild board assets.

Do not infer missing records from vendor-wide wildcard matching. Unresolved identities must be reported, not guessed.

Phases

Phase 1 — schema and deterministic builders

• Specify schema versioning and backward compatibility.
• Add typed identity/profile models and validation.
• Generate compact JSON plus compressed protobuf (or an equivalently compact versioned artifact).
• Preserve existing usb-ids.json consumers while adding the semantic artifact.
• Add unit tests for wire compatibility, collisions, alternates, provenance, and invalid role/reset combinations.

Phase 2 — provenance-backed data

• Curate/import the complete fbuild production inventory on the correct data branches.
• Distinguish runtime, bootloader, bridge, probe, and recovery identities.
• Include board alias/environment relationships and compile-time firmware identities.
• Cover Pico 1 and Pico 2 variants from research: audit and publish Pico/Pico 2 USB identities #46 without treating BOOTSEL as runtime CDC.
• Publish via the normal branch/build-site pipeline; no hand edits to site-src/public.

Phase 3 — consumer handoff

• Publish the artifact and stable URL with _meta schema/version/source hashes.
• Add a fixture/contract test consumable by fbuild.
• Link the fbuild migration PR that removes embedded production identities.
• Verify fbuild can build/deploy representative RP2040, NXP/LPC, Teensy, SAMD, Arduino, and ESP targets from boards-ingested metadata.

Acceptance criteria

• FastLED/boards is sufficient to remove every production VID/PID literal and vendor-ID wildcard from fbuild.
• No behavior depends on product-name substring heuristics when typed role data exists.
• The published schema preserves genuine VID:PID collisions and multiple board profiles.
• All records have provenance; unknowns are explicit.
• Runtime consumers can validate schema/version and reject stale or malformed artifacts.
• Test fixtures may embed IDs, but generated/release fbuild artifacts contain none outside data downloaded from FastLED/boards during the build/cache phase.