topicforge 0.5.4__tar.gz → 0.5.6__tar.gz

{topicforge-0.5.4 → topicforge-0.5.6}/.gitignore

@@ -160,6 +160,8 @@ dump.rdb
 *.db3
 *.mcap
 rosbag2_*/
+# Test fixtures that are meant to be committed
+!tests/fixtures/bags/**/*.db3
 
 
 # -------------------------------------------------------------------------
@@ -187,42 +189,8 @@ personal/
 CLAUDE*.md
 
 
-# -------------------------------------------------------------------------
-# Project-local docs and drafts kept out of the package / out of clients.
-# Allowlist exceptions: the folder README explains the convention, and
-# `*-spec.md` files are committable specs produced by pack-growth streams
-# (e.g. Stream C of a release plan). Everything else under projet-file/
-# stays local: PDFs, personal market briefs, raw strategy notes.
-# -------------------------------------------------------------------------
-/docs/projet-file/**
-!/docs/projet-file/README.md
-!/docs/projet-file/*-spec.md
-# Traction snapshots are versioned: weekly JSON + summary + folder README.
-# This is the historical curve that informs decision gates G1/G2/G3
-# (product-plan section 12). Numeric history must survive across machines.
-!/docs/projet-file/traction/
-!/docs/projet-file/traction/**
-# Launch-post drafts (Reddit, LinkedIn, X). Versioned so the maintainer
-# can diff drafts across releases and keep marketing history auditable.
-# Drafts, not production copy, never the public README.
-!/docs/projet-file/launch-posts/
-!/docs/projet-file/launch-posts/**
-# Audit reports (security, architecture) + audit-followup triage docs.
-# Versioned so audit trails survive across machines and the triage
-# decisions are bisectable per release.
-!/docs/projet-file/*-audit-*.md
-!/docs/projet-file/audit-*.md
-# External reference material (OMG interop reports, third-party specs
-# snapshots) the maintainer wants pinned in git so strategy decisions
-# 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/**
+# Owner's private strategy notes, specs and traction snapshots: local only.
+/docs/projet-file/
 /docs/assets/screencast-raw/
 
 
@@ -235,3 +203,6 @@ pro/
 scripts/integration/**/rti_license.dat
 scripts/integration/**/*.dat
 .venv-demo/
+
+# Owner's traction snapshot script (runs from a local scheduled task): local only.
+/scripts/traction-snapshot.sh

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

@@ -5,113 +5,201 @@ 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).
 
-## [Unreleased]
+## [0.5.6] - 2026-10-02
+
+Fixes from a live run of 0.5.3 and 0.5.5 against OmniSim's simulated
+Clearpath Husky (ROS 2 Humble, Fast DDS, Cyclone backend for the DDS tools),
+reported with ground truth by the OmniSim team.
+
+### Added
+
+- `sample_messages` takes `max_array_length` (1..65536, default 128, null for no
+  cut) and `arrays_summary_only`. A cut is listed under `_truncated_after_columns`
+  in the sample and in `note`.
+- Size caps on returned samples: 1 MiB per message and 4 MiB per call
+  (`TOPICFORGE_MAX_SAMPLE_BYTES` sets the per-message cap). Over-cap messages are
+  dropped and `note` says so. `peek_bag_samples` is capped the same way, and its
+  arrays are cut at 4096 elements.
+- `BagTopicStats` gains `first_timestamp_ns`, `last_timestamp_ns`,
+  `frequency_basis` (`topic_span` or `bag_duration`) and `latched`.
+- `TopicInfo.qos_durability`; `qos_reliability` and `qos_durability` are filled
+  by `get_topic_info` from the publishers' QoS (`mixed` when they disagree).
+- `HealthReport.dds_inactive_reason` says why `dds_backend` is `none`.
+- A real Humble rosbag2 bag from the OmniSim team as a test fixture
+  (`tests/fixtures/bags/omnisim_humble/`).
+
+### Changed
+
+- `list_topics` (live) uses one `ros2 topic list -v` call for publisher and
+  subscriber counts instead of one `ros2 topic info` per topic, falling back to
+  the per-topic calls if the output is not recognized. It leaves QoS null.
+- `rosbags>=0.11.3` is required (0.10 reads a bare `.db3` as ROS 1 and returns
+  message definitions and QoS as plain strings).
+- A latched topic gets no rate only when its messages span under 1 second (a
+  start-up burst such as `/tf_static`); a latched topic published over a longer
+  span keeps its rate. `latched` is unchanged.
+- `analyze_bag` reads per-topic times of an `.mcap` bag only up to 200 MiB and
+  5 s; past either it keeps `bag_duration` rates and says so in the new
+  `BagAnalysis.note`.
+- The `policies_checked` entry for History reads "History (risky only, where
+  announced)".
+- `max_array_length` also cuts strings and bytes to that many characters plus
+  `...`; those cells are listed under `_truncated_columns`.
+- `QosProfile.history` is now optional, and a new `history_note` explains why it
+  is missing. DDS discovery does not carry History (the builtin endpoint data has
+  no such member), so TopicForge reports it only for its own endpoints and for
+  Cyclone DDS peers that set something other than the default. For Fast DDS, RTI
+  and unknown-vendor endpoints it is `null`; for a Cyclone peer, KEEP_LAST depth 1
+  is also `null` because the binding fills missing QoS with that default. Clients
+  that assumed `history` is always a string must handle `null`.
+- A discovered endpoint that announced no History keeps its reliability,
+  durability and the other policies; before, the whole `qos` became `null`.
+- `detect_qos_mismatches` judges the KEEP_ALL-vs-KEEP_LAST History risk only
+  where both sides announced History; elsewhere one hint states that discovery
+  does not carry it, instead of a warning on every pair.
+
+### Fixed
+
+- `sample_messages` with `arrays_summary_only` shifted every CSV column after an
+  array: `<sequence type: float, length: 541>` contains a comma and was split in
+  two. It is one cell now.
+- `sample_messages` returned no samples and no explanation when the echo timed
+  out (for example a large message with `max_array_length` null); `note` now says
+  so.
+- `list_topics` reported 0 publishers and 0 subscribers for a topic missing from
+  `ros2 topic list -v`; it now asks `ros2 topic info` for that topic.
+- `peek_bag_samples` converted a whole numpy array to a list before cutting it
+  at 4096 elements; it now converts only the part it keeps.
+- Fast DDS endpoints no longer report a History taken from the binding's
+  defaults: `detect_qos_mismatches` treats it as not announced, like the other
+  vendors. This path has never run against a real Fast DDS bus.
+- The `tests/fixtures/bags` bag is left out of the sdist.
+- `peek_bag_samples` failed on every Humble `.db3` bag with "Bag contains no
+  type definitions". The reader now gets the type definitions of the distro the
+  bag records, or Humble, and `note` says which. `LaserScan.ranges` and other
+  numeric arrays now come back as lists, not a numpy repr string.
+- `analyze_bag` rates were count / whole-bag duration, 0.1 to 0.7 percent off on
+  periodic topics and meaningless on latched ones (`/tf_static` showed 0.06 Hz,
+  `/rosout` 0.37 Hz). They are now `(n - 1) / (last - first)` per topic, read
+  from the bag when it is readable locally, and latched topics are flagged.
+- `get_topic_info` returned `qos_reliability: null` on every topic although the
+  CLI prints Reliability and Durability per endpoint.
+- `peek_dds_samples('/scan')` reported the topic as not discovered while
+  `rt/scan` and `scan` worked; it now resolves the name like the other DDS tools
+  and says which topic matched.
+- The "DDS module is not active" error said to install the Cyclone binding even
+  when it was installed. It now states the actual cause: backend not selected,
+  binding missing, or adapter failed to start. README wording aligned.
+- CSV `...` truncation cells from `ros2 topic echo` no longer count as data
+  columns.
+- `ros2` output is decoded as UTF-8 on Windows instead of cp1252.
+- `detect_qos_mismatches` no longer calls service, action, `rosout`,
+  `parameter_events` or `ros_discovery_info` topics typos of each other (for
+  example `get_parametersRequest` vs `set_parametersRequest`), and no longer
+  reports them as orphans. Only plain `rt/` topics and bare DDS names are compared.
+- The "differs by N edits" hint is now only given between a writer-only name and
+  a reader-only name; a topic with both sides is never suggested as a typo.
+
+## [0.5.5] - 2026-10-02
+
+Tool outputs were reworked after testing them with LLM agents on the author's
+16 test scenarios (live DDS buses with planted faults).
+
+### Breaking
+
+- `detect_qos_mismatches` returns a `MismatchScan` envelope instead of a bare
+  list. Migrate by reading `["reports"]` where you used the list.
+
+### Added
+
+- `list_endpoints`, the twelfth tool: every announced DDS writer and reader with
+  owning participant, structured QoS and a per-topic roll-up that flags orphans
+  (`no_reader`, `no_writer`). Cyclone and mock only.
+- Continuous discovery tracking on Cyclone, so a node restarted three times
+  shows as 3 `lost` and 4 `discovered` events dated by DDS, not by poll time.
+- `announced_ns`, `lost_ns`, `time_source` and related timestamp fields on
+  `participant_events` and `list_participants`.
+- `health_check` reports `now_ns`, tracker status and an observed-domain note.
+- `QosProfile` gains Liveliness, Ownership, Partition, LatencyBudget,
+  DestinationOrder and DataRepresentation.
+- `peek_dds_samples` on builtin discovery topics returns structured endpoint
+  and participant fields instead of a raw repr string.
+- Topic filters accept `rt/x` and `x` interchangeably; a filter that matches
+  nothing returns the known topics.
+- `detect_qos_mismatches` also reports `matched` and `not_matched` pairs, hints
+  (near-miss topic names, path suffixes, type id differences), and the policies
+  it did and did not check.
+
+### Changed
+
+- `detect_qos_mismatches` checks Partition first (with `*` and `?` wildcards),
+  then type names, then the RxO rules; Liveliness, LatencyBudget, Ownership,
+  DestinationOrder and DataRepresentation join Reliability, Durability and
+  Deadline.
+- `topic_metrics` and `peek_dds_samples` on a user topic say they have no data
+  instead of returning zeros or a placeholder.
+- Tool descriptions no longer carry internal history.
+
+### Fixed
+
+- Infinite durations are `None` instead of 9223372036854775807.
+- Races between the tracker and tool calls could mark a live participant lost
+  or keep endpoints of a departed one.
+- Concurrent cyclonedds calls could corrupt the heap on Windows; every binding
+  call now takes one lock.
+- A failing tracker no longer adds 3 s to every tool call.
+- An unreadable QoS duration is treated as unknown, not infinite.
+- Typo hints stay bounded on a bus with a thousand topics.
+
+### Known limits
+
+- A hung writer (alive, no data) cannot be observed without a data probe.
+- A crash and a clean leave look the same; `lost_ns` is an upper bound.
+- A participant that cycles faster than the history depth between two tracker
+  passes can be missed.
+- The Fast DDS backend has never run on a bus; `list_endpoints` is not
+  supported there.
+- DDS Security is not supported, and user-topic payload decoding is disabled.
 
 ## [0.5.4] - 2026-10-02
 
-First run of the DDS code against a live multi-vendor bus (Windows 11, a
-Python / Cyclone DDS participant and a Rust / Dust DDS participant, TopicForge
-driven by a real MCP client). Until now every DDS adapter had only been
-checked statically. The run exposed four defects that together made the DDS
-module non-functional on Cyclone; all are fixed and pinned by tests.
+First run of the DDS code against a live bus (Windows 11, a Python / Cyclone DDS
+participant and a Rust / Dust DDS participant). It exposed four defects that
+left the DDS module non-functional on Cyclone; all are fixed and tested.
 
 ### Fixed
 
-- Role nodes published below their rate (about 7 Hz for 10 Hz on Windows):
-  they now keep an absolute schedule.
-
-- **`list_participants` now reports the participant name and the hostname on
-  Cyclone.** The name comes from the EntityName QoS and the hostname from the
-  `__Hostname` discovery property; both were always null on a real bus.
-- **Participant GUIDs were never read.** cyclonedds 11.0.1 exposes the builtin
-  key as a `uuid.UUID`, which the extractor did not handle, so every
-  participant collapsed onto a single `unknown` entry.
-- **Vendors were never identified.** The builtin participant sample carries no
-  vendor field. The vendor id is now read from the first two bytes of the GUID
-  prefix, as RTPS recommends; implementations that do not follow that
-  convention (Dust DDS, and RTI by default) still report `unknown`, because
-  the Cyclone Python binding does not expose the vendor id from the RTPS
-  header.
-- **The OMG vendor-id table was wrong.** It mapped `01.05` to Fast DDS and
-  `01.16` to Cyclone; the correct ids are `01.0F` (eProsima) and `01.10`
-  (Eclipse), verified against both vendors' sources. The Cyclone side ran on a
-  live bus; the Fast DDS side (`fast_extract_vendor_id`) is verified
-  statically only, since its tests need a binding that is not on PyPI. The `vendor` field of
-  `ParticipantInfo` and `ParticipantEvent` now also accepts `rti_micro`,
-  `opensplice`, `opendds`, `coredx`, `intercom` and `dust` (soft-breaking for
-  clients validating the previous enum).
-- **`detect_qos_mismatches` never reported anything on Cyclone.** cyclonedds
-  scopes its policy class names (`Reliability.BestEffort`), and the
-  normalizer matched only the bare name, so no QoS profile was ever built.
-- **A stopped participant never disappeared.** Discovery readers keep the last
-  sample of a departed participant with a NOT_ALIVE instance state; those are
-  now ignored for participants and endpoints, so a participant is reported as
-  left when its lease expires, and a dead endpoint no longer produces a
-  mismatch.
-
-- Cyclone adapter created a new DDS reader on a builtin discovery topic on
-  every tool call and never deleted it. It now keeps one reader per builtin
-  topic and takes a non-blocking snapshot, so calls no longer wait 2 s each
-  (`detect_qos_mismatches` waited 4 s).
-- `peek_dds_samples` on `DCPSPublication` / `DCPSSubscription` reported the
-  endpoints of participants that had left; disposed entries are now dropped.
-  Its payload also carries the endpoint `type_name`.
-- `test_dds_cross_vendor.py` expected an error message from v0.3; it had
-  never run, since CI has no DDS binding. First run against the real Cyclone
-  binding.
+- `list_participants` reports the participant name and hostname on Cyclone
+  (both were always null).
+- Participant GUIDs were never read, so every participant collapsed onto one
+  `unknown` entry.
+- Vendors were never identified. The vendor id is now read from the GUID prefix;
+  Dust DDS and RTI by default still report `unknown`.
+- The OMG vendor-id table mapped Fast DDS and Cyclone to the wrong ids (now
+  `01.0F` and `01.10`). The Fast DDS side is verified statically only.
+- `ParticipantInfo.vendor` also accepts `rti_micro`, `opensplice`, `opendds`,
+  `coredx`, `intercom` and `dust`.
+- `detect_qos_mismatches` never reported anything on Cyclone because policy
+  class names were not normalized.
+- A stopped participant never disappeared; departed participants and endpoints
+  are now dropped.
+- The Cyclone adapter leaked a reader per tool call and waited 2 s each; it now
+  keeps one reader per builtin topic.
+- `peek_dds_samples` on `DCPSPublication` / `DCPSSubscription` listed endpoints
+  of participants that had left, and now includes the endpoint `type_name`.
+- Example role nodes published below their rate on Windows.
 
 ### Added
 
-- `examples/dds/`: a "write the code" track. Examples 00 (hello publisher
-  and subscriber), 05 (Reliability), 06 (Durability and the late joiner),
-  07 (Deadline declared and kept) and 08 (a crash seen from inside and from
-  outside) each ship a readable `publisher.py` and `subscriber.py` in Cyclone
-  DDS Python; the subscriber prints what it receives and the DDS statuses,
-  and TopicForge explains the same situation from outside. All fourteen
-  examples pass on a live bus.
-- The generic role nodes print one line per second per reader with what
-  they received, and examples 02, 04, 10 and 13 check that the broken
-  subscriber receives nothing while the control one receives data.
-- The harness keeps each program's output in a log file and prints it live
-  under `--hold`.
-
-- `scripts/integration/interop_check.py`: one-command multi-vendor demo
-  that starts a Rust / Dust and a Python / Cyclone participant, drives
-  TopicForge over stdio through the official MCP client, checks participant
-  discovery, a deliberate Reliability mismatch between the two vendors, and
-  the departure of a stopped participant, then stops every process it started.
-- A real Rust / Dust DDS participant (`publishers/dust_publisher`) and a real
-  Python / Cyclone participant replacing the previous scaffold, which never
-  wrote a sample.
-- Twelve interop programs in total, one per vendor and language with an
-  officially released binding (Cyclone C / C++ / Rust / Python, Dust Rust /
-  Python, Fast DDS C++ / Python, RTI Connext C / C++ / Python, OpenSplice C),
-  all following the contract in `scripts/integration/DEMO_CONTRACT.md`. The
-  driver starts whichever ones are built on the host and adapts its checks;
-  `--list` shows what can run. Only Cyclone Python and Dust Rust / Python / C
-  have been run, on Windows; the rest are written but unrun. RTI participants
-  need a local license and are never run in CI.
-- One-command launch scripts, `scripts/integration/launch/setup` and
-  `run_demo` (`.ps1` and `.sh`), which create `.venv-demo`, install the Cyclone
-  binding and build the Rust participant. `setup.ps1 -Firewall` adds inbound
-  UDP 7400-7500 rules on private networks for multi-machine runs.
-- Unicast peer configuration for Cyclone and Fast DDS and a guide for a mixed
-  Linux and Windows bus (`scripts/integration/config/`).
-- `.github/workflows/demo.yml` runs the driver with the Cyclone and Dust
-  participants on Ubuntu and Windows; `demo-fast.yml` builds Fast DDS 3 from
-  pinned tags and starts the C++ participant (weekly and manual).
-- `scripts/integration/README.md` rewritten around the demo: it previously
-  described the removed docker / scenario rig.
-
-- `examples/dds/`: real use cases 10 to 14 (driver swap, wiring, safety
-  monitor dropout, deadline not offered, restart loop) next to the concept
-  examples 01 to 04. All nine pass on a live bus.
+- `examples/dds/`: fourteen runnable examples (concepts and use cases), all
+  passing on a live bus.
+- `scripts/integration/`: a demo driver, twelve interop programs (Cyclone, Dust,
+  Fast DDS, RTI, OpenSplice), one-command setup scripts and CI workflows. Only
+  Cyclone Python and Dust Rust / Python / C have been run, on Windows.
 
 ### Removed
 
-- The docker / scenario integration rig (`scenarios_runner.py`, `run-local.*`,
-  `docker-compose.yml`, per-vendor Dockerfiles, scenario JSON files, schema
-  test and `integration.yml`) is removed in favour of the demo driver.
+- The docker / scenario integration rig, replaced by the demo driver.
 
 ## [0.5.3] - 2026-10-01
 
@@ -1114,7 +1202,9 @@ 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.6...HEAD
+[0.5.6]: https://github.com/yaniswav/TopicForge/compare/v0.5.5...v0.5.6
+[0.5.5]: https://github.com/yaniswav/TopicForge/compare/v0.5.4...v0.5.5
 [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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topicforge
-Version: 0.5.4
+Version: 0.5.6
 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
@@ -45,7 +45,7 @@ Requires-Dist: pydantic>=2.6
 Provides-Extra: all
 Requires-Dist: cyclonedds>=0.10; extra == 'all'
 Provides-Extra: bags
-Requires-Dist: rosbags>=0.9; extra == 'bags'
+Requires-Dist: rosbags>=0.11.3; extra == 'bags'
 Provides-Extra: dds
 Requires-Dist: cyclonedds>=0.10; extra == 'dds'
 Provides-Extra: dds-cyclone
@@ -53,7 +53,7 @@ Requires-Dist: cyclonedds>=0.10; extra == 'dds-cyclone'
 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: rosbags>=0.11.3; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -65,17 +65,17 @@ Description-Content-Type: text/markdown
 [![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)
+[![Read-only](https://img.shields.io/badge/safety-read--only-2563eb)](https://github.com/yaniswav/TopicForge#security-model)
 
-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.
+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. The code has no write path: it cannot publish to the bus or command a robot, and there is no permission system to configure.
 
-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.
+It gives the agent twelve typed tools that return frozen Pydantic schemas, identical whether the server talks to a real robot or to its built-in mock fixtures. Ask why `nav_planner` gets no scan, and the agent reads the bus, finds the BEST_EFFORT writer facing a RELIABLE reader and names the incompatible policy (see [`examples/02-debug-qos-mismatch.md`](examples/02-debug-qos-mismatch.md)). It is meant for 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).
+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. So far the author has observed Cyclone DDS and Dust DDS participants on a live bus. RTI Connext, OpenDDS, CoreDX and Fast DDS announce themselves through the same standard discovery, but none of them has been observed yet. This covers discovery only: participants, readers, writers and their QoS. See [`docs/dds-interop-matrix.md`](docs/dds-interop-matrix.md).
 
 ## Quickstart
 
-No ROS2 needed; the mock adapter serves deterministic fixtures for a small differential robot (LIDAR + RGB camera). Python 3.10 to 3.13.
+No ROS2 is needed; the mock adapter serves deterministic fixtures for a small differential robot (LIDAR + RGB camera). Python 3.10 to 3.13.
 
 ```bash
 pip install topicforge
@@ -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.
+Every response except `health_check` carries `mode_effective` (`"live"` or `"mock"`), so a caller can tell a real graph from fixtures.
 
 | Tool                    | Purpose                                                                                          |
 | ----------------------- | ------------------------------------------------------------------------------------------------ |
@@ -109,13 +109,14 @@ All eleven tools are read-only. Every response except `health_check` carries `mo
 | `list_topics`           | Discover the ROS2 graph                                                                          |
 | `get_topic_info`        | Message type, publisher/subscriber counts and QoS for one topic                                  |
 | `sample_messages`       | Peek recent messages on a ROS2 topic (count clamped to 50)                                       |
-| `analyze_bag`           | Summarize a `.mcap` / `.db3` / `.bag` recording                                                  |
+| `analyze_bag`           | Summarize a `.mcap` / `.db3` recording or `rosbag2_*` directory (via `ros2 bag info`)      |
 | `list_participants`     | DDS participants on the domain: vendor, `name` (EntityName QoS, Cyclone) and `hostname`          |
 | `detect_qos_mismatches` | Incompatible QoS pairs between DDS readers and writers                                           |
 | `peek_dds_samples`      | Raw DDS samples; structured on the three builtin discovery topics, presence-only on user topics   |
 | `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]`)                       |
+| `peek_bag_samples`      | Decoded samples from a recorded bag, including ROS 1 `.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,9 +137,9 @@ 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). The default `mock` selects no DDS backend: installing the Cyclone binding is not enough, you must also set `TOPICFORGE_DDS_BACKEND=cyclone`. With `TOPICFORGE_MODE=live` and no backend selected, the DDS tools raise `DDS module is not active: ...` with the actual cause (backend not selected, binding not installed, or binding installed but the adapter failed to start), and `health_check` reports `dds_backend: "none"` plus `dds_inactive_reason`. 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).
+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,; Cyclone already sees those vendors' participants through standard discovery. 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).
 
 ## Configuration reference
 
@@ -148,55 +149,59 @@ A Fast DDS adapter exists but has never run against a bus, and its `fastdds` Pyt
 | `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 telemetry; an unrecognized value aborts startup. See [Telemetry](#telemetry)     |
-| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock`, `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                                 |
+| `TOPICFORGE_DDS_BACKEND`   | `mock`  | `mock` (no DDS backend), `cyclone`, `fast`, `auto` (`opendds` and `dust` are stubs)                |
 | `TOPICFORGE_DDS_DOMAIN_ID` | `0`     | DDS domain observed (0..232). Joined at startup; changing it needs a restart                      |
+| `TOPICFORGE_MAX_SAMPLE_BYTES` | `1048576` | Size cap for one sampled message (1 KiB..64 MiB); a call returns at most 4 times that. Over-cap messages are dropped with a note |
 
 Samples with comments are in [`.env.example`](.env.example). Any invalid value stops the server with `topicforge: configuration error: ...` and exit code 2, so a typo cannot silently change behaviour.
 
 ## 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.
-- **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.
-- **`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.
+- DDS validation is partial. The Cyclone adapter has run against a real bus, with Cyclone and Dust DDS participants, on Windows and in CI on Ubuntu and Windows (`.github/workflows/demo.yml`). The Fast DDS adapter has never run against a bus, and no RTI, OpenDDS, CoreDX or OpenSplice participant has been observed by this project. The multi-vendor claim rests on the RTPS protocol guarantee, not on a recorded cross-vendor run.
+- User-topic payloads are not decoded. `peek_dds_samples` on a user topic returns count 0 and a note that the topic is announced on the bus; no traffic is read. `topic_metrics` therefore has data only for the builtin discovery topics and says so in its `status`. It is a discovery-layer probe, not a publish-rate monitor.
+- Liveliness at runtime is not observed. A writer that is alive but silent (a hung process whose lease is still renewed) looks healthy, because TopicForge reads discovery, not data. An opt-in data probe is planned 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`.
+- 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, so it returns at most one message, and 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. Arrays are cut at 128 elements by default; `max_array_length` (1..65536, or null for no cut) and `arrays_summary_only` change that, and a cut is listed under `_truncated_after_columns`.
+- `analyze_bag` (live) parses `ros2 bag info` text for the totals and counts; anomaly detection is mock-only. Per-topic times, rates (`(n - 1) / span`) and `latched` are added when the bag can be read locally (`.db3` with the standard library, `.mcap` with `rosbags`), else rates fall back to count / bag duration (`frequency_basis`). `peek_bag_samples` reads the file itself, through `rosbags`, and is served only by the ROS2 CLI adapter or the mock; bags that embed no message definitions (Humble `.db3`) are decoded with the Humble definitions, or the distro the bag records, and `note` says so. Without `ros2`, bag tools return fixtures: check `health_check` for `mode: "mock"` before trusting bag output.
+- Synchronous handlers: the tools run on the MCP event loop; on Windows a hung `ros2` launcher can block the server.
 - No streaming or push subscriptions: tools are strictly request/response.
 
-The roadmap and the open work behind these limits are in [`docs/product-plan.md`](docs/product-plan.md).
+Next: an opt-in probe to tell a hung writer from a healthy one, wider real-bus validation (Fast DDS, RTI, OpenDDS), and DDS Security. Open work is tracked in [issues](https://github.com/yaniswav/TopicForge/issues).
 
 ## Telemetry
 
-Opt-in, anonymous and **off by default**. When off, instrumentation returns the handler unchanged: no event is built, no transport is constructed, no network code runs (pinned by `tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
+Opt-in, anonymous and off by default. When off, instrumentation returns the handler unchanged: no event is built, no transport is constructed, no network code runs (pinned by `tests/test_telemetry.py::test_build_app_off_makes_no_transport_calls`).
 
 ```bash
 TOPICFORGE_TELEMETRY=on python -m topicforge
 ```
 
-On-values: `on`, `1`, `true`, `yes`, `enabled`. Off-values: unset, `off`, `0`, `false`, `no`, `disabled`. Anything else is a configuration error, not a silent "off".
+On-values: `on`, `1`, `true`, `yes`, `enabled`. Off-values: unset, `off`, `0`, `false`, `no`, `disabled`. Anything else is a configuration error rather than a silent "off".
 
 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.6"`       | TopicForge server version                                   |
 | `session_id` | `"a1b2c3..."`   | Random UUID per process, never persisted                    |
 | `success`    | `true`          | Whether the handler returned or raised                      |
 
-Never sent: topic names, message types or payloads, bag paths or contents, hostnames, usernames, IP addresses, environment variables, error messages. The field set is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`; adding a field requires updating this section. The default transport is a structured log line, there is no HTTP endpoint yet. The implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/).
+Never sent: topic names, message types or payloads, bag paths or contents, hostnames, usernames, IP addresses, environment variables, error messages. The field set is fenced by `tests/test_telemetry.py::test_payload_contains_only_whitelisted_keys`; adding a field requires updating this section. The default transport is a structured log line; there is no HTTP endpoint yet. The implementation is in [`src/topicforge/telemetry/`](src/topicforge/telemetry/).
 
 ## Security model
 
-TopicForge is designed for **local trust**: it runs as a subprocess of your MCP client on a machine you control and inspects your own ROS2 graph, DDS domain and bag files. It is not hardened for adversarial inputs.
+TopicForge is designed for local trust: it runs as a subprocess of your MCP client on a machine you control and inspects your own ROS2 graph, DDS domain and bag files. It is not hardened for adversarial inputs.
 
 - `TOPICFORGE_ROS2_BIN` accepts an arbitrary path; treat it the way you treat `PATH`.
 - `analyze_bag` and `peek_bag_samples` open whatever path the client passes (no workspace isolation, no symlink restriction).
 - All `ros2` invocations use `subprocess.run` with an argument list, never `shell=True`. ROS2 topic names are validated against `^/[A-Za-z0-9_/]+$` first.
-- The server loads no third-party code at startup. Until 0.5.2 it imported any installed `topicforge_pro` package; that hook was removed in 0.5.3 because it was an opening for a package of that name to add write tools.
+- The server loads no third-party code at startup.
 - No outbound network calls unless telemetry is turned on.
 
 Before exposing TopicForge to untrusted MCP clients (hosted endpoints, shared environments), add path isolation and revisit the `TOPICFORGE_ROS2_BIN` policy. Vulnerability reports: see [`SECURITY.md`](SECURITY.md).
@@ -215,7 +220,7 @@ Tests run against the mock adapter, the live adapter's pure parsers and the bind
 
 ## Upgrading
 
-TopicForge is pre-1.0 and the 0.x releases changed things freely; [`CHANGELOG.md`](CHANGELOG.md) is the record. Two points matter if you are coming from an old install. Releases 0.3.0 to 0.5.2 are yanked, so `pip install -U topicforge` resolves to 0.5.3 or later. And since 0.5.3 the `[dds-fast]`, `[dds-opendds]`, `[dds-dust]` and `[dds-all-oss]` extras no longer exist, the DDS backend values `rti`, `opensplice`, `coredx` and `intercom` are rejected, and `[dds]` and `[all]` resolve to Cyclone only. Schema changes across 0.x were additive optional fields; a client that pins a JSON Schema with `additionalProperties: false` needs to regenerate it.
+TopicForge is pre-1.0; [`CHANGELOG.md`](CHANGELOG.md) lists every change, including the yanked releases and removed extras.
 
 ## Layout
 
@@ -238,4 +243,4 @@ Layers are strictly separated: handlers never call `subprocess`, adapters are th
 
 ## License
 
-MIT, see [LICENSE](LICENSE). Commercial support and integration work: [`docs/pro.md`](docs/pro.md).
+MIT, see [LICENSE](LICENSE). Integration or support work for a specific ROS 2 / DDS setup: ethvignot.yanis@gmail.com.