topicforge 0.6.0__tar.gz → 0.6.1__tar.gz

{topicforge-0.6.0 → topicforge-0.6.1}/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to TopicForge are documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.1] - 2026-10-06
+
+### Added
+
+- A Claude plugin bundle in `plugin/`: the TopicForge MCP server (started with
+  `uvx`, version pinned) and two skills, `diagnose-dds-bus` and
+  `inspect-ros2-robot`. Install with `claude plugin marketplace add
+  yaniswav/TopicForge`.
+- [docs/VALIDATION.md](docs/VALIDATION.md): the OmniSim team's external validation
+  against a simulated robot's ground truth, published as approved by them.
+- `MessageSample.recorded_ns`: the bag record time of a `peek_bag_samples` sample.
+- `MessageSample.stamp_source` value `recorded`: `timestamp_ns` is the bag record
+  time because the message has no top-level header.
+- `HealthReport.sim_clock_published` (live ROS 2 only, else null): whether `/clock`
+  has a publisher, a hint that nodes may run on simulated time.
+
+### Changed
+
+- `peek_bag_samples` `timestamp_ns` is now `header.stamp` when the message has a
+  top-level header (`stamp_source` `header`), else the bag record time (`stamp_source`
+  `recorded`). It used to be the bag record time for every message, with
+  `stamp_source` null. The tool description says it returns the first `count`
+  messages, not the last.
+- CI: `actions/checkout` v7, `actions/setup-python` v7, `actions/cache` v6. Jobs
+  that run tests or the demos use `ubuntu-24.04` instead of `ubuntu-latest`.
+
+### Fixed
+
+- `peek_bag_samples` payloads no longer carry `__msgtype__` in every nested object
+  nor a top-level `_msgtype`; the message type stays at the sample level.
+
 ## [0.6.0] - 2026-10-05
 
 `sample_messages` (live) rewritten after the OmniSim team's report (count
@@ -1263,7 +1294,8 @@ Initial MVP release of TopicForge: ROS Topic Inspector & Bag Analyzer MCP server
 - The write path (publishing, commanding robots) is intentionally out of scope for the MVP.
 - `analyze_bag` in live mode parses `ros2 bag info` text output; deeper anomaly detection remains mock-only for now.
 
-[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.6.1...HEAD
+[0.6.1]: https://github.com/yaniswav/TopicForge/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/yaniswav/TopicForge/compare/v0.5.6...v0.6.0
 [0.5.6]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...v0.5.6
 [0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5

{topicforge-0.6.0 → topicforge-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.6.0
+Version: 0.6.1
 Summary: ROS Topic Inspector & Bag Analyzer MCP server for AI agents
 Project-URL: Homepage, https://github.com/yaniswav/TopicForge
 Project-URL: Repository, https://github.com/yaniswav/TopicForge
@@ -158,6 +158,8 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 ## Limitations
 
+External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+
 - DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
 - Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
@@ -166,7 +168,7 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
 - `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
-- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`) or, without a top-level header, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
 - Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
@@ -189,7 +191,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.6.0"`       | TopicForge server version                                   |
+| `version`    | `"0.6.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.6.0 → topicforge-0.6.1}/README.md

@@ -98,6 +98,8 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 
 ## Limitations
 
+External validation against a simulated robot's ground truth: [docs/VALIDATION.md](docs/VALIDATION.md).
+
 - DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
 - User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
 - Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
@@ -106,7 +108,7 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 - DDS Security is not handled. A participant without credentials sees an empty secure bus. `detect_qos_mismatches` checks Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation (History as a risk); Presentation, XTypes assignability and runtime behavior are not checked, and the result lists them in `policies_unchecked`. It returns a `MismatchScan` envelope: read `reports` for the mismatches.
 - Fast DDS serves no `list_endpoints`.
 - `sample_messages` (live) streams `ros2 topic echo` until `count` messages arrive or `timeout_s` (1..45, default 10, for the whole call) runs out, and returns what arrived with a `note` (`N of M messages within T s`, saying whether a publisher exists). QoS is matched to the publishers, so latched topics work. The payload has nested named fields (`payload.header.stamp.sec`); `timestamp_ns` is `header.stamp` (the publisher's clock, sim time on a simulation) or 0 for headerless types, with `stamp_source` and `received_ns` (wall clock when the CLI printed it). Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_fields`. `nan` and `inf` come back as strings. `count` above 50 is capped with a note.
-- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, returns the first `count` messages in recording order (not the last), and is served only by the ROS2 CLI adapter or the mock; its `timestamp_ns` is the message's `header.stamp` (`stamp_source` `header`) or, without a top-level header, the bag record time (`stamp_source` `recorded`), and `recorded_ns` is always the bag record time; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output. `health_check` also reports `sim_clock_published` (live only): true when `/clock` has a publisher, a hint that header stamps may be simulation time.
 - Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
@@ -129,7 +131,7 @@ When on, each tool call emits one event with exactly six fields:
 | `tool_name`  | `"list_topics"` | One of the twelve tools, never argument values              |
 | `latency_ms` | `12.34`         | Handler wall-clock duration, 2 decimals                     |
 | `mode`       | `"mock"`        | Mode of the adapter actually serving: `mock` or `live`      |
-| `version`    | `"0.6.0"`       | TopicForge server version                                   |
+| `version`    | `"0.6.1"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.6.0 → topicforge-0.6.1}/docs/TESTING.md

@@ -15,7 +15,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 ```bash
 python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
 pip install topicforge
-python -m topicforge --version                      # -> topicforge 0.6.0
+python -m topicforge --version                      # -> topicforge 0.6.1
 TOPICFORGE_MODE=mock python -m topicforge           # blocks on stdio; MCP clients spawn it
 ```
 
@@ -41,7 +41,7 @@ python3 -m venv ~/topicforge-venv && source ~/topicforge-venv/bin/activate
 pip install topicforge          # Ubuntu 22.04 ships Python 3.10, which is enough
 ```
 
-Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.6.0 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
+Then run live mode with three terminals. In the first, `ros2 run demo_nodes_cpp talker` publishes `/chatter` at about 1 Hz. In the second, `ros2 topic list` should show `/chatter`. In the third, source ROS2, activate the venv and run `TOPICFORGE_MODE=live python -m topicforge`. The startup line reads `topicforge 0.6.1 ready (mode=live, requested_mode=live, adapter=ros2_cli, telemetry=off)`; `mode=mock` means `ros2` was not found and the server fell back to fixtures.
 
 ## Linux native
 

topicforge-0.6.1/docs/VALIDATION.md

@@ -0,0 +1,15 @@
+# External validation
+
+## OmniSim (October 2026)
+
+The OmniSim team ran TopicForge against a simulated robot and compared its answers with the simulator's ground truth.
+
+Setup: [OmniSim v9.1.3](https://github.com/omnilink-tech/omnisim/releases/tag/v9.1.3), a simulated Clearpath Husky with a 541-beam SICK LMS111 lidar in a room with walls at known positions, robot stationary. ROS 2 Humble on Ubuntu 22.04 (WSL2), Fast DDS. TopicForge 0.5.3 in live mode for the ROS 2 tools, and 0.5.5 with the Cyclone backend for the DDS tools.
+
+What matched:
+- Every lidar scan TopicForge sampled was bit-identical to the simulator's raw data on the beams it delivered.
+- `list_topics` and `get_topic_info` returned the same names, types and publisher/subscriber counts as the `ros2` CLI.
+- `analyze_bag` returned the same duration and message counts as `ros2 bag info` and an independent read of the bag.
+- With the Cyclone backend, TopicForge saw all seven Fast DDS participants of the ROS 2 graph without extra configuration, and reported participants leaving within about 10 ms of the actual time.
+
+What it found: seven discrepancies on TopicForge's side, including lidar arrays cut at 128 values, one message per `sample_messages` call, zero timestamps on simulated time, and Humble bags that `peek_bag_samples` could not decode. All seven are addressed in 0.5.6 and 0.6.0 (full arrays through a `max_array_length` option) and covered by a ROS 2 Humble/Jazzy test bench; the OmniSim run itself has not been repeated on these versions yet. The bag recorded during the run is part of TopicForge's test fixtures (`tests/fixtures/bags/omnisim_humble/`).

topicforge-0.6.1/plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yanis ETHVIGNOT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topicforge-0.6.1/plugin/README.md

@@ -0,0 +1,60 @@
+# TopicForge plugin for Claude
+
+TopicForge is a read-only MCP server for ROS 2 and DDS. This plugin bundles the server with two short skills so Claude can inspect a robot stack and diagnose a DDS bus. It cannot publish, command a robot, or change QoS: the server has no write path.
+
+## What is included
+
+- MCP server `topicforge`, started with `uvx` from the `topicforge` package on PyPI (version pinned to 0.6.1). It exposes twelve read-only tools: `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag`, `peek_bag_samples`, `list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, `peek_dds_samples`, `topic_metrics`.
+- Skill `diagnose-dds-bus`: what to call, and in which order, when nodes do not talk, a topic gets no data, or a node crashed or restarts.
+- Skill `inspect-ros2-robot`: listing topics, sampling messages and reading bags, including large arrays and simulation time.
+
+## Requirements
+
+- [`uv`](https://docs.astral.sh/uv/) on PATH, which provides `uvx`. The first start downloads the package and the Cyclone DDS binding, so it can take a little while.
+- A local MCP server: it runs on your machine, in Claude Code and in Cowork sessions that run on your computer. It does not run in claude.ai chat.
+- ROS 2 on PATH is optional. Without it the ROS 2 tools fall back to fixtures (a fictional demo robot) and `health_check` reports `mode: mock`. The DDS tools work without ROS 2.
+
+## Install
+
+From a marketplace, once the plugin is listed:
+
+```
+/plugin install topicforge
+```
+
+Meanwhile, from this repository (Claude Code):
+
+```
+claude plugin marketplace add yaniswav/TopicForge
+claude plugin install topicforge@topicforge
+```
+
+Or load the folder for one session: `claude --plugin-dir ./plugin`.
+
+## Configuration
+
+Claude Code asks for two options when the plugin is enabled:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `dds_backend` | `cyclone` | `cyclone` joins the DDS bus as a read-only participant. `mock` serves fixtures. `auto` picks the best available. |
+| `dds_domain_id` | `0` | The one DDS domain observed (0 to 232). Fixed at startup. |
+
+The server runs with `TOPICFORGE_MODE=auto`: live ROS 2 when `ros2` is on PATH, fixtures otherwise. Cowork does not prompt for options and uses the defaults. To use other settings there, edit `.mcp.json`.
+
+Without DDS, set `dds_backend` to `mock`, or use the standalone install `uvx topicforge`.
+
+## Privacy
+
+The server reads the local ROS 2 graph and the DDS discovery traffic on the machine and network it runs on, and returns the result to the Claude session. It makes no outbound network calls. Anonymous telemetry exists but is off by default and is not enabled by this plugin. See the main [README](https://github.com/yaniswav/TopicForge#telemetry) for the telemetry contract and [SECURITY.md](https://github.com/yaniswav/TopicForge/blob/main/SECURITY.md).
+
+## Limits
+
+TopicForge sees what DDS discovery announces. It cannot see whether data flows, a writer that is alive but silent, other DDS domains, or secured (DDS Security) endpoints. The skills tell Claude to say so.
+
+## Links
+
+- Project: https://github.com/yaniswav/TopicForge
+- Site: https://topicforge.horizonvista.xyz
+- Issues: https://github.com/yaniswav/TopicForge/issues
+- License: MIT

{topicforge-0.6.0 → topicforge-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.6.0"
+version = "0.6.1"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/__init__.py

@@ -1,5 +1,5 @@
 """TopicForge: ROS Topic Inspector & Bag Analyzer MCP server."""
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 __all__ = ["__version__"]

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/adapters/common/cdr_decoder.py

@@ -59,8 +59,18 @@ def iter_field_names(sample: Any) -> list[str]:
     """List field names on a dynamic-type sample.
 
     Tries `__dataclass_fields__`, `__fields__`, `__slots__`, then public
-    `__dict__` keys. Returns an empty list when none apply.
+    `__dict__` keys. Returns an empty list when none apply. Dunder names
+    such as the `__msgtype__` marker that `rosbags` messages carry are
+    not data and are left out.
     """
+    return [name for name in _raw_field_names(sample) if not _is_dunder(name)]
+
+
+def _is_dunder(name: str) -> bool:
+    return name.startswith("__") and name.endswith("__")
+
+
+def _raw_field_names(sample: Any) -> list[str]:
     fields = getattr(sample, "__dataclass_fields__", None)
     if fields:
         return list(fields)

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/adapters/composite.py

@@ -81,6 +81,11 @@ class CompositeAdapter:
     def analyze_bag(self, path: str) -> BagAnalysis:
         return self._ros.analyze_bag(path)
 
+    def sim_clock_published(self) -> bool | None:
+        """The ROS 2 half's `/clock` probe, `None` when it has none."""
+        probe = getattr(self._ros, "sim_clock_published", None)
+        return probe() if callable(probe) else None
+
     # ----- DDS surface -> DDS adapter -----
 
     def observer_status(self) -> dict[str, Any] | None:

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/adapters/ros2_live/adapter.py

@@ -309,6 +309,16 @@ class Ros2CliAdapter:
             analysis = analysis.model_copy(update={"note": note})
         return analysis
 
+    def sim_clock_published(self) -> bool | None:
+        """Whether `/clock` has a publisher on the graph; `None` when the CLI cannot tell."""
+        try:
+            text = self._run([self._exe, "topic", "info", "/clock"])
+        except AdapterError as exc:
+            return False if "unknown topic" in str(exc).lower() else None
+        if "unknown topic" in text.lower():
+            return False
+        return parse_pub_sub_counts(text)[0] > 0
+
     def _graph_counts(self) -> dict[str, tuple[int, int]] | None:
         """`{topic: (pubs, subs)}` from `ros2 topic list -v`, or `None` when unavailable."""
         try:

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/adapters/ros2_mock/fixtures.py

@@ -602,13 +602,13 @@ MOCK_BAG_SAMPLES: dict[str, list[MessageSample]] = {
         MessageSample(
             topic="/cmd_vel",
             message_type="geometry_msgs/msg/Twist",
-            timestamp_ns=0,
-            stamp_source="none",
+            timestamp_ns=_BASE_TS_NS + i * 100_000_000,
+            stamp_source="recorded",
+            recorded_ns=_BASE_TS_NS + i * 100_000_000,
             payload={
                 "_decode_status": "full",
                 "linear": {"x": 0.20 + i * 0.01, "y": 0.0, "z": 0.0},
                 "angular": {"x": 0.0, "y": 0.0, "z": 0.05 * i},
-                "_msgtype": "geometry_msgs/msg/Twist",
             },
         )
         for i in range(5)
@@ -618,11 +618,18 @@ MOCK_BAG_SAMPLES: dict[str, list[MessageSample]] = {
             topic="/odom",
             message_type="nav_msgs/msg/Odometry",
             timestamp_ns=_BASE_TS_NS + i * 100_000_000,
+            stamp_source="header",
+            recorded_ns=_BASE_TS_NS + i * 100_000_000 + 2_000_000,
             payload={
                 "_decode_status": "full",
-                "header": {"frame_id": "odom"},
+                "header": {
+                    "stamp": {
+                        "sec": (_BASE_TS_NS + i * 100_000_000) // 1_000_000_000,
+                        "nanosec": (_BASE_TS_NS + i * 100_000_000) % 1_000_000_000,
+                    },
+                    "frame_id": "odom",
+                },
                 "pose": {"position": {"x": 0.1 * i, "y": 0.0, "z": 0.0}},
-                "_msgtype": "nav_msgs/msg/Odometry",
             },
         )
         for i in range(3)

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/models/schemas.py

@@ -801,16 +801,30 @@ class MessageSample(BaseModel):
             "`geometry_msgs/Twist`). It is the publisher's clock, not the "
             "arrival time: on simulated time it is sim time since the "
             "simulation started (a few seconds, not a date) and 0 is a valid "
-            "value. Use `received_ns` for when the CLI printed the message. "
-            "Mock samples with a header carry synthetic increasing values."
+            "value. From `peek_bag_samples` a message without a header gets "
+            "the bag record time instead (`stamp_source` `recorded`), also "
+            "given in `recorded_ns`. Use `received_ns` for when the CLI "
+            "printed the message. Mock samples with a header carry synthetic "
+            "increasing values."
         )
     )
-    stamp_source: Literal["header", "none"] | None = Field(
+    stamp_source: Literal["header", "none", "recorded"] | None = Field(
         default=None,
         description=(
             "Where `timestamp_ns` comes from: `header` (the message's "
-            "`header.stamp`) or `none` (headerless message, `timestamp_ns` is "
-            "0). `None` when the backend does not say."
+            "`header.stamp`), `none` (headerless live message, `timestamp_ns` "
+            "is 0) or `recorded` (headerless message from a bag, "
+            "`timestamp_ns` is the bag record time). `None` when the backend "
+            "does not say."
+        ),
+    )
+    recorded_ns: int | None = Field(
+        default=None,
+        description=(
+            "Nanoseconds at which the recorder wrote this message into the "
+            "bag (the bag's own record time, wall clock unless the recorder "
+            "ran on simulated time). `peek_bag_samples` only; `None` for live "
+            "samples, where `received_ns` plays that role."
         ),
     )
     received_ns: int | None = Field(
@@ -1173,6 +1187,17 @@ class HealthReport(BaseModel):
             "use `list_endpoints` for topics and wiring there."
         ),
     )
+    sim_clock_published: bool | None = Field(
+        default=None,
+        description=(
+            "Whether `/clock` has at least one publisher on the ROS 2 graph. "
+            "True suggests nodes may run on simulated time (`use_sim_time`), "
+            "so `header.stamp` values are sim time, not wall time (compare "
+            "with `received_ns`). It is a hint: a publisher on `/clock` does "
+            "not prove a given node follows it. `None` in mock mode or when "
+            "the `ros2` CLI could not answer."
+        ),
+    )
     payload_decoding: Literal["disabled", "enabled"] = Field(
         default="disabled",
         description=(

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/services/bag_service.py

@@ -356,11 +356,14 @@ def _peek_with_rosbags(
             if len(samples) >= count:
                 break
             payload = _decode_bag_message(reader, connection, raw)
+            header_ns = _header_stamp_ns(payload)
             samples.append(
                 MessageSample(
                     topic=topic,
                     message_type=message_type,
-                    timestamp_ns=int(timestamp),
+                    timestamp_ns=int(timestamp) if header_ns is None else header_ns,
+                    stamp_source="recorded" if header_ns is None else "header",
+                    recorded_ns=int(timestamp),
                     payload=_cap_arrays(payload, capped),
                 )
             )
@@ -379,6 +382,18 @@ def _peek_with_rosbags(
     return samples, " ".join(notes) or None
 
 
+def _header_stamp_ns(payload: dict[str, Any]) -> int | None:
+    """`header.stamp` of a decoded message in nanoseconds, or `None` without a top-level header."""
+    header = payload.get("header")
+    stamp = header.get("stamp") if isinstance(header, dict) else None
+    if not isinstance(stamp, dict):
+        return None
+    sec, nanosec = stamp.get("sec"), stamp.get("nanosec")
+    if isinstance(sec, int) and isinstance(nanosec, int):
+        return sec * 1_000_000_000 + nanosec
+    return None
+
+
 def _cap_arrays(payload: dict[str, Any], capped: set[str], prefix: str = "") -> dict[str, Any]:
     """Cut lists over `_MAX_ARRAY_ELEMENTS`, recording the field paths in `capped`."""
     out: dict[str, Any] = {}
@@ -406,7 +421,4 @@ def _decode_bag_message(reader: Any, connection: Any, raw: bytes) -> dict[str, A
 
     from topicforge.adapters.common.cdr_decoder import decode_dynamic_sample
 
-    decoded = decode_dynamic_sample(deserialized, max_array_elements=_MAX_ARRAY_ELEMENTS)
-    if isinstance(decoded, dict):
-        decoded.setdefault("_msgtype", getattr(connection, "msgtype", "<unknown>"))
-    return decoded
+    return decode_dynamic_sample(deserialized, max_array_elements=_MAX_ARRAY_ELEMENTS)

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/services/health.py

@@ -67,6 +67,7 @@ class HealthService:
             middleware_available=_middleware_available(dds_backend, self._settings),
             ros_backend=ros_backend,
             ros_tools_available=ros_backend != "none",
+            sim_clock_published=_sim_clock_published(self._adapter),
         )
 
 
@@ -84,6 +85,21 @@ def _observer_status(adapter: MiddlewareAdapter) -> dict[str, Any]:
         return {}
 
 
+def _sim_clock_published(adapter: MiddlewareAdapter) -> bool | None:
+    """`/clock` publisher hint if the adapter can probe it (live ROS 2), else `None`.
+
+    Not part of the protocol, and a failure must not break `health_check`.
+    """
+    probe = getattr(adapter, "sim_clock_published", None)
+    if not callable(probe):
+        return None
+    try:
+        result = probe()
+    except Exception:
+        return None
+    return result if isinstance(result, bool) else None
+
+
 def _backends_from_adapter_name(name: str) -> tuple[RosBackendTag, DdsBackendTag]:
     """Split an adapter tag into its ROS2 and DDS halves.
 

{topicforge-0.6.0 → topicforge-0.6.1}/src/topicforge/tools/handlers.py

@@ -550,7 +550,12 @@ def register_tools(
             "graph), this reads **offline bag content** for post-mortem "
             "analysis. Supported formats: MCAP "
             "(`.mcap`), ROS 2 rosbag2 SQLite (`.db3`), ROS 1 legacy chunked "
-            "binary (`.bag`), detected from the file extension. Returns a "
+            "binary (`.bag`), detected from the file extension. Returns the "
+            "**first** `count` messages of the topic in recording order, not "
+            "the last ones. **Clocks**: `timestamp_ns` is the message's own "
+            "`header.stamp` (`stamp_source` `header`) when it has a top-level "
+            "header, else the bag record time (`stamp_source` `recorded`); "
+            "`recorded_ns` is always the bag record time. Returns a "
             "`SampleResult` in the same shape as `peek_dds_samples`: each "
             "sample's `payload` carries a `_decode_status` annotation (`full` /"
             " `partial` / `raw`). `count` defaults to 5 and is silently clamped"

{topicforge-0.6.0 → topicforge-0.6.1}/tests/integration/ros2/test_live_adapter.py

@@ -283,3 +283,27 @@ def test_a_short_latched_result_hints_count_one(adapter: Ros2CliAdapter) -> None
     assert result.count == 1
     assert result.note is not None and "fewer than requested" in result.note
     assert "latched" in result.note
+
+
+def test_peek_bag_samples_names_the_clock_of_each_timestamp(
+    adapter: Ros2CliAdapter, bag: Path
+) -> None:
+    scan = adapter.peek_bag_samples(str(bag), "/scan", 1).samples[0]
+    assert scan.stamp_source == "header"
+    assert scan.recorded_ns is not None
+    assert "__msgtype__" not in str(scan.payload) and "_msgtype" not in str(scan.payload)
+
+    text = adapter.peek_bag_samples(str(bag), "/robot_description_lite", 1).samples[0]
+    assert text.stamp_source == "recorded"
+    assert text.timestamp_ns == text.recorded_ns
+
+
+def test_health_reports_the_sim_clock_publisher(adapter: Ros2CliAdapter) -> None:
+    from topicforge.config import Settings
+    from topicforge.services import HealthService
+
+    assert adapter.sim_clock_published() is True
+    settings = Settings(
+        mode="live", log_level="INFO", ros2_executable="ros2", telemetry_enabled=False
+    )
+    assert HealthService(settings, adapter).report().sim_clock_published is True

{topicforge-0.6.0 → topicforge-0.6.1}/tests/test_bag_omnisim_humble.py

@@ -148,3 +148,19 @@ def test_peek_without_embedded_definitions_note_is_absent_for_self_describing_ba
     bag = _write_mcap_bag(tmp_path)
     result = BagService().peek_samples(str(bag), "/fast", 1)
     assert result.note is None or "no message definitions" not in result.note
+
+
+def test_peek_labels_the_clock_of_each_timestamp(bag_path: str) -> None:
+    scan = BagService().peek_samples(bag_path, "/scan", 1).samples[0]
+    header = scan.payload["header"]["stamp"]
+    assert scan.stamp_source == "header"
+    assert scan.timestamp_ns == header["sec"] * 1_000_000_000 + header["nanosec"]
+    assert scan.recorded_ns is not None
+
+    log = BagService().peek_samples(bag_path, "/rosout", 1).samples[0]
+    assert log.stamp_source == "header" or log.timestamp_ns == log.recorded_ns
+
+
+def test_peek_payload_has_no_message_type_markers(bag_path: str) -> None:
+    payload = BagService().peek_samples(bag_path, "/scan", 1).samples[0].payload
+    assert "msgtype" not in str(payload)

{topicforge-0.6.0 → topicforge-0.6.1}/tests/test_cdr_decoder.py

@@ -267,3 +267,10 @@ def test_cap_reaches_arrays_inside_nested_samples() -> None:
 
     decoded = decode_dynamic_sample(Outer(Inner(np.zeros(9000))), max_array_elements=100)
     assert len(decoded["inner"]["ranges"]) == 101  # type: ignore[index]
+
+
+def test_iter_field_names_skips_dunder_markers() -> None:
+    from dataclasses import make_dataclass
+
+    msg = make_dataclass("Msg", [("x", int), ("__msgtype__", str)])(x=1, __msgtype__="a/msg/B")
+    assert iter_field_names(msg) == ["x"]

{topicforge-0.6.0 → topicforge-0.6.1}/tests/test_health.py

@@ -215,3 +215,59 @@ def test_report_leaves_tracker_fields_empty_without_an_observer() -> None:
     report = HealthService(_settings(), _adapter("mock")).report()
 
     assert report.observer_started_ns is None and report.tracker_errors is None
+
+
+def test_sim_clock_is_unknown_in_mock_mode() -> None:
+    assert HealthService(_settings(), MockAdapter()).report().sim_clock_published is None
+
+
+class _ClockAdapter(_NamedAdapter):
+    def __init__(self, outcome: object) -> None:
+        super().__init__("ros2_cli")
+        self._outcome = outcome
+
+    def sim_clock_published(self) -> bool | None:
+        if isinstance(self._outcome, Exception):
+            raise self._outcome
+        return self._outcome  # type: ignore[return-value]
+
+
+@pytest.mark.parametrize(
+    ("outcome", "expected"), [(True, True), (False, False), (None, None), (RuntimeError(), None)]
+)
+def test_sim_clock_hint_comes_from_the_adapter_and_never_breaks_health(
+    outcome: object, expected: bool | None
+) -> None:
+    adapter: Any = _ClockAdapter(outcome)
+    assert HealthService(_settings(), adapter).report().sim_clock_published is expected
+
+
+def test_cli_adapter_reads_publisher_count_of_clock(monkeypatch: pytest.MonkeyPatch) -> None:
+    from topicforge.adapters.ros2_live import Ros2CliAdapter
+
+    adapter = Ros2CliAdapter()
+    outputs = {
+        "Type: rosgraph_msgs/msg/Clock\nPublisher count: 1\nSubscription count: 0\n": True,
+        "Type: rosgraph_msgs/msg/Clock\nPublisher count: 0\nSubscription count: 2\n": False,
+    }
+    for text, expected in outputs.items():
+        monkeypatch.setattr(adapter, "_run", lambda cmd, timeout=8.0, t=text: t)
+        assert adapter.sim_clock_published() is expected
+
+
+def test_cli_adapter_clock_probe_failure_modes(monkeypatch: pytest.MonkeyPatch) -> None:
+    from topicforge.adapters.base import AdapterError
+    from topicforge.adapters.ros2_live import Ros2CliAdapter
+
+    adapter = Ros2CliAdapter()
+
+    def unknown(cmd: list[str], timeout: float = 8.0) -> str:
+        raise AdapterError("failed (exit 1): Unknown topic '/clock'")
+
+    def timed_out(cmd: list[str], timeout: float = 8.0) -> str:
+        raise AdapterError("timed out after 8.0s")
+
+    monkeypatch.setattr(adapter, "_run", unknown)
+    assert adapter.sim_clock_published() is False
+    monkeypatch.setattr(adapter, "_run", timed_out)
+    assert adapter.sim_clock_published() is None

{topicforge-0.6.0 → topicforge-0.6.1}/tests/test_live_sample_notes.py

@@ -54,7 +54,9 @@ def test_timeout_bounds_the_topic_lookup_too(monkeypatch: pytest.MonkeyPatch) ->
     _stub_info(monkeypatch, delay_s=0.4)
     seen = _stub_echo(monkeypatch, EchoRun())
     Ros2CliAdapter().sample_messages("/imu", count=1, timeout_s=5)
-    assert 4.0 < seen[0]["deadline_s"] <= 4.6
+    # Upper bound leaves room for the ~16 ms Windows clock tick: a 0.4 s sleep can
+    # measure as 0.39 s there.
+    assert 4.0 < seen[0]["deadline_s"] <= 4.65
 
 
 def test_the_topic_lookup_never_waits_longer_than_timeout_s(