feat(nebula_core): vendor neutral runtime interface

[drwnz]

PR Type

• New Feature

Related Links

N/A

Description

This PR introduces a vendor-neutral runtime interface, providing a ROS-free core layer for
discovering sensor plugins, routing raw packets, and running decoders in live or replay sessions
without hard-coding vendor-specific orchestration.

The change adds:

• Generic packet, decoded-output, configuration, progress, and error contracts in
  nebula_core_common.
• Plugin and decoder runtime interfaces in nebula_core_decoders.
• A simplified plugin metadata contract where supported models are declared once in
  SensorPluginMetadata.
• Reusable packet sources for UDP, TCP, CAN, HTTP polling, HTTP control, and PCAP replay in
  nebula_core_hw_interfaces.
• A new nebula_core_runtime package with SensorRegistry, PacketRouter,
  LiveTransportGraph, and ReplaySessionRunner.
• A sample plugin and decoder package used to validate discovery, plugin loading, routing, live
  graph composition, and replay behavior.
• Documentation for the architecture, ABI expectations, threading model, routing model, replay
  behavior, and migration expectations.

This PR is intentionally scoped to the common runtime contract and reference plumbing. It does
not convert the existing production sensor drivers to this interface. Hesai, Robosense,
Velodyne, Continental, and Seyond remain on their current driver paths. Production
SensorPlugin and SensorDecoderRuntime adapters should land in future vendor-specific PRs with
sensor-specific tests and behavioral validation.

Runtime compatibility notes:

• The change is additive and does not replace existing production decoder or hardware-interface
  entrypoints.
• The new plugin ABI is versioned with kNebulaPluginAbiVersion.
• New plugins should export create_nebula_sensor_plugin,
  destroy_nebula_sensor_plugin, and nebula_plugin_abi_version.
• Descriptor models entries must resolve to known SensorModel values.
• Duplicate package descriptors are diagnosed instead of silently overwriting each other.
• Descriptors may declare a custom destroy symbol when they use a non-default factory symbol.

Review Procedure

Recommended review order:

1. Review the public contracts in nebula_core_common and nebula_core_decoders.
2. Review SensorRegistry descriptor discovery, descriptor validation, ABI checks, shared-library
   ownership, and plugin lifetime behavior.
3. Review PacketRouter, LiveTransportGraph, and ReplaySessionRunner for routing semantics,
   lifecycle ordering, callback behavior, and replay/live consistency.
4. Review the packet-source changes in nebula_core_hw_interfaces, especially callback exception
   handling and PCAP fragment reassembly.
5. Review the sample plugin and tests as the reference implementation for the generic runtime
   path.
6. Review docs/vendor_neutral_runtime_interface.md for consistency with the implementation and
   stated migration scope.

Validation already run:

pre-commit run --files $(git --no-pager diff --cached --name-only)
git --no-pager diff --cached --check
export CCACHE_DISABLE=1; source /opt/ros/humble/setup.bash && colcon build --packages-up-to nebula_core_runtime nebula_sample_decoders --event-handlers console_direct+ --cmake-args -DBUILD_TESTING=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
export CCACHE_DISABLE=1; source /opt/ros/humble/setup.bash && colcon test --packages-select nebula_core_common nebula_core_decoders nebula_core_runtime nebula_sample_decoders --event-handlers console_direct+
export CCACHE_DISABLE=1; source /opt/ros/humble/setup.bash && colcon test --packages-select nebula_core_hw_interfaces --event-handlers console_direct+

Results:

• pre-commit: passed.
• git diff --check: passed.
• Build through nebula_core_runtime and nebula_sample_decoders: passed.
• nebula_core_common: passed 3/3 test executables.
• nebula_core_decoders: passed 4/4 test executables.
• nebula_core_runtime: passed 5/5 test executables, including the registry, router, live graph,
  replay runner, and sample plugin integration tests.
• nebula_core_hw_interfaces: passed 5/5 test executables outside the restricted sandbox.

Remarks

Follow-up work should add production adapters one vendor or sensor family at a time. Each adapter
should include live and replay validation for packet routing, calibration handling, configuration
translation, and output equivalence before any ROS wrapper is moved onto the runtime graph.

Pre-Review Checklist for the PR Author

PR Author should check the checkboxes below when creating the PR.

• Assign PR to reviewer

Checklist for the PR Reviewer

Reviewers should check the checkboxes below before approval.

• Commits are properly organized and messages are according to the guideline
• (Optional) Unit tests have been written for new behavior
• PR title describes the changes

Post-Review Checklist for the PR Author

PR Author should check the checkboxes below before merging.

• All open points are addressed and tracked via issues or tickets

CI Checks

• Build and test for PR: Required to pass before the merge.

[codecov]

Codecov Report

❌ Patch coverage is 16.80441% with 302 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.49%. Comparing base (d827f3a) to head (89b5bee).
⚠️ Report is 2 commits behind head on main.

❌ Your patch check has failed because the patch coverage (16.80%) is below the target coverage (90.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #450      +/-   ##
==========================================
- Coverage   40.19%   39.49%   -0.70%     
==========================================
  Files         131      144      +13     
  Lines       10280    10638     +358     
  Branches     5393     5542     +149     
==========================================
+ Hits         4132     4202      +70     
- Misses       3796     4057     +261     
- Partials     2352     2379      +27     

Flag	Coverage Δ
nebula_core_common	51.65% <16.80%> (?)
nebula_core_decoders	51.65% <16.80%> (?)
nebula_core_hw_interfaces	51.65% <16.80%> (?)
nebula_core_runtime	51.65% <16.80%> (?)
nebula_sample_common	51.65% <16.80%> (?)
nebula_sample_decoders	51.65% <16.80%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.