topicforge 0.5.0__tar.gz → 0.5.2__tar.gz

{topicforge-0.5.0 → topicforge-0.5.2}/CHANGELOG.md

@@ -7,6 +7,198 @@ and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-08-22
+
+Documentation and metadata only. No code, no schema, and no dependency
+changes — `pip install topicforge` behaves identically to 0.5.1.
+
+### Added
+
+- **`server.json` — MCP Registry metadata.** Declares the server as
+  `io.github.yaniswav/topicforge` (the `io.github.<user>/` prefix is
+  required by the registry's GitHub-namespace authentication) and points
+  at the PyPI package, with the four user-facing environment variables
+  described so MCP clients can render configuration hints. Validated
+  against the registry's published JSON schema.
+- **PyPI ownership marker in `README.md`.** The registry verifies
+  ownership of a PyPI package by looking for an `mcp-name: <server name>`
+  string in the package description, which is generated from the README
+  at build time. The marker is an HTML comment, so it does not render.
+
+### Why this release exists
+
+The marker only reaches PyPI when a distribution is built and published.
+0.5.1 shipped before the marker was added, so its published description
+does not carry it and registry validation would reject the submission.
+Cutting this version is the mechanical prerequisite for listing
+TopicForge in the official MCP Registry — there is no functional change
+to install.
+
+## [0.5.1] - 2026-08-22
+
+### Fixed (hotfix — MCP SDK 2.0 incompatibility)
+
+- **Hard-pinned `mcp < 2` — TopicForge was uninstallable from 2026-07-28
+  to 2026-08-22.** The MCP Python SDK released `2.0.0` on 2026-07-28
+  alongside the `2026-07-28` protocol revision. That release removes the
+  `mcp.server.fastmcp` module entirely (`mcp/server/` now ships `auth`,
+  `lowlevel`, and `mcpserver`), so `server/app.py`'s
+  `from mcp.server.fastmcp import FastMCP` raises `ImportError` against
+  it. The dependency was declared as an unbounded `mcp>=1.0.0`, so every
+  fresh `pip install topicforge` resolved to `2.0.0` and produced a
+  server that could not start. Local development and CI both masked the
+  break — the dev environment had `mcp 1.27.1` already installed, and
+  the last CI run predates the SDK release. Pinning `<2` restores
+  installability on the 1.x line; migrating to the 2.x API
+  (`FastMCP` -> `MCPServer`, transport options moved from the
+  constructor to `.run()`, stateless protocol) is tracked separately and
+  is deliberately **not** bundled into this hotfix.
+
+### Note on scope
+
+- This release also publishes the external-audit work (Lots 0-5,
+  2026-07-08) that had accumulated under `[Unreleased]`. The Cyclone
+  `take_iter` -> `read_iter` change documented below is still **validated
+  by static analysis only** (`ruff` + `py_compile`); it has not been
+  exercised against a real multi-vendor DDS bus. It ships here because
+  leaving the package uninstallable was the larger harm — a broken
+  install affects every user, while this change can only affect users
+  running the Cyclone backend against a live bus. Real-bus validation
+  remains open.
+
+### Changed
+
+- **DDS pure logic extracted for testability (Lot 0, external audit
+  2026-07-08).** The QoS-profile normalizers (`_cyclone_qos_to_profile` /
+  `_fast_qos_to_profile`) and the discovery-sample field extractors
+  (`_extract_guid` / `_extract_vendor_id` / `_extract_hostname` /
+  `_extract_topic_name` / `_is_removal`) were moved out of
+  `adapters/dds_cyclone/adapter.py` and `adapters/dds_fast/adapter.py` —
+  which import their vendor binding at module top level and were therefore
+  never exercised by the test suite — into the binding-free
+  `adapters/common/qos_normalize.py` and `adapters/common/dds_introspection.py`.
+  The adapters import them back under their original private names, so every
+  call site is unchanged (verified by `ruff check` static analysis, since the
+  adapters are not importable without their SDKs). `fast_qos_to_profile`
+  takes the binding's int→str enum maps as parameters so it stays
+  import-free. This is the highest-value item from the audit: the QoS
+  normalization feeds `detect_qos_mismatches` (the flagship DDS diagnostic)
+  and was previously untestable and untested.
+
+### Added
+
+- `tests/test_dds_qos_normalization.py` and `tests/test_dds_introspection.py`
+  drive the extracted logic with synthetic duck-typed objects (no
+  `cyclonedds` / `fastdds` needed), including regression guards for the
+  "renamed policy key silently yields no QoS profile → no mismatch ever
+  reported" failure mode. The extracted modules are now ~91–92% covered.
+- `pytest-cov` and `rosbags` added to the `[dev]` extra, plus `[tool.coverage]`
+  config with a `fail_under = 85` floor (the two binding-only adapter shells
+  are `omit`ted as structurally unreachable without their SDKs). Adding
+  `rosbags` un-skips the real `.db3` bag-analysis I/O test.
+
+### Fixed
+
+- `tests/test_bag_service.py` bag-generation helper updated for the current
+  `rosbags` API (`Writer(..., version=Writer.VERSION_LATEST)`; typestore keyed
+  by `std_msgs/msg/String`, not `std_msgs__msg__String`). The test was
+  previously auto-skipped and had gone silently stale — un-skipping it in CI
+  surfaced the drift.
+- **`topic_metrics` frequency was wrong (Lot 2, audit C5).** It divided the
+  sample count by `(now − oldest_sample)` — folding in idle time since the
+  last peek — and counted N intervals instead of N−1. Now measured as
+  `(N−1) / (newest − oldest)` over the samples' own arrival span; samples
+  surfaced by a single opportunistic peek share one timestamp (span 0) and
+  correctly yield `frequency_hz_observed = null` instead of a fabricated rate.
+- **`topic_metrics` sequence-gap count exploded on multi-writer topics,
+  publisher restarts, and counter wrap (Lot 2, audit C6).** Gaps are now
+  counted per writer (new best-effort `MetricsSample.writer_guid`), so
+  independent writers' counter offsets are not read as phantom gaps, and a
+  single jump wider than 10 000 is treated as a reset/wrap discontinuity
+  rather than that many losses.
+- **QoS Deadline false negative (Lot 2, audit C3/P1-3).**
+  `detect_qos_mismatches` now flags a reader that requests a finite Deadline
+  against a writer that offers none — an absent deadline is the infinite
+  (loosest) period and cannot satisfy a finite request. The previous rule
+  required both sides non-null and silently missed this incompatibility.
+- **`LifecycleBuffer` participant map was unbounded (Lot 3, audit P1-4 / M1 /
+  P1).** Only the event ring was capped; the participant dict grew one entry
+  per GUID ever seen (a churny bus mints a fresh RTPS GUID on each node
+  restart), and `list_participants` returned every tombstone forever. Now
+  capped at `MAX_PARTICIPANTS = 4096`, evicting `"left"` tombstones first then
+  the oldest-inserted entry — the docstring's "Bounded" claim is now true.
+- **`MetricsBuffer` topic map was unbounded (Lot 3, audit P2-5).** Per-topic
+  rings were capped but the number of topic keys was not; now capped at
+  `MAX_TOPICS = 4096`, oldest-inserted topic evicted on overflow.
+- **OpenDDS stub `is_available()` always returns False (Lot 4, audit S1).** A
+  stub that advertised availability (when a `pyopendds` module happened to be
+  importable) could be auto-selected by the factory, after which every tool
+  call raised. Now consistent with the Dust stub.
+- **`iter_field_names` mis-decoded a string `__slots__` (Lot 4, audit C2).**
+  `__slots__ = "value"` was exploded into `['v','a','l','u','e']`; a bare
+  string slot is now treated as a single field name.
+- **`decode_field_value` recursion is depth-capped at 32 (Lot 4, audit M6).**
+  A pathologically deep decoded object graph collapses to `repr()` instead of
+  risking `RecursionError`.
+- **`_encode_raw_bytes` slices before hex-encoding (Lot 4, audit M5).** A large
+  raw payload no longer allocates its full 2×-size hex string only to truncate
+  it to the 4096-char preview.
+
+### Added (Lot 4 — test hardening)
+
+- End-to-end test that a failing tool call surfaces as an MCP error
+  (`ToolError`) rather than being masked as a success — pins the thin-handler
+  contract (CLAUDE.md §8, audit test-gap #4).
+- Test pinning that every canonical vendor tag is a valid
+  `ParticipantInfo`/`ParticipantEvent.vendor` Literal (guards against
+  vendor-map ↔ schema drift, audit P2-3). Scenario allowlist `_KNOWN_TOOLS`
+  now includes the 11th tool `peek_bag_samples`.
+
+### Removed (Lot 4)
+
+- Dead `annotate_full` / `annotate_partial` imports and the `_ = (...)`
+  unused-suppressor from `services/bag_service.py`.
+
+### Documentation (Lot 1 — reconcile the strategic source of truth)
+
+- **`docs/product-plan.md` realigned on the shipped 11-tool surface (audit
+  M6/P1-6).** §1 and §4 said "five typed tools today" / DDS "roadmapped"
+  while six DDS/observability tools had shipped across v0.2.0–v0.4.0. §11's
+  risk register carried a self-imposed governance gate — "any 9th tool needs
+  an explicit re-scope discussion documented in this register before code
+  lands" — that was crossed during v0.4.0 without the discussion being
+  recorded. Added a retroactive re-scope decision closing that gap: the three
+  ceiling-breaking tools are accepted, the new ceiling is 11 tools, a 12th
+  needs a documented re-scope.
+- **User-topic `raw` decode honesty (audit C1).** README and the
+  `peek_dds_samples` tool description no longer imply the `raw` fallback
+  preserves the payload in `_raw_bytes_hex` — on the current user-topic raw
+  path that field is empty (a `raw` status means "present but not decoded").
+  Capturing the on-wire CDR bytes is stated as roadmapped rather than done.
+
+### Changed (Lot 5 — DDS adapter deduplication)
+
+- **QoS-mismatch endpoint pairing deduplicated (audit D1/M7/P2).** The ~40
+  identical lines in each adapter's `detect_qos_mismatches` (group endpoints by
+  topic, pair reader × writer, build `MismatchReport`) moved to the binding-free
+  `common/qos_endpoints.detect_mismatches_across_endpoints`, unit-tested without
+  a binding. Each writer's QoS profile is now parsed once per topic instead of
+  once per reader (fixes the O(readers × writers) re-parse). Both adapters
+  delegate to it.
+- **Shared `validate_domain_id` (`common/dds_helpers`).** The identical 0..232
+  bound check in all four DDS adapter constructors (Cyclone, Fast, OpenDDS,
+  Dust) is now defined once.
+- **Cyclone discovery/sample reads switched from `take_iter` to `read_iter`
+  (audit A1/P1-5).** Destructive `take` drained the builtin discovery cache,
+  risking spurious lost / re-discovered participant flapping across polls;
+  `read` is non-destructive — the correct choice for read-only observability.
+  ⚠️ **Requires real-bus validation on `scripts/integration/` before release**:
+  the read-vs-take semantics cannot be exercised without `cyclonedds` installed
+  (the adapter is not importable in the unit environment; these edits are
+  validated only by `ruff` static analysis + `py_compile`).
+
+Baseline: 399 → 485 passed, 24 → 23 skipped, ruff clean, coverage 89.12%.
+
 ## [0.5.0] - 2026-05-21
 
 ### Sprint v0.5.0 — Polish + validation (pre-marketing-publication)
@@ -713,7 +905,9 @@ Initial MVP release of TopicForge — ROS Topic Inspector & Bag Analyzer MCP ser
 - 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.0...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/yaniswav/TopicForge/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/yaniswav/TopicForge/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/yaniswav/TopicForge/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/yaniswav/TopicForge/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/yaniswav/TopicForge/compare/v0.2.0...v0.3.0

{topicforge-0.5.0 → topicforge-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: topicforge
-Version: 0.5.0
+Version: 0.5.2
 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
@@ -39,7 +39,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.11
-Requires-Dist: mcp>=1.0.0
+Requires-Dist: mcp<2,>=1.0.0
 Requires-Dist: pydantic>=2.6
 Provides-Extra: all
 Requires-Dist: cyclonedds>=0.10; extra == 'all'
@@ -63,12 +63,16 @@ Requires-Dist: fastdds<3,>=2.6.1; extra == 'dds-fast'
 Provides-Extra: dds-opendds
 Requires-Dist: pyopendds>=0.1; extra == 'dds-opendds'
 Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rosbags>=0.9; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # TopicForge
 
+<!-- mcp-name: io.github.yaniswav/topicforge -->
+
 [![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
 [![CI](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml)
 [![Python versions](https://img.shields.io/pypi/pyversions/topicforge.svg)](https://pypi.org/project/topicforge/)
@@ -254,7 +258,7 @@ Six DDS / observability tools (in addition to the five ROS2 tools above) :
 
 **Composite adapter (v0.4.0 Phase 1+).** When `TOPICFORGE_MODE=live` is paired with a DDS backend (`cyclone`, `fast`, …), TopicForge instantiates **both** a ROS2 CLI adapter and the chosen DDS adapter and routes per-tool category — the 5 ROS2 tools hit the CLI, the DDS / observability tools hit the DDS backend. ROS2-only or DDS-only setups still work — the missing half is skipped and the present half serves what it can. The mock backend continues to expose all 11 tools against deterministic fixtures for local development.
 
-**`peek_dds_samples` payload shape (v0.4.0 Phase 1.5).** Full-fidelity on the 4 builtin DCPS topics (`DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`). Arbitrary user topics return best-effort decoded samples with a `_decode_status` annotation : `"full"` (every IDL field decoded — currently a v0.4.0+ Cyclone XTypes path), `"partial"` (some fields decoded, others opaque), or `"raw"` (binding could not resolve the dynamic XTypes — bytes preserved as hex in `_raw_bytes_hex`). The diagnostic key `_decode_note` carries a short explanation when the status is non-`full`. The wire shape is identical across Cyclone and Fast backends.
+**`peek_dds_samples` payload shape (v0.4.0 Phase 1.5).** Full-fidelity on the 4 builtin DCPS topics (`DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`). Arbitrary user topics return best-effort decoded samples with a `_decode_status` annotation : `"full"` (every IDL field decoded — currently a v0.4.0+ Cyclone XTypes path), `"partial"` (some fields decoded, others opaque), or `"raw"` (binding could not resolve the dynamic XTypes). The diagnostic key `_decode_note` carries a short explanation when the status is non-`full`. The wire shape is identical across Cyclone and Fast backends. **Caveat (v0.5.x):** on the current user-topic *raw* path `_raw_bytes_hex` is **empty** — a `"raw"` status means "topic present on the bus but not decoded", not "here are the serialized bytes to re-decode". Capturing the on-wire CDR bytes into the fallback is roadmapped ; until then use the Cyclone full/partial XTypes path for actual user-topic payloads. The 4 builtin DCPS topics are unaffected (always structured).
 
 **`RTI Connext`** is v0.4.0+ Pro tier (BYO license — see `docs/pro.md`).
 

{topicforge-0.5.0 → topicforge-0.5.2}/README.md

@@ -1,5 +1,7 @@
 # TopicForge
 
+<!-- mcp-name: io.github.yaniswav/topicforge -->
+
 [![PyPI version](https://img.shields.io/pypi/v/topicforge.svg)](https://pypi.org/project/topicforge/)
 [![CI](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yaniswav/TopicForge/actions/workflows/ci.yml)
 [![Python versions](https://img.shields.io/pypi/pyversions/topicforge.svg)](https://pypi.org/project/topicforge/)
@@ -185,7 +187,7 @@ Six DDS / observability tools (in addition to the five ROS2 tools above) :
 
 **Composite adapter (v0.4.0 Phase 1+).** When `TOPICFORGE_MODE=live` is paired with a DDS backend (`cyclone`, `fast`, …), TopicForge instantiates **both** a ROS2 CLI adapter and the chosen DDS adapter and routes per-tool category — the 5 ROS2 tools hit the CLI, the DDS / observability tools hit the DDS backend. ROS2-only or DDS-only setups still work — the missing half is skipped and the present half serves what it can. The mock backend continues to expose all 11 tools against deterministic fixtures for local development.
 
-**`peek_dds_samples` payload shape (v0.4.0 Phase 1.5).** Full-fidelity on the 4 builtin DCPS topics (`DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`). Arbitrary user topics return best-effort decoded samples with a `_decode_status` annotation : `"full"` (every IDL field decoded — currently a v0.4.0+ Cyclone XTypes path), `"partial"` (some fields decoded, others opaque), or `"raw"` (binding could not resolve the dynamic XTypes — bytes preserved as hex in `_raw_bytes_hex`). The diagnostic key `_decode_note` carries a short explanation when the status is non-`full`. The wire shape is identical across Cyclone and Fast backends.
+**`peek_dds_samples` payload shape (v0.4.0 Phase 1.5).** Full-fidelity on the 4 builtin DCPS topics (`DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`). Arbitrary user topics return best-effort decoded samples with a `_decode_status` annotation : `"full"` (every IDL field decoded — currently a v0.4.0+ Cyclone XTypes path), `"partial"` (some fields decoded, others opaque), or `"raw"` (binding could not resolve the dynamic XTypes). The diagnostic key `_decode_note` carries a short explanation when the status is non-`full`. The wire shape is identical across Cyclone and Fast backends. **Caveat (v0.5.x):** on the current user-topic *raw* path `_raw_bytes_hex` is **empty** — a `"raw"` status means "topic present on the bus but not decoded", not "here are the serialized bytes to re-decode". Capturing the on-wire CDR bytes into the fallback is roadmapped ; until then use the Cyclone full/partial XTypes path for actual user-topic payloads. The 4 builtin DCPS topics are unaffected (always structured).
 
 **`RTI Connext`** is v0.4.0+ Pro tier (BYO license — see `docs/pro.md`).
 

{topicforge-0.5.0 → topicforge-0.5.2}/docs/DDS_QUICKSTART.md

@@ -95,7 +95,7 @@ Both real backends and the mock fixtures encode the canonical "subscriber doesn'
 
 An LLM reading this output has enough information to suggest a concrete fix ("the writer is BEST_EFFORT but the reader requires RELIABLE — either relax the reader or upgrade the writer"). That is the diagnostic loop the DDS module is designed to support — and it works identically regardless of which backend produced the discovery samples, because the vendor-neutral pure analyzer at `src/topicforge/adapters/common/qos_analyzer.py` operates on canonical `QosProfile` Pydantic models.
 
-The analyzer covers the four MVP policies — **Reliability**, **Durability**, **History**, **Deadline** — that explain the bulk of real-world mismatch cases. Liveliness, Ownership, Partition, TimeBasedFilter, and LatencyBudget are v0.3.x patches.
+The analyzer covers the four MVP policies — **Reliability**, **Durability**, **History**, **Deadline** — that explain the bulk of real-world mismatch cases. Liveliness, Ownership, Partition, TimeBasedFilter, and LatencyBudget are v0.5.x patches.
 
 ---
 

topicforge-0.5.2/docs/TUTORIEL.md

@@ -0,0 +1,204 @@
+# TopicForge — Tutorial
+
+TopicForge is a read-only Model Context Protocol (MCP) server that gives an AI agent grounded, structured visibility into a ROS2 robotics stack and the raw DDS layer beneath it — topics, participants, QoS, recorded bags — without ever being able to publish, call a service, or command a robot.
+
+**Who this is for.** ROS2 developers, robotics ML/CV engineers, and anyone who wants their AI assistant to answer "what's actually happening on my robot's graph right now" instead of guessing from training data.
+
+**The read-only guarantee, in one sentence.** There is no write path anywhere in TopicForge's architecture — not a locked-down permission you could misconfigure, but code that was never written, so there is nothing to flip and nothing to exploit into a write.
+
+This tutorial covers installing TopicForge, using its eleven tools, and wiring it into a recurring monitoring workflow. For OS-by-OS environment setup (WSL2, native Linux, Docker, native Windows), see [`TESTING.md`](TESTING.md).
+
+---
+
+## Quickstart
+
+Requires Python 3.11+. This section needs no ROS2 install — the mock adapter serves deterministic fixtures for a small demo robot, so you can try every tool cold.
+
+```bash
+pip install topicforge
+```
+
+Add it to your MCP client. For Claude Desktop, edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "topicforge": {
+      "command": "topicforge",
+      "env": { "TOPICFORGE_MODE": "mock" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. All eleven tools appear under the hammer icon. Ask something like:
+
+> What topics are being published right now, and what message types do they carry?
+
+The agent calls `list_topics`. In mock mode you'll see the five fixture topics of the demo robot — `/cmd_vel`, `/odom`, `/scan`, `/tf`, `/camera/image_raw` — deterministic across runs, so you can build a mental model of the tool surface before pointing it at a real graph.
+
+When you're ready for a real ROS2 environment, switch `TOPICFORGE_MODE` to `live` or `auto` — see [Advanced options](#advanced-options) below, and [`TESTING.md`](TESTING.md) for full setup paths per OS.
+
+**Windows note.** File paths in this document are shown in POSIX style (`/tmp/demo.mcap`) because that's the form MCP clients pass internally, but TopicForge itself runs natively on Windows. Path resolution goes through `pathlib`, so both `C:\demos\run.mcap` and `C:/demos/run.mcap` work when you pass a bag path yourself.
+
+---
+
+## The eleven tools
+
+| Tool | What it does | When to use it |
+| --- | --- | --- |
+| `health_check` | Reports effective mode (`live`/`mock`), whether `ros2` is on PATH, the active DDS backend, and other environment state. Always succeeds. | Call first when something looks wrong — every other tool can raise an error, this one won't. |
+| `list_topics` | Lists every topic on the current ROS2 graph. | Discover what's currently being published before drilling into anything specific. |
+| `get_topic_info` | Structured detail for one topic — message type, publisher/subscriber counts, QoS reliability. | Check a topic's shape and who's connected to it before subscribing or debugging. |
+| `sample_messages` | Peeks recent messages on a ROS2 topic. | See real payload content without shelling out to `ros2 topic echo` yourself. |
+| `analyze_bag` | Summarizes a `.mcap` / `.db3` / `.bag` recording — duration, message count, per-topic stats. | Get a quick overview of a recorded run before deciding whether to dig deeper. |
+| `list_participants` | Lists DDS participants observed on a domain, at the raw DDS layer beneath ROS. | Diagnose why a participant isn't visible to the ROS graph, or inspect a non-ROS DDS stack. |
+| `detect_qos_mismatches` | Finds incompatible QoS pairs between DDS readers and writers. | A subscriber isn't receiving despite an apparently healthy publisher — this tells you why. |
+| `peek_dds_samples` | Peeks raw DDS samples, including the DCPS builtin discovery topics and (best-effort decoded) user topics. | Inspect non-ROS DDS topics, or the discovery layer itself. |
+| `participant_events` | Timeline of participant discovered/lost events over a lookback window. | Investigate churn — nodes restarting, dropping off, or new ones joining. |
+| `topic_metrics` | Observed frequency, latency percentiles, and sequence gaps for a topic over a time window. | Check whether a topic is actually meeting its declared publish rate or QoS Deadline. |
+| `peek_bag_samples` | Peeks recent samples from a recorded bag file (MCAP, `.db3`, or legacy ROS1 `.bag`). | Inspect payload content from a past recording without replaying the whole bag. |
+
+---
+
+## Advanced options
+
+### Environment variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `TOPICFORGE_MODE` | `auto` | Selects `mock`, `live`, or `auto` (see below). |
+| `TOPICFORGE_LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, or `ERROR`. |
+| `TOPICFORGE_ROS2_BIN` | `ros2` | Overrides the resolved `ros2` executable — useful when it isn't on PATH. |
+| `TOPICFORGE_TELEMETRY` | off | Opt-in anonymous telemetry. On-values: `on`, `1`, `true`, `yes`, `enabled`. See [Privacy](#privacy). |
+| `TOPICFORGE_DDS_BACKEND` | `mock` | Selects the DDS backend: `mock`, `cyclone`, `fast`, or `auto`. A few more identifiers exist in the settings schema (`rti`, `opensplice`, `coredx`, `intercom`, `opendds`, `dust`) — see [Choosing a DDS backend](#choosing-a-dds-backend). |
+| `TOPICFORGE_DDS_DOMAIN_ID` | `0` | DDS domain id to observe, `0`–`232`. |
+
+Add any of these to the same `env` object shown in the Quickstart config block.
+
+### The three modes
+
+- **`mock`** — deterministic fixtures, no ROS2 or DDS SDK required. Use for development, demos, CI, or evaluating the tool surface before touching a real graph.
+- **`live`** — talks to a real environment: the `ros2` CLI for the 5 ROS2 graph tools, and the configured DDS backend for the 6 DDS/observability tools. Use once ROS2 and/or a DDS backend are actually reachable from the shell that spawns TopicForge.
+- **`auto`** (default) — resolves to `live` if the `ros2` executable is found on PATH, otherwise falls back to `mock`. The DDS backend has its own `auto` resolution (see below), independent of `TOPICFORGE_MODE`.
+
+### DDS extras, per vendor
+
+Plain `pip install topicforge` gives you the 5 ROS2 tools plus mock fixtures for all eleven. To talk to a real DDS bus, install one of:
+
+```bash
+pip install topicforge[dds-cyclone]   # Eclipse CycloneDDS only
+pip install topicforge[dds-fast]      # eProsima Fast DDS only
+pip install topicforge[dds]           # both — the recommended default
+pip install topicforge[all]           # currently equivalent to [dds]
+pip install topicforge[bags]          # rosbags library — required for peek_bag_samples (no fallback);
+                                       # analyze_bag falls back to `ros2 bag info` text parsing without it
+```
+
+`topicforge[dds-opendds]` and `topicforge[dds-dust]` also exist in `pyproject.toml`, but as of this writing they pin `pyopendds` and `dust-dds-python` — packages not currently maintained on PyPI. Installing either extra fails at `pip install` time; they exist so the auto-detect framework has a known module name to probe once upstream ships a working release. Don't rely on them yet.
+
+### Choosing a DDS backend
+
+Set `TOPICFORGE_DDS_BACKEND` explicitly (`cyclone` or `fast`) if you have a preference and both are installed, or leave it on `auto` and let TopicForge pick. In practice, for the free tier `auto` resolves to Fast DDS if installed, otherwise CycloneDDS if installed, otherwise `mock`. The full priority chain also probes Pro-tier vendors (`rti`, `opensplice`, `coredx`, `intercom`) first, but only if you've separately installed the `topicforge-pro` add-on — without it, those probes are skipped automatically and fall through to the OSS vendors. Selecting `rti` explicitly without the Pro add-on falls back to the ROS2-CLI-only adapter with a logged warning rather than failing outright. `opendds` and `dust` are recognized identifiers with no working install path today (see the extras caveat above).
+
+### Domain id
+
+`TOPICFORGE_DDS_DOMAIN_ID` (default `0`, matching the default used by most ROS2 setups and by `cyclonedds` itself) sets the domain a live DDS adapter joins **at startup** — it does not change per call. `list_participants`, `participant_events`, and `topic_metrics` also accept a `domain_id` parameter, but on the real Cyclone/Fast adapters this parameter is accepted for protocol uniformity only; the adapter still reports what it sees on the domain it joined at construction time, not a different domain picked per call. To observe a different domain, restart the server with a different `TOPICFORGE_DDS_DOMAIN_ID`.
+
+---
+
+## Scheduled-task prompts
+
+TopicForge's tools are read-only, which makes them safe to run unattended on a schedule — a cron-triggered agent session, a scheduled task in whatever orchestrator you use, or a recurring reminder in your MCP client. The prompts below are generic: swap in your own topic names, domain ids, and bag paths. They're written as instructions to hand an agent, not as commands to run yourself.
+
+**Catches:** silent reader/writer QoS incompatibilities that block delivery — introduced by a new node, a config change, or a vendor default drifting from the rest of the bus.
+
+```
+Run detect_qos_mismatches across the whole bus (no topic filter). For every
+result with severity "incompatible", explain in plain language which QoS
+policy is blocking delivery, which side (reader or writer) is the outlier,
+and the smallest concrete change that would fix it (e.g. "relax the reader
+to BEST_EFFORT" or "raise the writer to TRANSIENT_LOCAL durability"). List
+any "risky" (non-blocking) mismatches separately as a lower-priority note.
+If nothing is found, say so in one line — do not pad the report.
+```
+
+**Catches:** environment drift before you trust the stack in the field — wrong mode silently active, `ros2` not actually on PATH, DDS backend quietly falling back to mock.
+
+```
+Before I start today's run, call health_check and confirm: the effective
+mode is "live" (not silently "mock"), the ros2 CLI is detected, and the
+active DDS backend matches what I expect. Then call list_topics and
+list_participants(domain_id=0), and tell me if the topic count or
+participant count looks abnormally low compared to a normal startup.
+Flag anything that looks like a partial or degraded environment before
+I rely on it.
+```
+
+**Catches:** flapping nodes (crash-restart loops), unexpected disconnects mid-run, or a new participant joining the bus that nobody deployed on purpose.
+
+```
+Call participant_events(domain_id=0, lookback_seconds=3600) and summarize
+the last hour of DDS participant activity. Group by guid: which
+participants were discovered then lost more than once (possible crash
+loop), which are new, and which have been stable the whole window. Call
+out anything under a hostname or vendor you don't recognize.
+```
+
+**Catches:** a critical topic silently dropping below its declared publish rate, latency creeping up, or sequence gaps appearing — degradation that doesn't throw an error but breaks downstream consumers.
+
+```
+For each of these topics: <topic-1>, <topic-2>, <topic-3> — first call
+peek_dds_samples(topic=<topic>, count=10) to warm up the metrics buffer,
+then call topic_metrics(topic=<topic>, window_seconds=60) and report
+frequency_hz_observed against frequency_hz_declared, the p50/p95/p99
+latency, and sequence_gaps_count. Flag any topic where the observed
+frequency is more than 20% below the declared rate, or where
+sequence_gaps_count is greater than zero.
+```
+
+**Catches:** recorded test or field runs that only get inspected reactively after something breaks, instead of on a regular cadence — letting anomalies (duration mismatches, missing topics, gaps) surface while they're still cheap to investigate.
+
+```
+Analyze the bag at <path-to-bag>. Report duration, total message count,
+and per-topic message counts. Then peek 5 samples from <topic-of-interest>
+in that bag and tell me if the payload shape looks consistent with a
+normal run. Flag anything anomalous: missing topics you'd expect to see,
+a duration much shorter or longer than usual, or a topic with a
+suspiciously low message count for its expected rate.
+```
+
+---
+
+## Privacy
+
+TopicForge is built so the question "what does this send off my machine?" has a short, verifiable answer.
+
+### Telemetry
+
+Telemetry is **off by default**. It's opt-in via `TOPICFORGE_TELEMETRY=on` (accepted on-values: `on`, `1`, `true`, `yes`, `enabled` — anything else, including an unset variable, stays off).
+
+When enabled, each tool call emits exactly six fields: `tool_name`, `latency_ms`, `mode`, `version`, `session_id`, `success`. `session_id` is a random id generated per server process — it isn't tied to your identity or any persistent identifier, and it's never written to disk.
+
+When disabled — the default — this isn't "we choose not to send it," it's "the code path doesn't exist." The instrumentation wrapper returns the tool handler unmodified: no event object is built, no transport is constructed, no network code executes. This no-op behavior is covered by a dedicated test in the codebase.
+
+### What never leaves your machine
+
+Regardless of the telemetry setting, TopicForge never transmits topic names, message payloads, bag file paths or contents, hostnames, or any other environment variable. The service and adapter layers that see this data have no code path into the telemetry module — by construction, not just by convention.
+
+### Bags are read locally
+
+`analyze_bag` and `peek_bag_samples` open bag files on the filesystem where TopicForge runs and parse them in-process — via `ros2 bag info` in live mode, or the `rosbags` library when installed (`pip install topicforge[bags]`). Nothing about a bag's content or path is uploaded anywhere.
+
+### Read-only, restated
+
+The same architectural property that keeps TopicForge from commanding your robot also bounds what it can leak: there is no write path anywhere in the codebase — not to the bus, not to a remote endpoint — other than the six-field telemetry event described above, and that event stays off unless you explicitly turn it on.
+
+---
+
+## Where to go next
+
+- [`DDS_QUICKSTART.md`](DDS_QUICKSTART.md) — a deeper tour of the DDS module: mock vs. live walkthroughs per backend, the QoS mismatch scenario end-to-end, and the composite-adapter routing table.
+- [`TESTING.md`](TESTING.md) — five paths to a working ROS2 environment (WSL2, native Linux, Docker, native Windows), plus MCP client wiring for Claude Desktop, Claude Code, and others.
+- [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) — the codebase's polished error messages, what they mean, and how to fix them.
+- [`dds-interop-matrix.md`](dds-interop-matrix.md) — why TopicForge sees participants from any OMG-DDS-RTPS-conformant vendor, not just the one it's bound to.

{topicforge-0.5.0 → topicforge-0.5.2}/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 five typed tools today — `health_check`, `list_topics`, `get_topic_info`, `sample_messages`, `analyze_bag` — backed by either a deterministic mock adapter (no ROS2 required) or a `ros2` CLI wrapper (full live introspection). Outputs are frozen Pydantic schemas, stable across runtime modes. Telemetry is opt-in, six fields, zero user payload.
+Concretely, the server exposes **eleven typed read-only tools today** (v0.5.0): 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.
 
 The ROS-MCP category is no longer empty (see §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.
 
@@ -40,13 +40,13 @@ Three concentric circles, ranked by strategic priority rather than acquisition c
 
 The strategic bet is **pack breadth via two focused products plus a modular surface inside TopicForge**. Two MCPs, not three to five — solo maintenance cost was the binding constraint and the 2026-05-14 audit collapsed the earlier 3-to-5-MCP plan accordingly.
 
-**MCP 01 — TopicForge umbrella.** Covers ROS2 introspection today (shipped v0.1.2) and DDS observability as the next module (roadmapped, see §8). The `RosAdapter` protocol generalizes into a `MiddlewareAdapter` protocol that supports CycloneDDS in the OSS core and RTI Connext under the existing `topicforge_pro` license-gated package. One install (`pip install topicforge`, optional extras for DDS), one CLI, one license key — the umbrella keeps the developer ergonomics tight while extending coverage to the DDS-native audience the ROS-MCP competitive set does not reach. Module spec at `docs/projet-file/mcp-02-spec.md`.
+**MCP 01 — TopicForge umbrella.** Covers ROS2 introspection (shipped v0.1.2) and DDS observability, which **shipped as a module across v0.2.0–v0.4.0** (see §8) — no longer roadmapped. The `RosAdapter` protocol was generalized into a `MiddlewareAdapter` protocol that supports Eclipse CycloneDDS and eProsima Fast DDS in the OSS core and RTI Connext under the existing `topicforge_pro` license-gated package. One install (`pip install topicforge`, optional extras for DDS), one CLI, one license key — the umbrella keeps the developer ergonomics tight while extending coverage to the DDS-native audience the ROS-MCP competitive set does not reach. Module spec at `docs/projet-file/mcp-02-spec.md`.
 
 **MCP 02 — DatasetForge.** Vision Dataset Inspector. Read images + annotations (COCO at MVP; YOLO / HF Datasets on roadmap) and answer structured questions about class balance, split coherence, annotation quality. Targets the ML/CV audience overlapping with TopicForge but distinct enough in domain (training data vs runtime graph) to warrant a separate product, separate repo, separate PyPI name. Full spec at `docs/projet-file/mcp-03-spec.md` (the file is still named `mcp-03-spec.md` for historical continuity ; the slot is MCP 02 of the 2-MCP pack).
 
 **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 slightly broader scope (cap: 5 ROS2 tools today + at most 3 DDS-side tools when the module ships, ceiling enforced by §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**. The original 8-tool ceiling was formally revised — see the re-scope decision in §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.
 
 ---
 
@@ -171,7 +171,7 @@ The risks worth tracking explicitly. Updated 2026-05-13 with the competitive lan
 - **Cross-platform regressions on Windows.** TopicForge's primary developer environment is Windows. The Makefile uses POSIX shell syntax; users on plain PowerShell need the documented escape hatches. Mitigation: tested directly in CI on `ubuntu-latest` only today; Windows coverage is documented in `docs/TESTING.md` and exercised manually before each release.
 - **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), a Pro tier inside 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 §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. Mitigation: tool surface stays capped at the 5 ROS2 tools today ; the DDS module adds at most 3 new tools (`list_participants`, `detect_qos_mismatches`, `peek_dds_samples`) when it ships. Any 9th tool needs an explicit re-scope discussion documented in this register before code lands.
+- **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 §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.
 
 ---
 

{topicforge-0.5.0 → topicforge-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "topicforge"
-version = "0.5.0"
+version = "0.5.2"
 description = "ROS Topic Inspector & Bag Analyzer MCP server for AI agents"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -22,14 +22,20 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "mcp>=1.0.0",
+    "mcp>=1.0.0,<2",
     "pydantic>=2.6",
 ]
 
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",
+    "pytest-cov>=5.0",
     "ruff>=0.4",
+    # rosbags (Apache-2.0, pure-Python) is a *dev* dependency so the
+    # bag-analysis I/O tests actually run in CI instead of self-skipping on
+    # `requires_rosbags`. It is NOT a runtime dependency — end users opt in
+    # via `topicforge[bags]`.
+    "rosbags>=0.9",
 ]
 # v0.3.0: split DDS extras per vendor. `[dds]` (the union) pulls both
 # OSS Python participants ; granular `[dds-cyclone]` / `[dds-fast]`
@@ -107,6 +113,33 @@ markers = [
     "requires_rosbags: tests needing the `rosbags` Python library; auto-skip without it (v0.4.0 Phase 3+)",
 ]
 
+[tool.coverage.run]
+branch = true
+source = ["topicforge"]
+omit = [
+    # The two real DDS adapters import their vendor binding (cyclonedds /
+    # fastdds) at module top level, so they are structurally unreachable
+    # without those SDKs installed. Their pure logic was extracted into
+    # adapters/common/{dds_introspection,qos_normalize,cdr_decoder}.py
+    # (Lot 0) which IS measured here; the thin binding shells are exercised
+    # only under the `-m integration` real-bus tier. Excluded so the
+    # coverage gate reflects testable code rather than being dragged down
+    # by lines no unit run can reach.
+    "*/adapters/dds_cyclone/adapter.py",
+    "*/adapters/dds_fast/adapter.py",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+# Threshold reflects the unit-testable surface (the two binding shells are
+# omitted above). Baseline at the Lot 0 achieved floor (87% total); the
+# extracted pure modules (qos_normalize, dds_introspection) are ~100%, while
+# factory.py / bag_service.py binding-present branches stay uncovered without
+# the SDKs installed. Ratchet upward as those get tests; do not lower without
+# a note in the changelog.
+fail_under = 85
+
 [tool.ruff]
 line-length = 100
 target-version = "py311"

{topicforge-0.5.0 → topicforge-0.5.2}/src/topicforge/__init__.py

@@ -1,5 +1,5 @@
 """TopicForge — ROS Topic Inspector & Bag Analyzer MCP server."""
 
-__version__ = "0.5.0"
+__version__ = "0.5.2"
 
 __all__ = ["__version__"]