Global /faults/stream SSE events lack entity context for downstream consumers

[mfaferek93]

Problem

Consumers subscribing to the gateway-wide /api/v1/faults/stream receive a fault payload (fault_code, severity, reporting_sources, description, ...) but no explicit SOVD entity identifier. reporting_sources contains ROS node names which follow a different convention than SOVD entity IDs (for example /bridge/diagnostic_bridge vs diagnostic-bridge), so a consumer that wants to pull the associated bulk-data/rosbags/{fault_code} has to enumerate apps + components and HEAD-probe each one until a 200 comes back.

Surfaced while building the first external integration (bridge to an Apache Arrow Flight data platform): see resolve_entity_for_download() in the demo bridge, which does O(N) HEAD probes on apps + components as the pragmatic workaround. That works fine at ~10 entities but is wasteful latency-wise and conceptually wrong - the gateway already knows which entity owns the bag, it just doesn't tell the SSE consumer.

Options

A. x-medkit extension in SSE payload

Add x-medkit-entity-type and x-medkit-entity-id fields inside the SSE fault event JSON. The consumer reads them directly and issues one request to bulk-data.

• Pros: zero extra round-trips, backward compatible (vendor extension, existing SOVD consumers ignore it).
• Cons: introduces a new x-medkit-* extension just as Replace x-medkit response extensions with dedicated REST resources #140 proposes moving away from them to dedicated REST resources.

B. Per-entity fault streams

Consumers subscribe to /api/v1/{entity_type}/{id}/faults/stream instead of the gateway-wide stream. Entity context is implicit in the URL path.

• Pros: SOVD-native shape, aligns with the direction of Replace x-medkit response extensions with dedicated REST resources #140.
• Cons: consumer needs to enumerate entities upfront (but that's a one-time discovery, not per-fault). For a global 'catch everything across the gateway' use case the consumer has to fan out into N subscriptions.

Related

• Replace x-medkit response extensions with dedicated REST resources #140 - Replace x-medkit response extensions with dedicated REST resources (tension with option A)
• feat(graph): x-medkit-graph vendor resource schema proposal for live pipeline topology #248 / Add x-medkit-graph provider and function cyclic subscriptions #270 - x-medkit-graph extension precedent (shows option A is workable if we accept more x-medkit)
• Rethink runtime discovery entity mapping to align with SOVD entity model #325 - Rethink runtime discovery entity mapping to align with SOVD entity model

Ask

Confirm a direction (A, B, or a third option) so the demo bridge can replace the HEAD-probe workaround with something the gateway explicitly supports.