topicforge 0.5.4__tar.gz → 0.5.5__tar.gz

{topicforge-0.5.4 → topicforge-0.5.5}/CHANGELOG.md

@@ -7,6 +7,127 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-10-02
+
+Driven by a blind evaluation: agents given only TopicForge's tools had to
+diagnose live DDS buses with planted faults. The first rounds (on 0.5.4) found
+wrong blame on QoS, missed Liveliness and Ownership faults, hand-joined GUIDs
+and empty results read as "healthy". After the changes below, 16 of 16
+scenarios were diagnosed correctly, with no false alarm on a healthy bus.
+
+### Added
+
+- **`list_endpoints`, the 12th MCP tool.** Returns every announced DDS writer
+  and reader as a typed `EndpointInfo` (role, topic, type, owning participant
+  guid, name and vendor, structured QoS, announcement timestamp) plus a
+  `by_topic` roll-up that flags orphans (`no_reader`, `no_writer`). TopicForge's
+  own endpoints are excluded unless `include_observer`, and counted in
+  `excluded_observer_endpoints`. Endpoints of a participant that left are kept
+  (200 entries, 1 hour) and shown as `departed_writers` / `departed_readers`;
+  `include_departed` lists them. Served by Cyclone and the mock. Fast raises a
+  clear "not supported yet" error.
+- **Continuous discovery tracking on Cyclone.** A daemon thread (0.5 s period)
+  is the only code that reads the builtin discovery topics and feeds in-memory
+  caches that every discovery tool reads. Lifecycle no longer moves only when a
+  tool is called: a node restarted three times shows as 3 `lost` and 4
+  `discovered`, dated by DDS. The 2 s warm-up sleep is gone.
+- Timestamps on `participant_events` and `list_participants`: `announced_ns`,
+  `lost_ns`, `lost_time_source`, and on events `time_source` and `observed_ns`.
+  A DDS source timestamp and a local observation are never mixed.
+- `health_check` gains `now_ns`, `observer_started_ns`, `observed_domain_note`
+  and the tracker status (`tracker_running`, `tracker_passes`, `tracker_errors`,
+  `tracker_last_pass_ns`).
+- `QosProfile` gains optional `liveliness_kind`, `liveliness_lease_ns`,
+  `ownership_kind`, `ownership_strength`, `partitions`, `latency_budget_ns`,
+  `destination_order` and `data_representation`, read from Cyclone discovery.
+  A missing Partition policy is reported as `[""]` everywhere.
+- `peek_dds_samples` on `DCPSPublication`, `DCPSSubscription` and
+  `DCPSParticipant` carries structured `role`, `participant_guid`,
+  `participant_name`, `type_id`, `qos`, `announced_ns` and `is_observer`, and
+  sets `timestamp_ns` from the announcement. `_raw_text` is kept only for a
+  sample with nothing structured to read, truncated to 300 characters.
+- `peek_dds_samples` on a builtin topic returns the cached discovery state, not
+  a stream.
+- Topic filters accept `rt/x` and `x` interchangeably and report which form
+  matched. A filter that matches nothing returns the list of known topics.
+- Examples: the generic role nodes take partition, liveliness and ownership
+  options.
+
+### Changed
+
+- **Breaking: `detect_qos_mismatches` returns a `MismatchScan` envelope instead
+  of a bare list.** To migrate, read `["reports"]` where you used the list. The
+  envelope also carries `matched`, `not_matched`, `hints`, `pairs_checked`,
+  `topics_scanned`, `policies_checked`, `policies_unchecked` and
+  `mode_effective`. Why: an empty list was read as a healthy bus although only
+  four policies were checked, and readers and writers in different partitions
+  were blamed on Reliability.
+- Partition is checked first (`*` and `?` wildcards; a wildcard against a
+  wildcard never matches). A pair it separates is a `not_matched` entry with
+  reason `partition`; differing type names give reason `type_name`. The RxO
+  rules are not run on either. A `not_matched` pair lists the policies that
+  would be incompatible if it matched (`latent_incompatible_policies`).
+- Liveliness (kind and lease), LatencyBudget, Ownership (kind equality),
+  DestinationOrder and DataRepresentation join Reliability, Durability and
+  Deadline. History stays a labelled `risky` finding. A policy a side did not
+  announce is skipped, never guessed.
+- `MismatchReport` gains, additively, the reader and writer participant guid and
+  name, type names, `details` (requested and offered value, failed rule) and
+  `unchecked`.
+- Hints cover orphan topics whose names differ by at most 2 edits (compared
+  against all topics), path-suffix matches and XTypes type id differences (a
+  note, never a mismatch). Hints are prioritized and say how many were omitted.
+- A late joiner is not a hint (it is normal on most buses): a `MatchedPair` is
+  flagged `late_joiner` when its writer is VOLATILE and the reader, on the same
+  host, appeared more than 1 s later.
+- `reports`, `matched` and `not_matched` are capped at 200 entries each, with
+  `reports_total`, `matched_total`, `not_matched_total` and `truncated`.
+- `topic_metrics` reports a `status`, and on a user topic says it has no data
+  instead of returning zeros. `peek_dds_samples` on a user topic returns count
+  0 and a note. `ParticipantInfo` and endpoints gain `is_observer`, and
+  `vendor_source` says where a vendor came from.
+- Tool descriptions no longer carry internal history, and state the
+  single-domain and EXCLUSIVE-ownership facts.
+- `EndpointInfo.activity` is reserved (always `None`) with an `activity_note`
+  saying liveness is not observed.
+
+### Fixed
+
+- Infinite durations (cyclonedds reports 9223372036854775807) are normalized
+  to `None`; an infinite Deadline used to surface as a 9.2e18 ns deadline.
+- The Cyclone discovery tracker is stopped at interpreter exit.
+- A race between the tracker and a tool call could mark a live participant as
+  lost for good; a failed read could drop a participant's departure; endpoints
+  of a participant that had just left could stay listed as live. The tracker
+  and every tool now share one lock, and taken samples are never discarded.
+- The cyclonedds Python binding is not thread-safe when it converts QoS: two
+  threads in `take()` at once corrupted the heap on Windows. Every binding call
+  now goes through one process-wide lock, and tool handlers no longer call the
+  binding at all.
+- If every tracker pass fails, tools no longer wait 3 s each: warm-up is bounded
+  once. `health_check` reports failed passes and cache evictions.
+- An unreadable QoS duration is treated as unknown (`QosProfile.unknown_policies`),
+  not as infinite, so it cannot produce a false Deadline incompatibility.
+- Topic-name typo hints are bounded (banded edit distance, orphan cap, call
+  budget), so a bus with a thousand topics does not stall the call.
+- Partition matching was checked against a live Cyclone bus: `*` and `?` are
+  wildcards, `[...]` is literal, and two wildcard expressions never match each
+  other. Pinned by tests.
+
+### Known limits
+
+- A hung writer (alive, lease renewed, no data) is not observable without a
+  data probe. An opt-in probe is planned for 0.5.6.
+- A crash and a clean leave cannot be told apart, and `lost_ns` is an upper
+  bound of the death (the lease expiry after a crash).
+- A participant that cycles faster than the discovery history depth between two
+  tracker passes can be missed.
+- The Fast DDS backend has never run on a bus, and `list_endpoints` is not
+  supported there.
+- DDS Security is not supported.
+- User-topic payload decoding is disabled, so `topic_metrics` has no data on
+  user topics.
+
 ## [0.5.4] - 2026-10-02
 
 First run of the DDS code against a live multi-vendor bus (Windows 11, a
@@ -1114,7 +1235,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.5.4...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...HEAD
+[0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5
 [0.5.4]: https://github.com/yaniswav/TopicForge/compare/v0.5.3...v0.5.4
 [0.5.3]: https://github.com/yaniswav/TopicForge/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/yaniswav/TopicForge/compare/v0.5.1...v0.5.2

{topicforge-0.5.4 → topicforge-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.5.4
+Version: 0.5.5
 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
@@ -69,7 +69,7 @@ Description-Content-Type: text/markdown
 
 A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS, without being able to publish to the bus or command a robot. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure and no permission system to audit.
 
-Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **eleven typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **twelve typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
 
 For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Every conformant vendor announces itself there, so a Cyclone participant also sees RTI Connext, OpenDDS, CoreDX and Dust DDS endpoints without any proprietary binding. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
 
@@ -101,7 +101,7 @@ Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code:
 
 ## Tools
 
-All eleven tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+All twelve tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
 
 | Tool                    | Purpose                                                                                          |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
@@ -116,6 +116,7 @@ All eleven tools are read-only. Every response except `health_check` carries `mo
 | `participant_events`    | Timeline of participant `discovered` / `lost` events                                             |
 | `topic_metrics`         | Frequency, sequence-gap and latency schema; data only for builtin discovery topics               |
 | `peek_bag_samples`      | Decoded samples from a recorded bag (needs `pip install topicforge[bags]`)                       |
+| `list_endpoints`        | DDS writers and readers with structured QoS, per-topic roll-up that flags orphans (writer with no reader, reader with no writer) |
 
 Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
 
@@ -136,7 +137,7 @@ pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cycl
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
-`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the five DDS tools to the DDS backend.
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the seven DDS tools to the DDS backend.
 
 A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error, since the Pro tier is retired (see [`docs/pro.md`](docs/pro.md)). Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
 
@@ -156,9 +157,12 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 ## Limitations
 
 - **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 reports that the topic is announced on the bus and returns one placeholder sample (`_decode_status="raw"`, empty `_raw_bytes_hex`); no traffic is read. Consequently `topic_metrics` only has data for the builtin discovery topics, its observed frequency is the cadence of your own `peek_dds_samples` calls, and latency and sequence gaps are `null`. It is a discovery-layer probe, not a publish-rate monitor.
+- **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 for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - **Cyclone vendor ids.** Participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
-- **DDS Security is not handled.** A participant without credentials sees an empty secure bus. `detect_qos_mismatches` covers Reliability, Durability, History and Deadline; Liveliness, Ownership and Partition are not checked.
+- **Single domain.** The server observes the domain it joined at startup; changing it needs a restart.
+- **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)** runs `ros2 topic echo --csv --once` with a short timeout; a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones.
 - **`analyze_bag` (live)** parses `ros2 bag info` text and does not use `rosbags`; anomaly detection is mock-only. `peek_bag_samples` is the only tool that reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
 - **Synchronous handlers.** The tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
@@ -180,10 +184,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the eleven tools, never argument values              |
+| `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.5.3"`       | TopicForge server version                                   |
+| `version`    | `"0.5.5"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

{topicforge-0.5.4 → topicforge-0.5.5}/README.md

@@ -10,7 +10,7 @@
 
 A read-only MCP (Model Context Protocol) server that lets an AI agent inspect a ROS2 graph, recorded bag files and the DDS layer underneath ROS, without being able to publish to the bus or command a robot. It is read-only by **architecture**, not by configuration: there is no write path to misconfigure and no permission system to audit.
 
-Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **eleven typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
+Without grounding, an LLM asked about a robot will invent topic names, message types and bag contents. TopicForge gives it **twelve typed tools** that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. It is aimed at ROS2 developers, robotics ML/CV engineers and teams that cannot accept a write path into a production stack.
 
 For DDS, TopicForge joins a domain as a read-only participant through one open-source binding (Eclipse CycloneDDS from PyPI) and reads the builtin discovery topics that the OMG DDS-RTPS protocol standardizes. Every conformant vendor announces itself there, so a Cyclone participant also sees RTI Connext, OpenDDS, CoreDX and Dust DDS endpoints without any proprietary binding. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
 
@@ -42,7 +42,7 @@ Then ask it to list the topics or to analyze `/tmp/demo.mcap`. For Claude Code:
 
 ## Tools
 
-All eleven tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
+All twelve tools are read-only. Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
 
 | Tool                    | Purpose                                                                                          |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
@@ -57,6 +57,7 @@ All eleven tools are read-only. Every response except `health_check` carries `mo
 | `participant_events`    | Timeline of participant `discovered` / `lost` events                                             |
 | `topic_metrics`         | Frequency, sequence-gap and latency schema; data only for builtin discovery topics               |
 | `peek_bag_samples`      | Decoded samples from a recorded bag (needs `pip install topicforge[bags]`)                       |
+| `list_endpoints`        | DDS writers and readers with structured QoS, per-topic roll-up that flags orphans (writer with no reader, reader with no writer) |
 
 Walkthroughs against the mock, each with the exact tool calls and payloads, are in [`examples/`](examples/README.md). To run the DDS tools against a real bus with several programs and vendors, see [`examples/dds/README.md`](examples/dds/README.md) (`python examples/dds/run_all.py`).
 
@@ -77,7 +78,7 @@ pip install topicforge[dds]                      # Eclipse CycloneDDS ([dds-cycl
 TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
 ```
 
-`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the five DDS tools to the DDS backend.
+`TOPICFORGE_DDS_BACKEND` accepts `mock` (default), `cyclone`, `fast` and `auto` (`fast`, then `cyclone`, then `mock`, whichever binding imports). An explicit value is honoured with or without `ros2` on PATH, in any mode except `mock`. If the binding is missing or the participant cannot start, the server logs a warning naming the cause and falls back to the ROS2 CLI alone, or to the mock fixtures. When both `ros2` and a DDS backend are up, a composite adapter routes the five ROS2 graph and bag tools to the CLI and the seven DDS tools to the DDS backend.
 
 A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Python binding is not on PyPI: build it from eProsima's sources and install it next to TopicForge. There is no `[dds-fast]` extra. `opendds` and `dust` are permanent stubs that never serve. `rti`, `opensplice`, `coredx` and `intercom` are rejected with a configuration error, since the Pro tier is retired (see [`docs/pro.md`](docs/pro.md)). Full backend selection, the routing table and the QoS mismatch scenario are in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md); error messages are in [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md).
 
@@ -97,9 +98,12 @@ Samples with comments are in [`.env.example`](.env.example). Any invalid value s
 ## Limitations
 
 - **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 reports that the topic is announced on the bus and returns one placeholder sample (`_decode_status="raw"`, empty `_raw_bytes_hex`); no traffic is read. Consequently `topic_metrics` only has data for the builtin discovery topics, its observed frequency is the cadence of your own `peek_dds_samples` calls, and latency and sequence gaps are `null`. It is a discovery-layer probe, not a publish-rate monitor.
+- **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 for 0.5.6. A crash and a clean leave cannot be told apart, and `lost_ns` is an upper bound of the death.
 - **Cyclone vendor ids.** Participants that do not follow the RTPS vendor-id convention in their GUID prefix (Dust DDS, and RTI by default) are reported with vendor `unknown`.
-- **DDS Security is not handled.** A participant without credentials sees an empty secure bus. `detect_qos_mismatches` covers Reliability, Durability, History and Deadline; Liveliness, Ownership and Partition are not checked.
+- **Single domain.** The server observes the domain it joined at startup; changing it needs a restart.
+- **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)** runs `ros2 topic echo --csv --once` with a short timeout; a topic with no current publisher returns an empty sample. `timestamp_ns` is the message `header.stamp` for `Header`-stamped types and `0` for headerless ones.
 - **`analyze_bag` (live)** parses `ros2 bag info` text and does not use `rosbags`; anomaly detection is mock-only. `peek_bag_samples` is the only tool that reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
 - **Synchronous handlers.** The tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
@@ -121,10 +125,10 @@ When on, each tool call emits one event with exactly six fields:
 
 | Field        | Example         | Notes                                                       |
 | ------------ | --------------- | ----------------------------------------------------------- |
-| `tool_name`  | `"list_topics"` | One of the eleven tools, never argument values              |
+| `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.5.3"`       | TopicForge server version                                   |
+| `version`    | `"0.5.5"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 

topicforge-0.5.5/docs/DDS_QUICKSTART.md

@@ -0,0 +1,126 @@
+# DDS quickstart
+
+A short tour of TopicForge's DDS observability tools. The server joins the bus as a **read-only DDS-RTPS participant** and, by the OMG protocol guarantee, observes every conformant vendor through the builtin discovery topics. The `MiddlewareAdapter` protocol has no write method, so the MCP client cannot publish back on any backend. This guide does not assume ROS2.
+
+**Validation status.** The Cyclone adapter has run against a live bus, with a Python / Cyclone participant and Dust DDS participants in Rust, Python and C, on Windows and in CI (Ubuntu and Windows, `.github/workflows/demo.yml`); see [`scripts/integration/README.md`](../scripts/integration/README.md). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed yet. For runnable live scenarios (who is on the bus, why two nodes cannot talk, a node that crashed, a late joiner that misses data), see [`examples/dds/README.md`](../examples/dds/README.md). Multi-vendor positioning: [`dds-interop-matrix.md`](dds-interop-matrix.md).
+
+## 1. Mock mode
+
+The mock fixtures expose every tool with no DDS SDK:
+
+```bash
+pip install topicforge
+TOPICFORGE_MODE=mock python -m topicforge
+```
+
+- `list_participants(domain_id=0)` returns four participants: two CycloneDDS (`mock-robot`, `mock-laptop`), one Fast DDS (`mock-aerospace-node`) and one Dust DDS in Rust (`mock-rust-node`). The `vendor` field comes from the OMG vendor id: `cyclone`, `fast`, `rti`, `rti_micro`, `opensplice`, `opendds`, `coredx`, `intercom`, `dust`, `mock` or `unknown`.
+- `detect_qos_mismatches(topic=None)` returns a `MismatchScan` with one report for `/dds/qos_mismatch`: a RELIABLE reader against a BEST_EFFORT writer.
+- `list_endpoints()` returns the mock writers and readers with their QoS and a `by_topic` roll-up.
+- `peek_dds_samples(topic="/dds/well_matched", count=3)` returns three deterministic samples. The mock only knows `/dds/well_matched`, `/dds/qos_mismatch`, `/dds/ddsforge/example` and `/dds/ddsforge/opaque`, and raises "Unknown DDS topic" for anything else.
+- `topic_metrics(topic="/dds/heartbeat_10hz", window_seconds=60)` returns a pre-filled 10 Hz buffer (100 samples, no gaps, 50 ms latency). A live adapter behaves differently, see section 5 and [`examples/04-monitor-topic-frequency.md`](../examples/04-monitor-topic-frequency.md).
+
+The mock illustrates payload shapes that no live adapter produces today, such as the `"full"` decode status on `/dds/ddsforge/example`.
+
+## 2. Live mode: choose a backend
+
+**Cyclone** is the one with a PyPI install path:
+
+```bash
+pip install topicforge[dds]             # same as [dds-cyclone]
+TOPICFORGE_DDS_BACKEND=cyclone python -m topicforge
+```
+
+`cyclonedds` publishes wheels for CPython 3.10 to 3.13 on Windows, Linux and macOS (as of 11.0.1). A background thread reads the builtin DCPS topics through `BuiltinDataReader`. On a real bus `list_participants` reports each participant's `name` (EntityName QoS) and `hostname` (the `__Hostname` discovery property) when the remote participant sets them, and the vendor from the first two bytes of the GUID prefix; implementations that do not follow that convention (Dust DDS, RTI by default) show vendor `unknown`.
+
+**Fast DDS** has no PyPI install path. The `fastdds` binding is not published, so TopicForge declares no extra for it. Build eProsima's [Fast-DDS-python](https://github.com/eProsima/Fast-DDS-python) from source (it needs the Fast DDS C++ libraries and SWIG), install it into the same environment, then `TOPICFORGE_DDS_BACKEND=fast`. The adapter was written against the 2.6.x API and has never run against a bus.
+
+**Auto** (`TOPICFORGE_DDS_BACKEND=auto`) probes importable bindings in the order `fast`, `cyclone`, `mock`. With only the PyPI extra installed it resolves to Cyclone. `opendds` and `dust` are permanent stubs that always report unavailable and are not in the chain.
+
+**Domain.** `TOPICFORGE_DDS_DOMAIN_ID` (`0..232`, default `0`) is joined at startup; the `domain_id` tool parameter exists for protocol uniformity only. Changing domains needs a restart.
+
+**Commercial vendors.** `rti`, `opensplice`, `coredx` and `intercom` are rejected at startup with a configuration error. You do not need them to observe an RTI bus; for what a native RTI adapter would add (secure domains with vendor credentials, shared-memory-only deployments) see [`pro.md`](pro.md).
+
+## 3. The QoS mismatch scenario
+
+The canonical "my subscriber does not receive" case. Against the mock:
+
+```
+> Detect QoS mismatches on the current bus.
+
+[tool call: detect_qos_mismatches]
+{
+  "reports": [
+    {
+      "topic": "/dds/qos_mismatch",
+      "reader_guid": "...", "writer_guid": "...",
+      "reader_participant_name": "lidar_driver", "writer_participant_name": "nav_planner",
+      "incompatible_policies": ["Reliability"],
+      "severity": "incompatible",
+      "details": [{"policy": "Reliability", "requested": "RELIABLE",
+                   "offered": "BEST_EFFORT", "rule": "a RELIABLE reader needs a RELIABLE writer"}],
+      "mode_effective": "mock"
+    }
+  ],
+  "not_matched": [],
+  "hints": ["Topic '/dds/ddsforge/opaque' has writers but no reader: there is no pair to compare."],
+  "pairs_checked": 3, "topics_scanned": 4,
+  "policies_checked": ["Reliability", "Durability", "Deadline", "Liveliness", "..."],
+  "policies_unchecked": ["Presentation: ...", "..."],
+  "mode_effective": "mock"
+}
+```
+
+The result is a `MismatchScan` envelope. Live adapters render GUIDs in dotted form (`xxxxxxxx.xxxxxxxx.xxxxxxxx.xxxxxxxx`). From this the agent can suggest a concrete fix: the writer is BEST_EFFORT but the reader requires RELIABLE, so relax the reader or upgrade the writer. The analysis is vendor-neutral pure code (`adapters/common/qos_analyzer.py`, `qos_scan.py`) over canonical `QosProfile` models, so it does not depend on which backend produced the discovery samples.
+
+Order of checks per reader/writer pair: Partition first (wildcards `*` and `?` on one side match; wildcard against wildcard never does), then the type name, then the RxO policies. A pair separated by partition or type goes to `not_matched` and no QoS rule is run on it, so a partition split is never reported as a Reliability problem; an empty `reports` with a non-empty `not_matched` still means no data flows. RxO policies compared: Reliability, Durability, Deadline, Liveliness (kind and lease), LatencyBudget, Ownership (kind only), DestinationOrder, DataRepresentation. History (KEEP_ALL reader, KEEP_LAST writer) is reported as `risky`, not as an incompatibility. A policy a side did not announce is skipped and counted in a hint. `policies_unchecked` lists what stays out of scope (Presentation, XTypes assignability, runtime liveliness, anything not discoverable): discovery shows declared QoS, not runtime behavior, so an empty result is not proof the bus is healthy.
+
+## 4. Composite adapter and backend selection
+
+When `ros2` is on PATH and a DDS backend starts, TopicForge builds both a `Ros2CliAdapter` and the DDS adapter behind a `CompositeAdapter`: the five ROS2 graph and bag tools go to the CLI, the seven DDS tools to the DDS backend. An explicit DDS backend (`cyclone`, `fast`, `auto`) is honoured in every mode except `mock`, including on a host without `ros2`.
+
+| `TOPICFORGE_MODE` | `TOPICFORGE_DDS_BACKEND` | `ros2` on PATH | Active adapter | ROS2 graph and bag tools | DDS tools |
+| --- | --- | --- | --- | --- | --- |
+| `mock` | any | any | `MockAdapter` | fixtures | fixtures |
+| `live` / `auto` | `mock` (default) | yes | `Ros2CliAdapter` | CLI | raise "DDS module is not active" |
+| `live` / `auto` | `cyclone` / `fast` / `auto` | yes | `CompositeAdapter` | CLI | real binding |
+| `live` / `auto` | `cyclone` / `fast` / `auto` | no | the DDS adapter alone | raise "DDS observability only" | real binding |
+| `live` / `auto` | `cyclone` / `fast`, binding missing or participant fails | any | `Ros2CliAdapter` if `ros2` is on PATH, else `MockAdapter` | CLI, or fixtures | raise, or fixtures |
+| `live` / `auto` | `mock` | no | `MockAdapter` | fixtures | fixtures |
+
+A DDS problem never prevents startup: the server logs a warning naming the cause and keeps going. Only an invalid or removed configuration value stops it. `health_check` reports what was actually built: `mode` (can differ from `requested_mode`), `ros_backend` (`ros2_cli`, `mock`, `none`) and `dds_backend` (`cyclone`, `fast`, `mock`, `none`).
+
+## 5. Scope of the discovery tools
+
+`list_endpoints` returns every announced writer and reader as a typed record: role, topic, type, owning participant (guid, name, vendor), structured QoS and announcement time. Its `by_topic` roll-up flags orphans (`no_reader`, `no_writer`) and lists endpoints of participants that left under `departed_writers` / `departed_readers`. TopicForge's own endpoints are excluded unless `include_observer` is set. Cyclone and the mock serve it; the Fast DDS backend raises "not supported yet". Use it first to find out who talks on which topic, and `detect_qos_mismatches` to learn why they do not match.
+
+`peek_dds_samples` is structured on the three builtin discovery topics, with both backends. Builtin names carry no leading `/`:
+
+```
+peek_dds_samples(topic="DCPSParticipant", count=5)
+peek_dds_samples(topic="DCPSSubscription", count=10)
+peek_dds_samples(topic="DCPSPublication", count=10)
+```
+
+Each sample is the cached current discovery state, not a stream. The payload carries `vendor`, `guid`, `topic_name` and, for endpoints, `role`, `participant_guid`, `participant_name`, `type_id`, `qos`, `announced_ns` and `is_observer`. The sample `timestamp_ns` is the announcement time.
+
+**User topics are not decoded.** For a user topic the tool returns count 0 and a `note`:
+
+```json
+{
+  "topic": "/my/topic",
+  "count": 0,
+  "samples": [],
+  "mode_effective": "live",
+  "note": "payload decoding is disabled for DDS user topics, so no samples are returned; this does not mean the topic is silent. Use list_endpoints for the topic's presence, writers, readers and QoS"
+}
+```
+
+An empty result says nothing about traffic. The earlier decode path never worked on either backend and is disabled until it can be validated against a real bus. The `"full"` and `"partial"` decode statuses stay in the schema and the mock emits examples of them, but no live adapter produces them.
+
+**`topic_metrics` only has data for the builtin topics.** For a user topic it returns `status="unsupported_user_topic"`, and its null fields are not a measurement. For a builtin topic, `frequency_hz_observed` is how often you called `peek_dds_samples` (one call yields `null`), `sequence_numbers_available` is `false` and the latency percentiles are `null`, because builtin samples carry no publish timestamp. `frequency_hz_declared` is `1 / deadline` for the shortest Deadline a writer announced, when there is one. Use it to watch discovery-layer churn, not to check a publish rate.
+
+**Lifecycle.** On Cyclone a background thread (0.5 s period) reads the three builtin discovery topics and feeds the caches behind every discovery tool, so `participant_events` and `list_participants` do not depend on when you call them. A participant that cycles faster than the discovery history depth between two passes can still be missed. Event times come from DDS (`announced_ns`, `lost_ns`), with `time_source` saying which clock. A `lost` time is an upper bound of the death: a crash is only noticed when the lease expires, and a crash cannot be told from a clean leave. A writer that is alive but silent is not observable without reading its data. Fast DDS captures arrival and removal through listener callbacks.
+
+## 6. Open work
+
+Wider real-bus validation (Fast DDS, RTI, OpenDDS, CoreDX, OpenSplice; re-enabling user-topic decoding depends on it), an opt-in data probe to catch a hung writer (planned for 0.5.6), and DDS Security, which is not handled at all: a participant without credentials sees an empty secure bus. The roadmap is in [`product-plan.md`](product-plan.md). Errors and fixes: [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md). Report what you see on a real domain at https://github.com/yaniswav/TopicForge/issues.

{topicforge-0.5.4 → topicforge-0.5.5}/docs/TESTING.md

@@ -4,7 +4,7 @@ How to get a working ROS2 environment to point TopicForge at, and how to wire it
 
 | You want to... | Time | Path |
 | --- | --- | --- |
-| Try the eleven tools without installing ROS2 | 5 min | [Mock mode](#mock-mode) |
+| Try the twelve tools without installing ROS2 | 5 min | [Mock mode](#mock-mode) |
 | Live mode on Windows | 45 min | [WSL2 + Humble](#wsl2--ros2-humble-windows-recommended) |
 | Live mode on Ubuntu | 20 min | [Linux native](#linux-native) |
 | Throwaway environment | 15 min | [Docker](#docker) |
@@ -102,4 +102,4 @@ TopicForge speaks MCP over stdio; any compliant client can spawn it with a comma
 }
 ```
 
-That is the Claude Desktop shape (`claude_desktop_config.json`); restart the app and the eleven tools appear under the hammer icon. For Claude Code run `claude mcp add topicforge -- topicforge`. Cursor, Continue and Cline accept the same stdio config. If the `topicforge` script is not on PATH, use `"command": "python", "args": ["-m", "topicforge"]`, or the absolute path of the binary inside your venv: desktop clients do not inherit your shell's PATH or venv activation.
+That is the Claude Desktop shape (`claude_desktop_config.json`); restart the app and the twelve tools appear under the hammer icon. For Claude Code run `claude mcp add topicforge -- topicforge`. Cursor, Continue and Cline accept the same stdio config. If the `topicforge` script is not on PATH, use `"command": "python", "args": ["-m", "topicforge"]`, or the absolute path of the binary inside your venv: desktop clients do not inherit your shell's PATH or venv activation.

{topicforge-0.5.4 → topicforge-0.5.5}/docs/TROUBLESHOOTING.md

@@ -31,7 +31,7 @@ You called a ROS2 graph or bag tool (`list_topics`, `get_topic_info`, `sample_me
 2. Re-run with `TOPICFORGE_MODE=live` and your existing `TOPICFORGE_DDS_BACKEND`.
 3. Check `health_check`: `ros_backend` should be `"ros2_cli"` and `dds_backend` your vendor.
 
-If you want a DDS-only deployment, the message is expected: you use the five DDS tools and the two bag tools raise it. For offline work use `TOPICFORGE_MODE=mock`. The opposite error, "DDS module is not active", means `TOPICFORGE_DDS_BACKEND` is `mock` (the default) while a live adapter serves; set it to `cyclone`.
+If you want a DDS-only deployment, the message is expected: you use the seven DDS tools and the two bag tools raise it. For offline work use `TOPICFORGE_MODE=mock`. The opposite error, "DDS module is not active", means `TOPICFORGE_DDS_BACKEND` is `mock` (the default) while a live adapter serves; set it to `cyclone`.
 
 ## "rosbags"
 

{topicforge-0.5.4 → topicforge-0.5.5}/docs/TUTORIEL.md

@@ -31,7 +31,7 @@ Add it to your MCP client. For Claude Desktop, edit `claude_desktop_config.json`
 }
 ```
 
-Restart Claude Desktop. All eleven tools appear under the hammer icon. Ask something like:
+Restart Claude Desktop. All twelve tools appear under the hammer icon. Ask something like:
 
 > What topics are being published right now, and what message types do they carry?
 

{topicforge-0.5.4 → topicforge-0.5.5}/docs/dds-interop-matrix.md

@@ -25,7 +25,7 @@ Notice: a Rust implementation is in this list. That is the OMG-DDS promise: lang
 
 When you install TopicForge with DDS support (`pip install topicforge[dds]`, which installs the CycloneDDS Python binding), it joins the domain you point it at as a read-only participant. The Fast DDS adapter works the same way, but its Python binding is not on PyPI: you build it from eProsima's sources (see [`DDS_QUICKSTART.md`](DDS_QUICKSTART.md)).
 
-From there, TopicForge's discovery-based tools (`list_participants`, `detect_qos_mismatches`, `participant_events`, and `peek_dds_samples` on the builtin `DCPS*` topics) see **every conformant participant on the bus**, regardless of:
+From there, TopicForge's discovery-based tools (`list_participants`, `list_endpoints`, `detect_qos_mismatches`, `participant_events`, and `peek_dds_samples` on the builtin `DCPS*` topics) see **every conformant participant on the bus**, regardless of:
 
 - **The vendor**: RTI Connext, OpenDDS, CoreDX, Fast DDS, Cyclone, InterCOM, Dust DDS, or any other DDS-RTPS conformant stack
 - **The host language**: C, C++11/14/17/20, Rust, Java, .NET, Python, Ada, anything with a binding
@@ -35,7 +35,7 @@ The two known interop gaps from the 2025-05 OMG report (Dust DDS <-> OpenDDS, Du
 
 ## Limits of this claim
 
-The claim is about **discovery**: which participants, readers and writers exist, and what QoS they announce. It does not extend to user-topic payloads: `peek_dds_samples` reports that a user topic is present on the bus but does not decode its contents, for any vendor. The project's own real-bus runs cover Cyclone and Dust DDS participants only (see [`../scripts/integration/README.md`](../scripts/integration/README.md)); RTI, OpenDDS, CoreDX, OpenSplice and Fast DDS have not been observed. For the rest the claim follows from the RTPS standard and from the OMG's published results above. Vendors that do not follow the RTPS vendor-id convention in the GUID prefix (Dust DDS, RTI by default) are reported with vendor `unknown` on Cyclone. Domains that use DDS Security are not observable at all, because TopicForge joins without credentials.
+The claim is about **discovery**: which participants, readers and writers exist, and what QoS they announce. It does not extend to user-topic payloads: `peek_dds_samples` on a user topic returns count 0 and a note, and does not decode contents, for any vendor; `list_endpoints` shows the topic's writers, readers and QoS. The project's own real-bus runs cover Cyclone and Dust DDS participants only (see [`../scripts/integration/README.md`](../scripts/integration/README.md)); RTI, OpenDDS, CoreDX, OpenSplice and Fast DDS have not been observed. For the rest the claim follows from the RTPS standard and from the OMG's published results above. Vendors that do not follow the RTPS vendor-id convention in the GUID prefix (Dust DDS, RTI by default) are reported with vendor `unknown` on Cyclone. Domains that use DDS Security are not observable at all, because TopicForge joins without credentials.
 
 ## What TopicForge is not
 

{topicforge-0.5.4 → topicforge-0.5.5}/docs/pro.md

@@ -22,7 +22,7 @@ Integration and adaptation to a specific ROS2 / DDS environment, native RTI Conn
 
 ## Known limitations
 
-DDS Security is not implemented on any adapter: if your domain requires authenticated or encrypted RTPS, TopicForge cannot join it today. `detect_qos_mismatches` covers Reliability, Durability, History and Deadline; Liveliness, Ownership and Partition are not checked.
+DDS Security is not implemented on any adapter: if your domain requires authenticated or encrypted RTPS, TopicForge cannot join it today. `detect_qos_mismatches` covers Partition, type name, Reliability, Durability, Deadline, Liveliness, LatencyBudget, Ownership (kind), DestinationOrder and DataRepresentation, with History as a risk; Presentation, XTypes assignability and runtime behavior are not checked.
 
 ## Contact
 

{topicforge-0.5.4 → topicforge-0.5.5}/docs/product-plan.md

@@ -8,7 +8,7 @@
 
 TopicForge is **the safety-first read-only MCP for ROS2 robotics**. Where general-purpose ROS-MCP servers let an LLM publish topics, call services, and command robots (useful for demos, untenable for production fleets, defense systems, or anything safety-certified), TopicForge is read-only by **architecture**, not by configuration. There is no write path to misconfigure, no permission system to audit, no liability conversation to have. The MCP client can see the robot stack; it cannot touch it.
 
-Concretely, the server exposes **eleven typed read-only tools today** (v0.5.3): the five ROS2-graph tools (`health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag`) plus the six DDS / observability tools shipped across v0.2.0-v0.4.0 (`list_participants`, `detect_qos_mismatches`, `peek_dds_samples`, `participant_events`, `topic_metrics`, `peek_bag_samples`). They are backed by a deterministic mock adapter (no ROS2/DDS required), a `ros2` CLI wrapper, or an OSS DDS participant (Eclipse CycloneDDS / eProsima Fast DDS). Outputs are frozen Pydantic schemas, stable across runtime modes. Telemetry is opt-in, six fields, zero user payload.
+Concretely, the server exposes **twelve typed read-only tools today** (v0.5.5): the five ROS2-graph tools (`health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag`) plus the seven DDS / observability tools shipped across v0.2.0-v0.5.5 (`list_participants`, `list_endpoints`, `detect_qos_mismatches`, `peek_dds_samples`, `participant_events`, `topic_metrics`, `peek_bag_samples`). They are backed by a deterministic mock adapter (no ROS2/DDS required), a `ros2` CLI wrapper, or an OSS DDS participant (Eclipse CycloneDDS / eProsima Fast DDS). Outputs are frozen Pydantic schemas, stable across runtime modes. Telemetry is opt-in, six fields, zero user payload.
 
 The ROS-MCP category is no longer empty (see section 11 Risk register for the competitive landscape as of 2026-05-13). What TopicForge defends, and the rest of the pack will inherit, is the read-only-by-architecture stance and the production-quality engineering envelope around it: frozen schemas, mock-first development, telemetry contract pinned by tests, Windows-first cross-platform, no shell injection, deterministic outputs.
 
@@ -46,7 +46,7 @@ The strategic bet is **pack breadth via two focused products plus a modular surf
 
 **Motif of the pivot.** Earlier drafts of this plan sequenced a 3-to-5-MCP pack with a separate DDS observability MCP as MCP 02. The 2026-05-14 audit collapsed that into a 2-product strategy: TopicForge as an umbrella covering both middlewares, DatasetForge as the second standalone product. The binding constraints were (a) solo-maintenance cost of running two repos in parallel and (b) the fact that ROS2 and DDS are the same problem shape (a typed pub/sub graph that needs structured introspection) and the `RosAdapter` protocol already generalizes to a `MiddlewareAdapter` superset with zero rework. Two products instead of three reduces the surface area without losing coverage.
 
-The umbrella commits TopicForge to a broader scope than first drafted: the DDS module shipped **six** DDS / observability tools across v0.2.0-v0.4.0 (not the three originally scoped), taking the surface to **11 tools total**. The original 8-tool ceiling was formally revised: see the re-scope decision in section 11. The pack inherits the layer separation, mock-first development, opt-in telemetry, and read-only-by-architecture commitments from TopicForge. Pack-shared infrastructure extraction (telemetry, license, settings resolver into a `pack-template/` repo) becomes a non-decision at 2 products: fork-and-tweak from TopicForge to DatasetForge is acceptable ; revisit only if a third product is ever planned.
+The umbrella commits TopicForge to a broader scope than first drafted: the DDS module shipped **six** DDS / observability tools across v0.2.0-v0.4.0 (not the three originally scoped), taking the surface to **11 tools total**, then **12** with `list_endpoints` (0.5.5, approved 2026-10-02 after a blind evaluation). The original 8-tool ceiling was formally revised: see the re-scope decision in section 11. The pack inherits the layer separation, mock-first development, opt-in telemetry, and read-only-by-architecture commitments from TopicForge. Pack-shared infrastructure extraction (telemetry, license, settings resolver into a `pack-template/` repo) becomes a non-decision at 2 products: fork-and-tweak from TopicForge to DatasetForge is acceptable ; revisit only if a third product is ever planned.
 
 ---
 
@@ -160,7 +160,7 @@ The risks worth tracking explicitly. Updated 2026-09-05 (previous pass: 2026-05-
 - **Cross-platform regressions on Windows -- CLOSED (2026-09-05).** Was: CI tested `ubuntu-latest` only, with Windows coverage manual-only before each release. Resolved in v0.5.0: `.github/workflows/ci.yml`'s matrix now runs `{ubuntu-latest, windows-latest} x {3.10, 3.11, 3.12, 3.13}` (3.10 added in 0.5.3, verified current). Residual, smaller risk: the Makefile still uses POSIX shell syntax, so users on plain PowerShell run the underlying commands listed in the README "Development" section.
 - **Telemetry trust.** Even opt-in telemetry can damage trust if the payload contract drifts. Mitigation: `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys` pins the six allowed keys. Any change requires a CHANGELOG entry and a README Telemetry section update in the same PR.
 - **Time / focus dilution.** A solo maintainer trying to drive two products (TopicForge umbrella + DatasetForge), commercial-support work for each, marketing, and the DDS module on top of TopicForge is the realistic risk. The 2026-05-14 pivot from a 3-to-5-MCP pack to a 2-product strategy reduced the surface but did not eliminate the risk. Mitigation: explicit phase gates (do not start Phase 2 until Phase 1 is shipped, do not act on the DDS module marketing until Phase 2 has shipped), though section 8 schedules `MiddlewareAdapter` protocol prep during Phase 1.
-- **Scope creep within the TopicForge umbrella.** Combining ROS2 + DDS introspection in one product risks bloating the tool surface beyond what a focused MCP should expose. **Re-scope decision (2026-07-08, ratified retroactively).** The register's original ceiling (5 ROS2 tools + at most 3 DDS tools, any 9th tool gated on a re-scope discussion documented *here* before code lands) was crossed during v0.4.0 **without that discussion being recorded in this register**, a governance gap surfaced by the 2026-07-08 external audit. The three tools that broke it are deliberate and were acknowledged in the CHANGELOG and `docs/projet-file/mcp-02-spec.md section 2` at ship time: `participant_events` (9th, v0.4.0 Phase 1), `topic_metrics` (10th, Phase 2), `peek_bag_samples` (11th, Phase 3). They are accepted; the revised ceiling is **11 tools**. A 12th tool now needs an explicit re-scope discussion documented in this register before code lands. Mitigation going forward: the `verify-change` skill's doc-drift step and the `docs-curator` sweep keep this register, `README.md`, and `CLAUDE.md` in sync so a ceiling break cannot ship undocumented again.
+- **Scope creep within the TopicForge umbrella.** Combining ROS2 + DDS introspection in one product risks bloating the tool surface beyond what a focused MCP should expose. **Re-scope decision (2026-07-08, ratified retroactively).** The register's original ceiling (5 ROS2 tools + at most 3 DDS tools, any 9th tool gated on a re-scope discussion documented *here* before code lands) was crossed during v0.4.0 **without that discussion being recorded in this register**, a governance gap surfaced by the 2026-07-08 external audit. The three tools that broke it are deliberate and were acknowledged in the CHANGELOG and `docs/projet-file/mcp-02-spec.md section 2` at ship time: `participant_events` (9th, v0.4.0 Phase 1), `topic_metrics` (10th, Phase 2), `peek_bag_samples` (11th, Phase 3). They are accepted; the revised ceiling was **11 tools** and moved to **12** on 2026-10-02 for `list_endpoints`. A 13th tool now needs an explicit re-scope discussion documented in this register before code lands. Mitigation going forward: the `verify-change` skill's doc-drift step and the `docs-curator` sweep keep this register, `README.md`, and `CLAUDE.md` in sync so a ceiling break cannot ship undocumented again.
 
 ---
 

{topicforge-0.5.4 → topicforge-0.5.5}/examples/README.md

@@ -17,6 +17,6 @@ TOPICFORGE_MODE=mock python -m topicforge
 # Windows PowerShell: $env:TOPICFORGE_MODE="mock"; python -m topicforge
 ```
 
-Point any MCP client at the server with `"env": { "TOPICFORGE_MODE": "mock" }`. The mock exposes all 11 tools against deterministic fixtures, so every example is reproducible byte for byte.
+Point any MCP client at the server with `"env": { "TOPICFORGE_MODE": "mock" }`. The mock exposes all 12 tools against deterministic fixtures, so every example is reproducible byte for byte.
 
 To run against a real bus, use `TOPICFORGE_MODE=live` and, for the DDS tools, `TOPICFORGE_DDS_BACKEND=cyclone` (see [`docs/DDS_QUICKSTART.md`](../docs/DDS_QUICKSTART.md)). The mock shows the shape of every response, not the behaviour of the live DDS adapters, which differ in two ways that examples 02 and 04 call out: user-topic payloads are not decoded, and `topic_metrics` only has data for the builtin discovery topics.

{topicforge-0.5.4 → topicforge-0.5.5}/examples/dds/02_why_cant_they_talk/README.md

@@ -27,7 +27,9 @@ python run.py --hold     # keep the programs running, ask your own MCP client
 ```
 [1] Which reader/writer pairs can never talk?
     -> detect_qos_mismatches
+    odom: matched (declared QoS): writer nav_planner -> reader lidar_driver
     scan: Reliability (incompatible): writer lidar_driver -> reader nav_planner
+        Reliability: reader asks RELIABLE, writer offers BEST_EFFORT
 
 [3] What does nav_planner actually receive on scan?
     -> nav_planner output
@@ -36,8 +38,8 @@ python run.py --hold     # keep the programs running, ask your own MCP client
 
 [4] What does lidar_driver actually receive on odom?
     -> lidar_driver output
-    [lidar_driver] rx odom: 10 in 1.0 s, last seq 39
-    [lidar_driver] rx odom: 10 in 1.0 s, last seq 49
+    [lidar_driver] rx odom: 10 in 1.0 s, last seq 50
+    [lidar_driver] rx odom: 10 in 1.0 s, last seq 60
 ```
 
 - On `scan`, the planner **requests** RELIABLE delivery and the driver only
@@ -45,7 +47,8 @@ python run.py --hold     # keep the programs running, ask your own MCP client
   offers, so DDS refuses the match.
 - On `odom` the QoS differ the other way: the writer offers RELIABLE and the
   reader asks for BEST_EFFORT. That is allowed (offering more than asked is
-  fine), so TopicForge does not report it.
+  fine), so TopicForge does not report it as a mismatch. It lists it under
+  `matched`, the pairs DDS will connect on the declared QoS.
 
 ## Ask your agent
 

{topicforge-0.5.4 → topicforge-0.5.5}/examples/dds/03_a_node_crashed/README.md

@@ -28,21 +28,22 @@ python run.py --hold     # keep the programs running, ask your own MCP client
 [2] The LIDAR driver crashes. How long until the bus notices?
     -> list_participants
   killed lidar_driver
-    lidar_driver reported as left after 14 s
+    lidar_driver reported as left after 10 s
 
 [3] What happened on the bus, in order?
     -> participant_events
     lost       lidar_driver
-    discovered lidar_driver
-    discovered nav_planner
     discovered topicforge
+    discovered nav_planner
+    discovered lidar_driver
 ```
 
-- Cyclone DDS uses a 10 s lease by default. TopicForge polls the bus, so it
-  reports the departure a few seconds after the lease expires.
-- TopicForge notices a departure when it is asked about the bus: it polls,
-  it does not keep a continuous history in the background. An agent watching
-  for crashes has to ask regularly.
+- Cyclone DDS uses a 10 s lease by default, so the departure is reported when
+  the lease expires.
+- TopicForge tracks discovery in the background, so the event is there when
+  you ask, and its time comes from DDS rather than from your question. The
+  `lost` time is an upper bound of the death: after a crash it is the lease
+  expiry, and a crash looks the same as a clean leave.
 - The lease is a per-vendor default you can configure. Dust DDS, for
   example, uses 100 s: a crashed Dust program stays "active" much longer.