Correct provisional action-fault attribution via supersedes_source_id

[bburda]

Pull Request

Summary

An action fault raised before DDS discovery resolves the action server node's
FQN was reported under the action interface name (e.g. /navigate_to_pose).
Because reporting_sources is an append-only set and the per-entity /faults
scope filter is strict-AND (every source must be in the entity's scope), that
provisional source stayed in the set permanently and kept the fault hidden from
every node entity, including the real server node it belongs to.

This adds an optional ReportFault.supersedes_source_id: a re-report can drop a
previously-reported source before adding the new one. The action_status_bridge
records the provisional source and, once discovery resolves the FQN, re-reports
the already-delivered fault under the server FQN with the provisional source
superseded, so the FaultManager ends with reporting_sources = {FQN} and the
fault resolves to the correct entity.

Behavior is opt-in and backward compatible: an empty supersedes_source_id
(the default) preserves the existing add-only behavior.

Key pieces:

• ReportFault.srv: optional supersedes_source_id field.
• FaultStorage / SqliteFaultStorage: drop the superseded source before
  adding the new one, in both the FAILED-update and CLEARED-reactivation paths;
  a self-supersede (supersedes == source_id) is a no-op so a fault can never
  end up with an empty source set.
• FaultReporter::report: optional supersedes_source_id; a supersede
  bypasses local debounce filtering so the correcting report is never dropped.
• action_status_bridge: tracks the provisional source per action and
  corrects it on the next rescan once the FQN is known. A healed or
  not-yet-delivered fault is left untouched; re-attribution happens at most once
  per fault.

---

Issue

• closes Re-attribute action faults raised before DDS discovery resolves #467

---

Type

• Bug fix
• New feature or tests
• Breaking change
• Documentation only

Note: not a breaking change (the new field/argument default to empty), but
out-of-tree callers must rebuild against the regenerated ros2_medkit_msgs.

---

Testing

• Unit (storage): with/without supersede, superseding an absent source,
  self-supersede guard, supersede on a brand-new fault, and supersede across a
  CLEARED->FAILED reactivation - for both the in-memory and SQLite stores.
• Unit (bridge): provisional source kept while the report is still deferred,
  resolved once delivered, and kept after a heal - driven deterministically
  through a test seam with a controllable server-FQN resolver.
• End-to-end: test_fault_source_supersede.test.py drives the real gateway
  scope filter and FaultManager - a fault reported under a provisional source is
  404 under the owning app, then 200 after a superseding re-report under the FQN.
  This exercises the exact strict-AND scope-filter interaction that caused Re-attribute action faults raised before DDS discovery resolves #467.

The bridge's discovery-race timing itself cannot be reproduced deterministically
in a launch test, so the bridge decision logic is covered by the unit seam and
the gateway/FaultManager half by the e2e; together they cover the full path.

Local runs (Jazzy): fault_manager 457, fault_reporter 47, action_status_bridge
65 unit tests - 0 failures; clang-format, clang-tidy (changed files), flake8,
and ament-copyright all clean.

---

Checklist

• Breaking changes are clearly described (and announced in docs / changelog if needed)
• Tests were added or updated if needed
• Docs were updated if behavior or public API changed

[Copilot]

Pull request overview

This PR fixes a fault-attribution edge case where action faults raised before DDS discovery resolves the server node FQN could remain permanently scoped under a provisional source, preventing them from appearing under the correct entity due to strict-AND fault scope filtering.

Changes:

• Adds ReportFault.supersedes_source_id to allow replacing a previously reported source in reporting_sources (opt-in; default preserves add-only behavior).
• Implements supersede handling in both in-memory and SQLite fault storage, and exposes the new parameter via FaultReporter::report (bypassing local debounce when superseding).
• Updates action_status_bridge to track provisional sources and re-report once the server FQN is resolved; adds unit + integration test coverage and updates docs/changelogs.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ros2_medkit_msgs/srv/ReportFault.srv	Adds supersedes_source_id request field and documents intended semantics.
src/ros2_medkit_msgs/README.md	Documents the new supersedes_source_id field for ReportFault.
src/ros2_medkit_msgs/CHANGELOG.rst	Notes the new service field and rebuild requirement for out-of-tree users.
src/ros2_medkit_integration_tests/test/features/test_fault_source_supersede.test.py	Adds an end-to-end test validating provisional-source supersede fixes strict-AND scoping.
src/ros2_medkit_fault_reporter/src/fault_reporter.cpp	Extends reporter API to forward supersede and bypass local debounce when superseding.
src/ros2_medkit_fault_reporter/include/ros2_medkit_fault_reporter/fault_reporter.hpp	Updates reporter API documentation/signature to include optional supersede argument.
src/ros2_medkit_fault_reporter/README.md	Documents advanced reporter usage for superseding provisional sources.
src/ros2_medkit_fault_reporter/CHANGELOG.rst	Changelog entry for the reporter API extension and debounce bypass behavior.
src/ros2_medkit_fault_manager/include/ros2_medkit_fault_manager/fault_storage.hpp	Extends storage interface contract with optional supersede parameter.
src/ros2_medkit_fault_manager/src/fault_storage.cpp	Implements supersede behavior in the in-memory store (self-supersede guarded).
src/ros2_medkit_fault_manager/include/ros2_medkit_fault_manager/sqlite_fault_storage.hpp	Extends SQLite storage override signature with optional supersede parameter.
src/ros2_medkit_fault_manager/src/sqlite_fault_storage.cpp	Implements supersede behavior in SQLite storage by updating stored source set.
src/ros2_medkit_fault_manager/src/fault_manager_node.cpp	Forwards supersedes_source_id from service request to storage.
src/ros2_medkit_fault_manager/test/test_fault_manager.cpp	Adds unit tests covering supersede behavior in the in-memory store.
src/ros2_medkit_fault_manager/test/test_sqlite_storage.cpp	Adds unit tests covering supersede behavior persisted through SQLite JSON storage.
src/ros2_medkit_fault_manager/CHANGELOG.rst	Changelog entry for supersede behavior in fault storage implementations.
src/ros2_medkit_action_status_bridge/include/ros2_medkit_action_status_bridge/action_status_bridge_node.hpp	Adds re-attribution support structures/API and test accessors.
src/ros2_medkit_action_status_bridge/src/action_status_bridge_node.cpp	Implements provisional tracking + re-attribution on rescan; cleans up state on prune.
src/ros2_medkit_action_status_bridge/test/test_action_status_bridge.cpp	Adds deterministic unit tests for re-attribution behavior via an overridable resolver seam.
src/ros2_medkit_action_status_bridge/README.md	Updates behavior description to include provisional re-attribution via supersede.
src/ros2_medkit_action_status_bridge/CHANGELOG.rst	Changelog entry for corrected action-fault attribution behavior.
docs/api/messages.rst	Updates API docs to include supersedes_source_id semantics and usage notes.