topicforge 0.4.0__tar.gz → 0.5.0__tar.gz

{topicforge-0.4.0 → topicforge-0.5.0}/.gitignore

@@ -217,6 +217,12 @@ CLAUDE*.md
 # remain reproducible. Tracked, not part of sdist.
 !/docs/projet-file/references/
 !/docs/projet-file/references/**
+# Archive of superseded strategic artifacts (old audit reports, dated
+# launch-post drafts). Kept in git so the historical context survives
+# but tucked away so the active `projet-file/` folder stays focused on
+# what is currently load-bearing.
+!/docs/projet-file/archive/
+!/docs/projet-file/archive/**
 /docs/assets/screencast-raw/
 
 

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

@@ -5,7 +5,166 @@ All notable changes to TopicForge are documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.0]
+## [Unreleased]
+
+## [0.5.0] - 2026-05-21
+
+### Sprint v0.5.0 — Polish + validation (pre-marketing-publication)
+
+> Branch `feat/v0.5.0-polish-and-validation`. Three sub-milestones
+> (5.1 real validation, 5.2 audit closure + error polish, 5.3 docs +
+> examples + repo polish). No new MCP tool, no schema change. Last
+> sprint before marketing publication ; the next version bump is
+> the maintainer's manual `release` commit + tag.
+
+#### Changed (sub-milestone 5.1 — Real validation)
+
+- **CI matrix expanded** (`.github/workflows/ci.yml`) from
+  `ubuntu-latest × {3.11, 3.12}` to `{ubuntu-latest, windows-latest} ×
+  {3.11, 3.12, 3.13}` (6 cells, `fail-fast: false`). Windows-latest
+  coverage closes the largest unverified surface — TopicForge's primary
+  dev environment is Windows per `CLAUDE.md §7` and was previously only
+  hand-validated. Python 3.13 added now that wheels are stable across
+  the dependency footprint.
+- **`pyproject.toml` classifiers** widened with `Programming Language ::
+  Python :: 3.13`.
+
+#### Changed (sub-milestone 5.2 — AdapterError polish)
+
+- **`DDS_ONLY_ERROR_MSG`** (`adapters/common/dds_helpers.py`) rewritten
+  with the v0.4.0 `CompositeAdapter` remediation path explicit, and
+  with every affected ROS2 tool name listed inline. Substring
+  `"DDS observability only"`, `"TOPICFORGE_DDS_BACKEND"`,
+  `"TOPICFORGE_MODE"` preserved — existing `pytest.raises(match=...)`
+  contracts honored. New token assertions added :
+  `"CompositeAdapter"`, the 4 affected tool names.
+- **CycloneDDS adapter errors** (`adapters/dds_cyclone/adapter.py`)
+  enriched with the underlying exception type, the active domain id,
+  the topic name (where relevant), and common-cause diagnostic hints
+  (`CYCLONEDDS_URI` misconfiguration, multicast firewall, domain
+  mismatch). Three sites : participant discovery, endpoint discovery,
+  sample peek.
+- **Fast DDS participant-init error** (`adapters/dds_fast/adapter.py`)
+  enriched with an ABI-mismatch diagnostic — Fast DDS 2.6.x Python
+  binding wheels frequently desynchronize with system-installed Fast
+  DDS native libraries, and the v0.4.0 wording masked the cause behind
+  a bare `"returned None"`. New message points at the pyproject pin
+  (`fastdds>=2.6.1,<3`) and the `FastDDS_DEFAULT_PROFILES_FILE` env
+  var as the two likely culprits.
+- **`BagService` IO errors** (`services/bag_service.py`) wrap the
+  rosbags-side exception class name into the AdapterError message so
+  the LLM caller can pivot on `PermissionError` / `IsADirectoryError`
+  / etc. without inspecting `__cause__`.
+- **`_ROSBAGS_REQUIRED_MSG`** rewording — clarifies that `analyze_bag`
+  has a v0.3.0 text-parse fallback while `peek_bag_samples` does not.
+
+#### Closed (sub-milestone 5.2 — audit triage)
+
+- **`docs/projet-file/audit-followup-triage-v0.2.0.md` refreshed**
+  against the current tree (was last touched pre-v0.3.0). Strict
+  B-class : 3 items now CLOSED (B6 in v0.2.0, B9 in v0.3.0, B10 in
+  v0.5.0). 6 items remain DEFER (B1-B5 hosted-context security
+  hardening ; B7, B8 wire-contract decisions for v0.6+).
+- **`TODO(roadmap, audit-2026-05-14)` at `services/inspector.py:76`
+  retired as WONT-FIX-by-design** — the `list_topics` Inspector gate
+  is intentionally empty (no MCP-level args to validate). The comment
+  block is now a permanent design note rather than a roadmap pointer.
+
+#### Added (sub-milestone 5.2 — regression tests)
+
+- **5 new tests** in `tests/test_dds_helpers.py` and
+  `tests/test_bag_service.py` (regex-token assertions, not exact
+  wording) — pin the polished message contract without locking the
+  exact prose. Baseline grows from 394 to 399 passed ; 24 skipped
+  unchanged ; ruff clean.
+
+#### Changed (sub-milestone 5.3 — Documentation cascade)
+
+- **`README.md`** — CI badge added ; tagline refreshed from "v0.3.0"
+  to "v0.4.0" framing emphasising observability + bag analysis ; the
+  3-row DDS tool mini-table grew into a 6-row table listing every
+  DDS / observability tool with its sub-milestone of origin ;
+  `peek_dds_samples` scope rewritten around `_decode_status` (full /
+  partial / raw) ; telemetry contract field description switched from
+  "five MVP tools" to "eleven MCP tools" ; `TOPICFORGE_DDS_BACKEND`
+  Literal values listed in the config reference ; Roadmap section
+  pruned of items that shipped in v0.4.0 (Composite adapter, XTypes
+  Cyclone push).
+- **`docs/DDS_QUICKSTART.md`** — header bumped to v0.4.0+ ; §4
+  "Single-adapter limitation (v0.3.0)" replaced by "Composite adapter
+  (v0.4.0 Phase 1+)" with the new routing table ; §5 documents the
+  v0.4.0 Phase 1.5 best-effort XTypes story (no more
+  `AdapterError` on user topics) ; §6 "What's next" pruned of shipped
+  items ; §7 Troubleshooting updated.
+- **`docs/TESTING.md`** — "five MCP tools" → "eleven MCP tools" in the
+  three documented occurrences ("Pick your path" table row, the lead
+  paragraph, Path 1 header). New v0.4.0 tool-surface callout above
+  the path picker.
+
+#### Added (sub-milestone 5.3 — new docs and examples)
+
+- **`docs/MIGRATION_v0.3_to_v0.4.md`** (new, sibling to the existing
+  `MIGRATION_v0.2_to_v0.3.md`). 8 sections : new tools, env vars and
+  extras, soft-breaking schema widening (`ParticipantInfo` +4 fields,
+  `BagAnalysis` +4 fields, `HealthReport.ros_backend`, `dds_backend`
+  widening, `AdapterName` widening, new `TopicMetrics` /
+  `ParticipantEvent` schemas), `CompositeAdapter`, `peek_dds_samples`
+  user-topic story, protocol expansions, plus a quick checklist.
+- **`docs/TROUBLESHOOTING.md`** (new). One section per polished
+  AdapterError message, plus the cross-cutting "ROS2 CLI not found on
+  PATH" / `auto` fallback to mock case. Each section quotes the
+  message and lists the diagnostics in order.
+- **`examples/`** (new). 4 mock-mode-runnable walkthroughs covering
+  the headline value props :
+  - `01-discover-ros2-stack.md` — `health_check` + `list_topics` +
+    `get_topic_info` + `sample_messages`
+  - `02-debug-qos-mismatch.md` — `list_participants` +
+    `detect_qos_mismatches` + `peek_dds_samples` (canonical
+    Reliability mismatch story)
+  - `03-analyze-recording.md` — `analyze_bag` + `peek_bag_samples`
+    post-mortem inspection
+  - `04-monitor-topic-frequency.md` — `topic_metrics` +
+    `participant_events` with the opportunistic-fill caveat
+  Each example pairs an MCP-client prompt with the expected tool
+  calls and a short LLM-facing synthesis.
+
+#### Added (sub-milestone 5.3 — repo polish)
+
+- **`CONTRIBUTING.md`** (new). What contributions land easily vs hard,
+  development setup, the `make check` contract, mock-first
+  development convention, layer separation, pure-parser convention,
+  commit conventions.
+- **`SECURITY.md`** (new). Local-trust threat model, the
+  read-only-by-architecture stance, vulnerability disclosure email,
+  response SLAs, supported version policy.
+- **`.github/ISSUE_TEMPLATE/bug_report.yml`** (new) — structured form
+  with version, mode, OS, Python, repro, env vars, troubleshooting
+  check.
+- **`.github/ISSUE_TEMPLATE/feature_request.yml`** (new) —
+  problem-first framing, tier disambiguation (OSS / Pro), explicit
+  read-only-by-architecture acknowledgment.
+- **`.github/ISSUE_TEMPLATE/config.yml`** (new) — disables blank
+  issues, links to `SECURITY.md`, `docs/TROUBLESHOOTING.md`,
+  `docs/DDS_QUICKSTART.md`.
+- **`.github/PULL_REQUEST_TEMPLATE.md`** (new) — summary, test plan,
+  backward-compatibility checklist (covers the 11-tool cap, schema
+  additive-only invariant, telemetry 6-field contract, env var docs,
+  public API removal flag).
+
+#### Notes
+
+- **Backward compat preserved.** Zero schema changes, zero new tools,
+  zero env-var renames. The `DDS_ONLY_ERROR_MSG` substring tokens
+  pinned by existing tests (`"DDS observability only"`,
+  `"TOPICFORGE_DDS_BACKEND"`, `"TOPICFORGE_MODE"`) are preserved
+  intact ; v0.4.0 producers and clients keep working byte-for-byte.
+- **CHANGELOG entry deferred to release time.** This branch leaves
+  `pyproject.toml` at `0.4.0`, `__version__` at `"0.4.0"`, and the
+  `## [Unreleased]` heading populated with the polish notes above.
+  The version bump and `v0.5.0` tag are the maintainer's manual
+  steps after final review.
+
+## [0.4.0] - 2026-05-15
 
 ### Sprint v0.4.0 — Phase 3 (bag analysis multi-format)
 
@@ -554,7 +713,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.3.0...HEAD
+[Unreleased]: https://github.com/yaniswav/TopicForge/compare/v0.5.0...HEAD
+[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
 [0.2.0]: https://github.com/yaniswav/TopicForge/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/yaniswav/TopicForge/compare/v0.1.1...v0.1.2

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topicforge
-Version: 0.4.0
+Version: 0.5.0
 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
@@ -37,6 +37,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 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: pydantic>=2.6
@@ -69,11 +70,12 @@ Description-Content-Type: text/markdown
 # 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/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yaniswav/TopicForge/blob/main/LICENSE)
 [![Read-only by architecture](https://img.shields.io/badge/safety-read--only_by_architecture-2563eb)](https://github.com/yaniswav/TopicForge#security-model)
 
-> **The safety-first read-only MCP for ROS2 robotics — now with multi-vendor OMG DDS-RTPS observability (v0.3.0).** TopicForge lets AI agents inspect your ROS2 graph, ROS bag files, and (since v0.2.0) the raw DDS layer beneath ROS, without ever publishing back to the bus. v0.3.0 ships two OSS Python adapters — Eclipse CycloneDDS and eProsima Fast DDS — each joining the bus as a read-only DDS-RTPS participant that observes **every conformant vendor on the wire** (RTI Connext, OpenDDS, CoreDX, Dust DDS in Rust, etc.) via the OMG protocol guarantee. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md) for the canonical multi-vendor positioning and the OMG May 2025 interop reference.
+> **The safety-first read-only MCP for ROS2 robotics — observability + multi-vendor OMG DDS-RTPS (v0.4.0).** TopicForge lets AI agents inspect your ROS2 graph, recorded bag files, and the raw DDS layer beneath ROS — without ever publishing back to the bus. **Eleven typed read-only tools** (5 ROS2 graph + 3 DDS + 3 observability/bag) share a single Pydantic envelope so an LLM caller reads one schema across the whole stack. v0.4.0 adds participant lifecycle tracking (`participant_events`), temporal metrics (`topic_metrics`), and post-mortem bag sample peek (`peek_bag_samples`) on top of v0.3.0's two OSS Python DDS participants — Eclipse CycloneDDS and eProsima Fast DDS — each observing **every conformant vendor on the wire** (RTI Connext, OpenDDS, CoreDX, Dust DDS in Rust, etc.) via the OMG protocol guarantee. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md) for the canonical multi-vendor positioning and the OMG May 2025 interop reference.
 
 TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics, analyze ROS bag files, and (since v0.2.0) observe the raw DDS layer through a clean, structured tool interface. It 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.
 
@@ -239,21 +241,24 @@ CoreDX, InterCOM) ship under the optional `topicforge-pro` package with
 BYO vendor license. See [`docs/pro.md`](docs/pro.md) for the early-access
 slot and pricing terms ; nothing is collected today.
 
-Three new MCP tools (in addition to the five ROS2 tools above) :
+Six DDS / observability tools (in addition to the five ROS2 tools above) :
 
-| Tool                    | Purpose                                                                          |
-| ----------------------- | -------------------------------------------------------------------------------- |
-| `list_participants`     | DDS participants discovered on a domain, with vendor and hostname                |
-| `detect_qos_mismatches` | Reader/writer QoS incompatibilities preventing communication on a topic          |
-| `peek_dds_samples`      | Recent samples on a raw DDS topic (distinct from `sample_messages` on ROS2 graph)|
+| Tool                    | Since   | Purpose                                                                                                        |
+| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `list_participants`     | v0.2.0  | DDS participants discovered on a domain, with vendor, hostname, and (v0.4.0) lifecycle fields                  |
+| `detect_qos_mismatches` | v0.2.0  | Reader/writer QoS incompatibilities preventing communication on a topic                                        |
+| `peek_dds_samples`      | v0.2.0  | Recent samples on a raw DDS topic — v0.4.0 adds best-effort XTypes user-topic decode (distinct from `sample_messages` on ROS2 graph) |
+| `participant_events`    | v0.4.0  | Lifecycle stream — `discovered` / `lost` participant events over a configurable window                         |
+| `topic_metrics`         | v0.4.0  | Temporal metrics — observed frequency, sequence gaps, latency p50/p95/p99 over a sliding window                |
+| `peek_bag_samples`      | v0.4.0  | Post-mortem inspection — decoded samples from a recorded `.mcap` / `.db3` / `.bag` file                        |
 
-**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 3 DDS tools (+ `participant_events` from Phase 1) 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 9 tools against deterministic fixtures for local development.
+**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.
 
-**v0.3.0 limitation — `peek_dds_samples` scope.** Full-fidelity on the 4 builtin DCPS topics (`DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`) ; arbitrary user topics raise an `AdapterError` pointing at the v0.3.x XTypes/IDL roadmap. The other two DDS tools (`list_participants`, `detect_qos_mismatches`) work end-to-end on any user-topic deployment.
+**`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.
 
 **`RTI Connext`** is v0.4.0+ Pro tier (BYO license — see `docs/pro.md`).
 
-**Full 5-minute walkthrough** — backend selection, the canonical QoS-mismatch debugging scenario, troubleshooting — lives in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md). Migration from v0.2.0 in [`docs/MIGRATION_v0.2_to_v0.3.md`](docs/MIGRATION_v0.2_to_v0.3.md).
+**Full 5-minute walkthrough** — backend selection, the canonical QoS-mismatch debugging scenario, troubleshooting — lives in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md). Migration history : [v0.2 → v0.3](docs/MIGRATION_v0.2_to_v0.3.md), [v0.3 → v0.4](docs/MIGRATION_v0.3_to_v0.4.md).
 
 ### Configure with Claude Desktop
 
@@ -308,7 +313,7 @@ make check    # both, plus tests (CI bundle)
 | `TOPICFORGE_LOG_LEVEL`      | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                           |
 | `TOPICFORGE_ROS2_BIN`       | `ros2`  | Name (or path) of the ROS2 CLI binary                                         |
 | `TOPICFORGE_TELEMETRY`      | `off`   | Opt-in anonymous usage telemetry. See [Telemetry](#telemetry).                |
-| `TOPICFORGE_DDS_BACKEND`    | `mock`  | DDS module backend: `mock`, `cyclone`, `fast`, `rti`, or `auto`. `auto` resolves to Fast > Cyclone > Mock. See [Multi-vendor DDS support](#multi-vendor-dds-support-v030). |
+| `TOPICFORGE_DDS_BACKEND`    | `mock`  | DDS module backend: `mock`, `cyclone`, `fast`, `rti`, `opensplice`, `coredx`, `intercom`, `opendds`, `dust`, or `auto`. The v0.4.0 Phase 1.5 auto-detect chain resolves to: `rti > opensplice > coredx > intercom` (Pro tier, if installed) `> opendds > fast > cyclone > dust > mock`. See [Multi-vendor DDS support](#multi-vendor-dds-support-v030). |
 | `TOPICFORGE_DDS_DOMAIN_ID`  | `0`     | DDS domain id observed (0..232) when a DDS backend is active.                 |
 
 See [`.env.example`](.env.example).
@@ -336,7 +341,7 @@ When telemetry is on, each MCP tool call emits a single event with **only** thes
 
 | Field             | Example          | Notes                                                                  |
 | ----------------- | ---------------- | ---------------------------------------------------------------------- |
-| `tool_name`       | `"list_topics"`  | One of the five MVP tools — never argument values.                     |
+| `tool_name`       | `"list_topics"`  | One of the eleven MCP tools — never argument values.                   |
 | `latency_ms`      | `12.34`          | Wall-clock duration of the handler, rounded to 2 decimals.             |
 | `mode`            | `"mock"`         | Effective runtime mode: `mock` or `live`.                              |
 | `version`         | `"0.1.2"`        | TopicForge server version.                                             |
@@ -382,16 +387,14 @@ See [`docs/product-plan.md`](docs/product-plan.md) for the full product trajecto
 
 Near-term additions on the bench:
 
-- `rclpy`-backed live adapter for faster & richer sampling
-- XTypes/IDL discovery to extend `peek_dds_samples` to arbitrary user topics (today: 4 builtin DCPS topics only) — v0.3.x patch
-- Extended QoS coverage (Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget) — v0.3.x patch
-- Composite adapter delegating per-tool category, so ROS2 + DDS surfaces work simultaneously — v0.3.x patch
-- `RtiConnextAdapter` in the Pro tier (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`) — v0.4.0+
-- URDF inspector / validator MCP tools
-- Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health)
+- `rclpy`-backed live adapter for faster & richer sampling (per-message rmw receive timestamps, windowed sampling) — gated on external user demand
+- Extended QoS coverage (Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget) — v0.5.x patch
+- Real `RtiConnextAdapter` in the Pro tier (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`) — the v0.4.0 Phase 1.5 framework is in place ; production binding pending Pro tier launch
+- URDF inspector / validator MCP tools (Pro tier)
+- Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health) — Pro tier
 - Dataset export helpers (rosbag → COCO / HF Datasets)
 - Synthetic data pipeline controller (Blender, Gazebo, Isaac Sim)
-- Hosted MCP endpoint with auth
+- Hosted MCP endpoint with auth (Phase 3 — depends on Pro tier traction)
 
 ## Project layout
 

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

@@ -1,11 +1,12 @@
 # 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/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/yaniswav/TopicForge/blob/main/LICENSE)
 [![Read-only by architecture](https://img.shields.io/badge/safety-read--only_by_architecture-2563eb)](https://github.com/yaniswav/TopicForge#security-model)
 
-> **The safety-first read-only MCP for ROS2 robotics — now with multi-vendor OMG DDS-RTPS observability (v0.3.0).** TopicForge lets AI agents inspect your ROS2 graph, ROS bag files, and (since v0.2.0) the raw DDS layer beneath ROS, without ever publishing back to the bus. v0.3.0 ships two OSS Python adapters — Eclipse CycloneDDS and eProsima Fast DDS — each joining the bus as a read-only DDS-RTPS participant that observes **every conformant vendor on the wire** (RTI Connext, OpenDDS, CoreDX, Dust DDS in Rust, etc.) via the OMG protocol guarantee. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md) for the canonical multi-vendor positioning and the OMG May 2025 interop reference.
+> **The safety-first read-only MCP for ROS2 robotics — observability + multi-vendor OMG DDS-RTPS (v0.4.0).** TopicForge lets AI agents inspect your ROS2 graph, recorded bag files, and the raw DDS layer beneath ROS — without ever publishing back to the bus. **Eleven typed read-only tools** (5 ROS2 graph + 3 DDS + 3 observability/bag) share a single Pydantic envelope so an LLM caller reads one schema across the whole stack. v0.4.0 adds participant lifecycle tracking (`participant_events`), temporal metrics (`topic_metrics`), and post-mortem bag sample peek (`peek_bag_samples`) on top of v0.3.0's two OSS Python DDS participants — Eclipse CycloneDDS and eProsima Fast DDS — each observing **every conformant vendor on the wire** (RTI Connext, OpenDDS, CoreDX, Dust DDS in Rust, etc.) via the OMG protocol guarantee. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md) for the canonical multi-vendor positioning and the OMG May 2025 interop reference.
 
 TopicForge is a production-minded MCP (Model Context Protocol) server that lets AI agents — such as Claude — inspect ROS2 topics, analyze ROS bag files, and (since v0.2.0) observe the raw DDS layer through a clean, structured tool interface. It 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.
 
@@ -171,21 +172,24 @@ CoreDX, InterCOM) ship under the optional `topicforge-pro` package with
 BYO vendor license. See [`docs/pro.md`](docs/pro.md) for the early-access
 slot and pricing terms ; nothing is collected today.
 
-Three new MCP tools (in addition to the five ROS2 tools above) :
+Six DDS / observability tools (in addition to the five ROS2 tools above) :
 
-| Tool                    | Purpose                                                                          |
-| ----------------------- | -------------------------------------------------------------------------------- |
-| `list_participants`     | DDS participants discovered on a domain, with vendor and hostname                |
-| `detect_qos_mismatches` | Reader/writer QoS incompatibilities preventing communication on a topic          |
-| `peek_dds_samples`      | Recent samples on a raw DDS topic (distinct from `sample_messages` on ROS2 graph)|
+| Tool                    | Since   | Purpose                                                                                                        |
+| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `list_participants`     | v0.2.0  | DDS participants discovered on a domain, with vendor, hostname, and (v0.4.0) lifecycle fields                  |
+| `detect_qos_mismatches` | v0.2.0  | Reader/writer QoS incompatibilities preventing communication on a topic                                        |
+| `peek_dds_samples`      | v0.2.0  | Recent samples on a raw DDS topic — v0.4.0 adds best-effort XTypes user-topic decode (distinct from `sample_messages` on ROS2 graph) |
+| `participant_events`    | v0.4.0  | Lifecycle stream — `discovered` / `lost` participant events over a configurable window                         |
+| `topic_metrics`         | v0.4.0  | Temporal metrics — observed frequency, sequence gaps, latency p50/p95/p99 over a sliding window                |
+| `peek_bag_samples`      | v0.4.0  | Post-mortem inspection — decoded samples from a recorded `.mcap` / `.db3` / `.bag` file                        |
 
-**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 3 DDS tools (+ `participant_events` from Phase 1) 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 9 tools against deterministic fixtures for local development.
+**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.
 
-**v0.3.0 limitation — `peek_dds_samples` scope.** Full-fidelity on the 4 builtin DCPS topics (`DCPSParticipant`, `DCPSSubscription`, `DCPSPublication`) ; arbitrary user topics raise an `AdapterError` pointing at the v0.3.x XTypes/IDL roadmap. The other two DDS tools (`list_participants`, `detect_qos_mismatches`) work end-to-end on any user-topic deployment.
+**`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.
 
 **`RTI Connext`** is v0.4.0+ Pro tier (BYO license — see `docs/pro.md`).
 
-**Full 5-minute walkthrough** — backend selection, the canonical QoS-mismatch debugging scenario, troubleshooting — lives in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md). Migration from v0.2.0 in [`docs/MIGRATION_v0.2_to_v0.3.md`](docs/MIGRATION_v0.2_to_v0.3.md).
+**Full 5-minute walkthrough** — backend selection, the canonical QoS-mismatch debugging scenario, troubleshooting — lives in [`docs/DDS_QUICKSTART.md`](docs/DDS_QUICKSTART.md). Migration history : [v0.2 → v0.3](docs/MIGRATION_v0.2_to_v0.3.md), [v0.3 → v0.4](docs/MIGRATION_v0.3_to_v0.4.md).
 
 ### Configure with Claude Desktop
 
@@ -240,7 +244,7 @@ make check    # both, plus tests (CI bundle)
 | `TOPICFORGE_LOG_LEVEL`      | `INFO`  | `DEBUG`, `INFO`, `WARNING`, `ERROR`                                           |
 | `TOPICFORGE_ROS2_BIN`       | `ros2`  | Name (or path) of the ROS2 CLI binary                                         |
 | `TOPICFORGE_TELEMETRY`      | `off`   | Opt-in anonymous usage telemetry. See [Telemetry](#telemetry).                |
-| `TOPICFORGE_DDS_BACKEND`    | `mock`  | DDS module backend: `mock`, `cyclone`, `fast`, `rti`, or `auto`. `auto` resolves to Fast > Cyclone > Mock. See [Multi-vendor DDS support](#multi-vendor-dds-support-v030). |
+| `TOPICFORGE_DDS_BACKEND`    | `mock`  | DDS module backend: `mock`, `cyclone`, `fast`, `rti`, `opensplice`, `coredx`, `intercom`, `opendds`, `dust`, or `auto`. The v0.4.0 Phase 1.5 auto-detect chain resolves to: `rti > opensplice > coredx > intercom` (Pro tier, if installed) `> opendds > fast > cyclone > dust > mock`. See [Multi-vendor DDS support](#multi-vendor-dds-support-v030). |
 | `TOPICFORGE_DDS_DOMAIN_ID`  | `0`     | DDS domain id observed (0..232) when a DDS backend is active.                 |
 
 See [`.env.example`](.env.example).
@@ -268,7 +272,7 @@ When telemetry is on, each MCP tool call emits a single event with **only** thes
 
 | Field             | Example          | Notes                                                                  |
 | ----------------- | ---------------- | ---------------------------------------------------------------------- |
-| `tool_name`       | `"list_topics"`  | One of the five MVP tools — never argument values.                     |
+| `tool_name`       | `"list_topics"`  | One of the eleven MCP tools — never argument values.                   |
 | `latency_ms`      | `12.34`          | Wall-clock duration of the handler, rounded to 2 decimals.             |
 | `mode`            | `"mock"`         | Effective runtime mode: `mock` or `live`.                              |
 | `version`         | `"0.1.2"`        | TopicForge server version.                                             |
@@ -314,16 +318,14 @@ See [`docs/product-plan.md`](docs/product-plan.md) for the full product trajecto
 
 Near-term additions on the bench:
 
-- `rclpy`-backed live adapter for faster & richer sampling
-- XTypes/IDL discovery to extend `peek_dds_samples` to arbitrary user topics (today: 4 builtin DCPS topics only) — v0.3.x patch
-- Extended QoS coverage (Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget) — v0.3.x patch
-- Composite adapter delegating per-tool category, so ROS2 + DDS surfaces work simultaneously — v0.3.x patch
-- `RtiConnextAdapter` in the Pro tier (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`) — v0.4.0+
-- URDF inspector / validator MCP tools
-- Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health)
+- `rclpy`-backed live adapter for faster & richer sampling (per-message rmw receive timestamps, windowed sampling) — gated on external user demand
+- Extended QoS coverage (Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget) — v0.5.x patch
+- Real `RtiConnextAdapter` in the Pro tier (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`) — the v0.4.0 Phase 1.5 framework is in place ; production binding pending Pro tier launch
+- URDF inspector / validator MCP tools (Pro tier)
+- Bag anomaly detection (clock jumps, gaps, dropped frames, TF tree health) — Pro tier
 - Dataset export helpers (rosbag → COCO / HF Datasets)
 - Synthetic data pipeline controller (Blender, Gazebo, Isaac Sim)
-- Hosted MCP endpoint with auth
+- Hosted MCP endpoint with auth (Phase 3 — depends on Pro tier traction)
 
 ## Project layout
 

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

@@ -1,4 +1,4 @@
-# DDS quickstart — TopicForge v0.3.0+
+# DDS quickstart — TopicForge v0.4.0+
 
 A 5-minute tour of TopicForge's multi-vendor DDS observability module. Both backends — Eclipse CycloneDDS and eProsima Fast DDS — join the bus as **read-only DDS-RTPS participants** and observe every conformant vendor on the wire via the OMG protocol guarantee. The `MiddlewareAdapter` protocol does not expose a write method, so the MCP client cannot publish back to the bus on any backend.
 
@@ -99,25 +99,25 @@ The analyzer covers the four MVP policies — **Reliability**, **Durability**, *
 
 ---
 
-## 4. Single-adapter limitation (v0.3.0)
+## 4. Composite adapter (v0.4.0 Phase 1+)
 
-TopicForge v0.3.0 still selects **one adapter at a time** based on `TOPICFORGE_MODE` + `TOPICFORGE_DDS_BACKEND` :
+v0.4.0 Phase 1 lifted the v0.3.0 single-adapter limitation. When `TOPICFORGE_MODE=live` is paired with a DDS backend, TopicForge instantiates **both** a `Ros2CliAdapter` and the chosen DDS adapter behind a `CompositeAdapter` and routes per-tool category — the 5 ROS2 graph tools hit the CLI, the 6 DDS / observability tools (`list_participants`, `detect_qos_mismatches`, `peek_dds_samples`, `participant_events`, `topic_metrics`, `peek_bag_samples`) hit the DDS half. The `name` collapses to `"ros2_cli+cyclone"` or `"ros2_cli+fast"` ; `effective_mode` reports `"live"` whenever either half is live.
 
-| `TOPICFORGE_MODE` | `TOPICFORGE_DDS_BACKEND` | Active adapter             | ROS2 tools                | DDS tools                  |
-| ----------------- | ------------------------ | -------------------------- | ------------------------- | -------------------------- |
-| `mock`            | (any)                    | `MockAdapter`              | work (fixtures)           | work (fixtures)            |
-| `live` / `auto`   | `mock` (default)         | `Ros2CliAdapter`           | work                      | raise with remediation     |
-| `live` / `auto`   | `cyclone`                | `CycloneDdsAdapter`        | raise (DDS-only adapter)  | work (real CycloneDDS)     |
-| `live` / `auto`   | `fast`                   | `FastDdsAdapter`           | raise (DDS-only adapter)  | work (real Fast DDS)       |
-| `live` / `auto`   | `rti`                    | falls back to ROS2 CLI     | work (CLI)                | raise (v0.4.0+ Pro tier)   |
+| `TOPICFORGE_MODE` | `TOPICFORGE_DDS_BACKEND` | Active adapter                | ROS2 tools                       | DDS / observability tools           |
+| ----------------- | ------------------------ | ----------------------------- | -------------------------------- | ----------------------------------- |
+| `mock`            | (any)                    | `MockAdapter`                 | work (fixtures)                  | work (fixtures)                     |
+| `live` / `auto`   | `mock` (default)         | `Ros2CliAdapter`              | work                             | raise with remediation              |
+| `live` / `auto`   | `cyclone`                | `CompositeAdapter(ros2_cli + cyclone)` | work (CLI)              | work (real CycloneDDS)              |
+| `live` / `auto`   | `fast`                   | `CompositeAdapter(ros2_cli + fast)` | work (CLI)                 | work (real Fast DDS)                |
+| `live` / `auto`   | `rti`                    | falls back to `Ros2CliAdapter` | work (CLI)                      | raise (v0.4.0+ Pro tier — BYO license) |
 
-A composite adapter that delegates per-tool category (ROS2 graph vs DDS layer) is on the v0.3.x roadmap. For now, restart the server with a different `TOPICFORGE_DDS_BACKEND` to switch sides.
+**Graceful degradation paths preserved.** DDS binding missing → ROS2-CLI-only (the v0.3.0 behavior). ROS2 CLI missing on PATH → DDS-only adapter with a clear `DDS_ONLY_ERROR_MSG` on the 5 ROS2 methods. Neither available → MockAdapter (auto mode only).
 
-Error messages on the unselected side are explicit and point at the remediation path — no silent failures.
+`HealthReport` reports both halves via the `ros_backend` and `dds_backend` fields, so a downstream client can introspect which half of a composite is live without guessing.
 
 ---
 
-## 5. v0.3.0 scope of `peek_dds_samples`
+## 5. v0.4.0 scope of `peek_dds_samples`
 
 `peek_dds_samples` is full-fidelity on the 4 builtin DCPS topics with both backends :
 
@@ -127,18 +127,26 @@ peek_dds_samples(topic="DCPSSubscription", count=10)
 peek_dds_samples(topic="DCPSPublication", count=10)
 ```
 
-Arbitrary user topics raise an `AdapterError` pointing at the v0.3.x roadmap — XTypes/IDL discovery (`cyclonedds.dynamic.get_types_for_typeid` on Cyclone, XTypes remote-type lookup on Fast DDS) is the missing piece for arbitrary user-topic peek.
+**Arbitrary user topics (v0.4.0 Phase 1.5+).** The v0.3.0 `AdapterError` is retired. The tool now returns best-effort decoded samples annotated with a `_decode_status` field :
 
-The other two DDS tools — `list_participants` and `detect_qos_mismatches` — work end-to-end on any user-topic deployment ; they don't depend on payload deserialization.
+- `"full"` — every IDL field decoded (currently the Cyclone XTypes path, structurally in place ; real-bus validation pending user feedback)
+- `"partial"` — some fields decoded, others opaque (mixed-success path)
+- `"raw"` — the binding could not resolve the dynamic XTypes ; the serialized payload is preserved as hex in `_raw_bytes_hex` (capped at 4096 hex chars ; `_raw_bytes_truncated=True` flags clipping)
+
+The diagnostic key `_decode_note` carries a short explanation when the status is non-`full`. The wire shape is identical across Cyclone and Fast DDS — the analyzer doesn't need to know which backend produced the sample.
+
+Fast DDS 2.6.x exposes only a partial dynamic XTypes Python surface today, so the `"raw"` fallback is the common path on Fast DDS user topics — the structural plumbing is identical to Cyclone, the upstream binding completion is the gating factor.
+
+The other DDS tools — `list_participants`, `detect_qos_mismatches`, `participant_events`, `topic_metrics` — work end-to-end on any user-topic deployment ; they don't depend on payload deserialization.
 
 ---
 
 ## 6. What's next
 
-- **v0.3.x patch** — XTypes/IDL discovery to extend `peek_dds_samples` to arbitrary user topics on both backends.
-- **v0.3.x patch** — Extended QoS coverage : Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget.
-- **v0.3.x patch** — Composite adapter routing ROS2 graph tools to `Ros2CliAdapter` and DDS tools to the selected DDS adapter, so both surfaces are usable simultaneously.
-- **v0.4.0+** — `RtiConnextAdapter` in the Pro tier (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`).
+- **v0.5.x patch** — Fast DDS XTypes binding completion to lift `"raw"` → `"full"` for arbitrary user-topic peek on Fast.
+- **v0.5.x patch** — Extended QoS coverage : Liveliness, Ownership, Partition, TimeBasedFilter, LatencyBudget.
+- **v0.5.x patch** — Real-bus validation of the Cyclone XTypes pipeline (the v0.4.0 Phase 1.5 structural pipeline awaits user feedback on real domains).
+- **v0.4.0+ Pro tier** — Real `RtiConnextAdapter` (BYO RTI Connext license, gated by `TOPICFORGE_LICENSE_KEY`). Scaffolded but not yet shipped.
 
 Full strategic roadmap lives in [`docs/product-plan.md`](product-plan.md) and the DDS module spec at [`docs/projet-file/mcp-02-spec.md`](projet-file/mcp-02-spec.md).
 
@@ -149,8 +157,9 @@ Full strategic roadmap lives in [`docs/product-plan.md`](product-plan.md) and th
 - **`pip install topicforge[dds-cyclone]` fails on Windows / macOS Python 3.13+** — `cyclonedds` wheels are typically published for Python 3.8 to 3.12. Pin Python 3.11 or 3.12 for the install host.
 - **`pip install topicforge[dds-cyclone]` fails with `CYCLONEDDS_HOME`** — pip is trying to build `cyclonedds` from source because no wheel matches your platform/Python combination. Either switch to a supported Python (3.11/3.12) or install the native CycloneDDS C library first (see Eclipse CycloneDDS releases).
 - **`pip install topicforge[dds-fast]` fails** — eProsima Fast DDS Python bindings (`fastdds>=2.6.1,<3`) currently ship wheels for Linux first. Windows wheels lag ; consult fast-dds.docs.eprosima.com for the current matrix.
-- **DDS tool returns "v0.3.x roadmap" error** — you called `peek_dds_samples` on an arbitrary user topic. The 4 builtin DCPS topics work today ; arbitrary user-topic peek is a v0.3.x patch (XTypes/IDL discovery).
-- **DDS tool returns "DDS module is not active" error** — your `TOPICFORGE_DDS_BACKEND` is `mock` while `TOPICFORGE_MODE` is `live` (the ROS2 CLI adapter is selected). Set `TOPICFORGE_DDS_BACKEND=cyclone` or `=fast` explicitly to enable the DDS adapters.
+- **DDS tool returns samples with `_decode_status="raw"`** — the binding could not resolve the dynamic XTypes for this user topic. Inspect `_decode_note` for the cause and `_raw_bytes_hex` for the serialized payload. On Fast DDS this is the common path until 2.6.x dynamic XTypes binding completion. On Cyclone, ensure the publisher uses XTypes-discoverable types and re-run.
+- **DDS tool returns "DDS module is not active" error** — your `TOPICFORGE_DDS_BACKEND` is `mock` while `TOPICFORGE_MODE` is `live` (the ROS2 CLI half of the composite is the only one selected). Set `TOPICFORGE_DDS_BACKEND=cyclone` or `=fast` explicitly to enable the DDS half — the `CompositeAdapter` will then serve both surfaces.
+- **DDS tool returns "DDS observability only" with a long remediation message** — the inverse case: a DDS-only adapter is active (the ROS2 CLI is missing on PATH) and you called a ROS2 graph tool. Install ROS2 and source the workspace so `ros2` is on PATH ; the `CompositeAdapter` will pick up both halves on the next run.
 - **`auto` selects the wrong backend** — `auto` prefers Fast > Cyclone > Mock. If you want Cyclone explicitly, set `TOPICFORGE_DDS_BACKEND=cyclone` rather than relying on `auto`.
 
 Report issues at https://github.com/yaniswav/TopicForge/issues.