feat: coordinate symbol-reference completeness with fbuild callgraph #18

Context

The dashboard is adding level-one symbol hover/focus/click reference popups. All 96 Blink/APA102/Rainbow profiles were reanalyzed with explicit cross-toolchain tools, preserving ELF digests, memory totals and symbol sizes. The popup separates incoming symbols from object-file referencers and distinguishes a confirmed ELF entry root, unavailable analysis and unexplained retention.

The audit found 41,645 unexplained positive-size row occurrences and 10,620 unresolved-name occurrences across 96 profiles. These are candidates for investigation, not proof of unused code. Current fbuild JSON cannot explain KEEP/vector/data-pointer roots or distinguish all analysis failure states. Names can also identify several rows (code, literal pools, merged strings).

Audit artifact: REFERENCE-AUDIT.md and per-report *-references.json in FastLED/dashboard. Current producer is fbuild v2.5.37.

Proposal

Track the upstream callgraph/retention fixes with the dashboard consumer. Adopt structured availability, edge kinds, root reasons and stable graph-node identities when fbuild supplies them. Keep direct symbol references and TU-level references visibly separate. Until then, display uncertainty explicitly and retain unresolved target names.

Acceptance criteria

• Cross-linked fbuild issues have agreed producer/consumer contracts.
• RED → GREEN browser/schema tests cover producer analysis failure, a known linker root, a vtable-retained function and a map-derived owner/name collision.
• Incoming data-pointer references are shown as data references, rather than claimed runtime callers.
• Empty references never imply unused code; confirmed roots and unresolved retention have distinct states.
• Reaudit all 96 profiles and compare counts before/after each upstream fix, preserving benchmark provenance.
• Hover/focus/click and keyboard dismissal continue working for Flash and RAM without rebuilding firmware for view-only changes.

Decisions

• P2: the first reference UI can ship with explicit uncertainty; the completeness follow-ups stay open.
• Do not infer KEEP/vector roots from symbol-name heuristics; require ELF/linker evidence.
• Keep the dashboard's supplemental schema versioned until fbuild exposes the matching typed transport.

Coordinated producer issues

• fbuild #1659: tool discovery and silent graph loss.
• fbuild #1660: omitted weak-object vtables and static pointer references.
• fbuild #1661: availability/root/edge/identity transport and unexplained retention.

Each producer issue links back here. Keep this tracker open for the remaining producer/consumer integration even after the initial popup ships.