backplane-tracecheck 0.2.0__tar.gz

backplane_tracecheck-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Local-only material (old reports, governance files, MVP evidence). Never committed.
+archive/
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Tracecheck output
+reports/
+*.report.json
+*.report.html
+
+# Web
+node_modules/
+web/dist/
+.firebase/
+.wrangler/
+
+# OS / editors
+.DS_Store
+Thumbs.db
+desktop.ini
+.vscode/
+.idea/

backplane_tracecheck-0.2.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-14
+
+### Added
+- **Compressed chunks.** zstd and lz4 chunks are decoded, with output strictly capped at the declared uncompressed size, so decompression bombs fail safely.
+- **Streaming reader** (`tracecheck.reader`): a self-contained, bounded MCAP parser. SHA-256 and CRCs are computed in a single pass, and memory is bounded by explicit limits. The 64 MiB file-size cap is gone.
+- **Fast mode** (`--fast`): reads only the summary section for an instant inventory, counts, schemas and metadata check. It falls back to a full scan when the summary is missing or incomplete.
+- **`missing_crc` contract key** (`"warn"` or `"ignore"`) and the `--ignore-missing-crc` flag.
+- Summary-section CRC verification.
+- CLI flags: `--fail-on`, `--timeout`, `--max-chunk-mib`, `--max-record-mib`, `--max-tracked-messages`, `--quiet`, `--version`, and `samples --dest`.
+- Report fields (`report_version` 2): `scan_mode`, `fast_mode_fallback`, `compression`, `scan_stats`, `checksum_coverage`.
+- More synthetic examples: zstd, lz4, unchunked, no-CRC, unsupported-codec, malformed and truncated files, plus a 4-topic mobile-robot recording with and without a sensor dropout. `examples/expected.json` holds the golden results shared by the Python and browser test suites.
+- **Web app** (`web/`): a browser-only static site for backplanerobotics.com with the Tracecheck app.
+  - A JavaScript port of the engine running in a Web Worker. Files never leave the browser.
+  - Handles multi-GB files and zstd/lz4 chunks.
+  - Demo recordings, a contract editor, and JSON/HTML report downloads.
+  - Reports are byte-identical to the Python CLI's, apart from timestamps and tool fields.
+  - A strict Content-Security-Policy.
+
+### Changed
+- Renamed the project from "Recording Health Checker" to **Backplane Tracecheck**.
+  - The Python package `rhc` is now `tracecheck`.
+  - The PyPI distribution is `backplane-tracecheck`.
+  - The CLI command is `tracecheck`.
+- `tracecheck check` runs in-process, with no subprocess and no size cap. The local `serve` UI keeps its 64 MiB upload limit.
+- **Missing-CRC rule.** C01 now warns only when some message data has no CRC coverage. Default ROS 2 files, which have chunk CRCs but no data-section CRC, now pass.
+- Packaged with `pyproject.toml` (hatchling), replacing `requirements*.txt` and the Windows `.cmd` launchers.
+- Relicensed as Apache-2.0 open source.
+
+### Fixed
+- The local server no longer returns stderr text or the user's home path in error responses.
+- The local server now requires a matching `Origin` header on POST requests.
+
+### Removed
+- MVP governance, evidence, QA and marketing files were moved out of the repository into a local archive.
+
+## [0.1.0] - 2026-10-13
+
+### Added
+- Initial MVP: CLI and local browser UI, 10 contract checks, JSON and HTML reports, and synthetic examples.

backplane_tracecheck-0.2.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

backplane_tracecheck-0.2.0/NOTICE

@@ -0,0 +1,5 @@
+Backplane Tracecheck
+Copyright 2026 Backplane Robotics LLC
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+Third-party components and their licenses are listed in docs/THIRD_PARTY_NOTICES.md.

backplane_tracecheck-0.2.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: backplane-tracecheck
+Version: 0.2.0
+Summary: Check robot recordings (MCAP) against an explicit, versioned recording contract.
+Project-URL: Homepage, https://backplanerobotics.com
+Project-URL: Source, https://github.com/backplane-robotics/backplane-tracecheck
+Project-URL: Issues, https://github.com/backplane-robotics/backplane-tracecheck/issues
+Project-URL: Changelog, https://github.com/backplane-robotics/backplane-tracecheck/blob/main/CHANGELOG.md
+Author: Backplane Robotics LLC
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: data-quality,mcap,recording,robotics,ros2,rosbag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: lz4>=4.3
+Requires-Dist: mcap<2,>=1.5
+Requires-Dist: zstandard>=0.22
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Backplane Tracecheck
+
+**Check robot recordings against an explicit recording contract.**
+
+Tracecheck reads an [MCAP](https://mcap.dev) recording (the default ROS 2 bag format) and checks it against a small JSON *recording contract*: which topics must be present, their schemas and encodings, message counts, rates, timestamp gaps, regressions, sequence continuity and time coverage. It produces a JSON report and a readable HTML report. Each finding points to an exact byte offset in the file.
+
+- Free and open source (Apache-2.0).
+- Read-only. Message payloads are never decoded or executed.
+- No robot, ROS install, account or cloud service needed.
+- Streams files of any size. Handles zstd and lz4 chunks safely.
+- Runs as a Python CLI or entirely in your browser at **[backplanerobotics.com/tracecheck](https://backplanerobotics.com/tracecheck/)**, where files never leave your device.
+
+Built by [Backplane Robotics](https://backplanerobotics.com).
+
+## Install
+
+```bash
+pip install backplane-tracecheck
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+# Write the synthetic demo recordings and contract to ./examples
+tracecheck samples
+
+tracecheck validate-contract examples/demo-contract.json
+tracecheck check examples/clean.mcap  --contract examples/demo-contract.json --out reports/clean
+tracecheck check examples/faults.mcap --contract examples/demo-contract.json --out reports/faults
+
+# Optional local browser UI (binds to 127.0.0.1 only)
+tracecheck serve --open
+```
+
+`--out` must be a new directory. Existing reports are never overwritten.
+
+**Useful options**
+
+| Option | Effect |
+|---|---|
+| `--fast` | Read only the summary section: inventory, counts, schemas and metadata in milliseconds. Timing checks (C06–C10) skip. Falls back to a full scan if the file has no usable summary. |
+| `--ignore-missing-crc` | Don't warn when the writer stored no CRCs (same as `"missing_crc": "ignore"` in the contract). Corrupt CRCs still fail. |
+| `--fail-on fail` | Exit 0 on warnings, exit 1 only on failures (the default `warn` also exits 1 on warnings). |
+| `--timeout SECONDS` | Stop a scan that takes too long. |
+| `--max-chunk-mib`, `--max-record-mib`, `--max-tracked-messages` | Raise or lower the memory safety limits (defaults: 256, 256, 20,000,000). |
+
+**Exit codes**
+- `0`: overall pass.
+- `1`: contract failures, warnings or an incomplete scan (all recorded in the report).
+- `2`: configuration, input or operational error. No report is written.
+
+## In the browser
+
+[backplanerobotics.com/tracecheck](https://backplanerobotics.com/tracecheck/) runs the same checks in a Web Worker, using a JavaScript port of the engine in [`web/src/engine/`](https://github.com/backplane-robotics/backplane-tracecheck/tree/main/web/src/engine).
+- The file is read locally in slices and never uploaded.
+- The site's Content-Security-Policy blocks connections to any other origin.
+- For the same inputs, the browser and CLI produce identical JSON reports, apart from timestamps and tool fields. The web test suite checks this.
+
+## A minimal contract
+
+```json
+{
+  "version": 1,
+  "name": "My recording requirements",
+  "topics": {
+    "/my/topic": { "required": true, "min_count": 1 }
+  }
+}
+```
+
+Start minimal, then read the report's channel inventory to see the actual schema names, encodings and fingerprints. Add only the requirements you can justify. See [docs/CONTRACT_REFERENCE.md](https://github.com/backplane-robotics/backplane-tracecheck/blob/main/docs/CONTRACT_REFERENCE.md) for every key.
+
+## The ten checks
+
+| ID | Check |
+|---|---|
+| C01 | Readable bounded MCAP scan (with CRC verification where present) |
+| C02 | Required topics contain messages |
+| C03 | Profile, schema and encoding |
+| C04 | Required file metadata |
+| C05 | Message counts |
+| C06 | Average recorded rate |
+| C07 | Sorted timestamp gaps |
+| C08 | Record-order timestamp regressions |
+| C09 | Sequence continuity |
+| C10 | Expected interval coverage |
+
+**Statuses**
+- **PASS:** the configured requirement was met.
+- **WARN:** a scoped limitation, for example message data with no CRC coverage. Default ROS 2 files with chunk CRCs pass.
+- **FAIL:** an unmet requirement or a failed scan. It does not mean the robot is unsafe.
+- **SKIPPED:** no conclusion was reached.
+
+Tracecheck does not certify safety, establish regulatory compliance, determine causality or measure transport latency.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use `source .venv/bin/activate` elsewhere
+pip install -e ".[dev]"
+python -m pytest
+```
+
+After an intentional behaviour change, regenerate the golden results shared by both test suites and review the diff:
+
+```bash
+tracecheck samples && python tools/make_golden.py
+```
+
+**Website** (Node 20+):
+
+```bash
+cd web
+npm install
+npm test          # engine parity tests against examples/ and the Python engine
+npm run dev       # local dev server
+npm run build     # static site in web/dist (deploy to Cloudflare Pages)
+```
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `src/tracecheck/` | Python package and CLI |
+| `tests/` | Engine, streaming, contract, CLI and local-server tests |
+| `examples/` | Synthetic MCAP recordings, contracts and golden results (invented data) |
+| `docs/` | Contract reference and third-party notices |
+| `tools/` | Maintenance scripts (golden-result generator) |
+| `web/` | Browser-only website and Tracecheck web app for backplanerobotics.com |
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/backplane-robotics/backplane-tracecheck/blob/main/LICENSE) and [NOTICE](https://github.com/backplane-robotics/backplane-tracecheck/blob/main/NOTICE). Copyright 2026 Backplane Robotics LLC.

backplane_tracecheck-0.2.0/README.md

@@ -0,0 +1,136 @@
+# Backplane Tracecheck
+
+**Check robot recordings against an explicit recording contract.**
+
+Tracecheck reads an [MCAP](https://mcap.dev) recording (the default ROS 2 bag format) and checks it against a small JSON *recording contract*: which topics must be present, their schemas and encodings, message counts, rates, timestamp gaps, regressions, sequence continuity and time coverage. It produces a JSON report and a readable HTML report. Each finding points to an exact byte offset in the file.
+
+- Free and open source (Apache-2.0).
+- Read-only. Message payloads are never decoded or executed.
+- No robot, ROS install, account or cloud service needed.
+- Streams files of any size. Handles zstd and lz4 chunks safely.
+- Runs as a Python CLI or entirely in your browser at **[backplanerobotics.com/tracecheck](https://backplanerobotics.com/tracecheck/)**, where files never leave your device.
+
+Built by [Backplane Robotics](https://backplanerobotics.com).
+
+## Install
+
+```bash
+pip install backplane-tracecheck
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```bash
+# Write the synthetic demo recordings and contract to ./examples
+tracecheck samples
+
+tracecheck validate-contract examples/demo-contract.json
+tracecheck check examples/clean.mcap  --contract examples/demo-contract.json --out reports/clean
+tracecheck check examples/faults.mcap --contract examples/demo-contract.json --out reports/faults
+
+# Optional local browser UI (binds to 127.0.0.1 only)
+tracecheck serve --open
+```
+
+`--out` must be a new directory. Existing reports are never overwritten.
+
+**Useful options**
+
+| Option | Effect |
+|---|---|
+| `--fast` | Read only the summary section: inventory, counts, schemas and metadata in milliseconds. Timing checks (C06–C10) skip. Falls back to a full scan if the file has no usable summary. |
+| `--ignore-missing-crc` | Don't warn when the writer stored no CRCs (same as `"missing_crc": "ignore"` in the contract). Corrupt CRCs still fail. |
+| `--fail-on fail` | Exit 0 on warnings, exit 1 only on failures (the default `warn` also exits 1 on warnings). |
+| `--timeout SECONDS` | Stop a scan that takes too long. |
+| `--max-chunk-mib`, `--max-record-mib`, `--max-tracked-messages` | Raise or lower the memory safety limits (defaults: 256, 256, 20,000,000). |
+
+**Exit codes**
+- `0`: overall pass.
+- `1`: contract failures, warnings or an incomplete scan (all recorded in the report).
+- `2`: configuration, input or operational error. No report is written.
+
+## In the browser
+
+[backplanerobotics.com/tracecheck](https://backplanerobotics.com/tracecheck/) runs the same checks in a Web Worker, using a JavaScript port of the engine in [`web/src/engine/`](https://github.com/backplane-robotics/backplane-tracecheck/tree/main/web/src/engine).
+- The file is read locally in slices and never uploaded.
+- The site's Content-Security-Policy blocks connections to any other origin.
+- For the same inputs, the browser and CLI produce identical JSON reports, apart from timestamps and tool fields. The web test suite checks this.
+
+## A minimal contract
+
+```json
+{
+  "version": 1,
+  "name": "My recording requirements",
+  "topics": {
+    "/my/topic": { "required": true, "min_count": 1 }
+  }
+}
+```
+
+Start minimal, then read the report's channel inventory to see the actual schema names, encodings and fingerprints. Add only the requirements you can justify. See [docs/CONTRACT_REFERENCE.md](https://github.com/backplane-robotics/backplane-tracecheck/blob/main/docs/CONTRACT_REFERENCE.md) for every key.
+
+## The ten checks
+
+| ID | Check |
+|---|---|
+| C01 | Readable bounded MCAP scan (with CRC verification where present) |
+| C02 | Required topics contain messages |
+| C03 | Profile, schema and encoding |
+| C04 | Required file metadata |
+| C05 | Message counts |
+| C06 | Average recorded rate |
+| C07 | Sorted timestamp gaps |
+| C08 | Record-order timestamp regressions |
+| C09 | Sequence continuity |
+| C10 | Expected interval coverage |
+
+**Statuses**
+- **PASS:** the configured requirement was met.
+- **WARN:** a scoped limitation, for example message data with no CRC coverage. Default ROS 2 files with chunk CRCs pass.
+- **FAIL:** an unmet requirement or a failed scan. It does not mean the robot is unsafe.
+- **SKIPPED:** no conclusion was reached.
+
+Tracecheck does not certify safety, establish regulatory compliance, determine causality or measure transport latency.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/Scripts/activate        # Windows; use `source .venv/bin/activate` elsewhere
+pip install -e ".[dev]"
+python -m pytest
+```
+
+After an intentional behaviour change, regenerate the golden results shared by both test suites and review the diff:
+
+```bash
+tracecheck samples && python tools/make_golden.py
+```
+
+**Website** (Node 20+):
+
+```bash
+cd web
+npm install
+npm test          # engine parity tests against examples/ and the Python engine
+npm run dev       # local dev server
+npm run build     # static site in web/dist (deploy to Cloudflare Pages)
+```
+
+## Repository layout
+
+| Path | Contents |
+|---|---|
+| `src/tracecheck/` | Python package and CLI |
+| `tests/` | Engine, streaming, contract, CLI and local-server tests |
+| `examples/` | Synthetic MCAP recordings, contracts and golden results (invented data) |
+| `docs/` | Contract reference and third-party notices |
+| `tools/` | Maintenance scripts (golden-result generator) |
+| `web/` | Browser-only website and Tracecheck web app for backplanerobotics.com |
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/backplane-robotics/backplane-tracecheck/blob/main/LICENSE) and [NOTICE](https://github.com/backplane-robotics/backplane-tracecheck/blob/main/NOTICE). Copyright 2026 Backplane Robotics LLC.

backplane_tracecheck-0.2.0/docs/CONTRACT_REFERENCE.md

@@ -0,0 +1,48 @@
+# Contract reference · version 1
+
+Contracts are UTF-8 JSON objects up to 64 KiB. Keys are case-sensitive; duplicate and unknown keys are rejected. All time values are integer **nanoseconds**, not seconds or formatted dates. Numbers must be finite, nonnegative and no greater than 2^64−1. Booleans do not count as numbers. Names/keys must be 1–256 characters, except the optional profile may be empty.
+
+## Top-level keys
+
+| Key | Meaning |
+|---|---|
+| `version` | Required integer `1`. |
+| `name` | Required human-readable contract name. |
+| `profile` | Optional exact MCAP Header profile string; empty is valid. |
+| `missing_crc` | Optional `"warn"` (default) or `"ignore"`. Controls whether C01 warns when some message data has no CRC coverage (see *Scan and checksums* below). Corrupt CRCs always fail, whatever this setting. The CLI flag `--ignore-missing-crc` and the web app toggle set it to `"ignore"`. |
+| `metadata` | Optional object: metadata-record name → required key → exact string or `null` for present/nonempty. Multiple records with the same name must all satisfy each requested key. No payload fields or Channel metadata are searched. |
+| `topics` | Required object with 1–50 exact topic names, each mapping to the options below. No glob or regex matching. |
+
+## Topic options
+
+| Key | Type / behavior |
+|---|---|
+| `required` | Boolean, default true: at least one Message on any channel with this topic. Channel registration alone is insufficient. |
+| `message_encoding` | Optional exact Channel encoding, e.g. `json` or `cdr`. Does not decode or validate payloads. |
+| `schema_name`, `schema_encoding` | Optional exact Schema identity fields. A legal schema-id-zero channel fails these expectations if specified. |
+| `schema_sha256` | Optional 64 lowercase hex characters; exact Schema byte fingerprint. Whitespace/schema serialization changes affect it. |
+| `min_count`, `max_count` | Optional inclusive integer bounds, applied independently to every matching channel. |
+| `time_basis` | `log_time` (default) or `publish_time`. These are MCAP Message fields, not decoded ROS header stamps. |
+| `clock_confirmed` | Boolean, default false. All four timing checks skip unless true. User asserts the clock is interpretable for this requirement. |
+| `min_rate_hz`, `max_rate_hz` | Optional inclusive bounds for observed average `(N−1)/(last−first)` after sorting. Not windowed rate or proof of session completeness. Use interval/gap checks too. |
+| `max_gap_ns` | Optional inclusive upper limit between adjacent **sorted** timestamps. Does not include leading/trailing gaps. |
+| `check_regression` | Boolean, default false. Strict decreases in **physical record order** fail; equal timestamps pass. |
+| `sequence` | `disabled` (default) or `increment_mod32`. The latter asserts one unit-incrementing sequence source per channel, allowing wrap from 2^32−1 to 0; resets, duplicates and jumps fail. |
+| `interval_ns` | Optional inclusive `[start,end]`, with start < end, on the selected clock. All recorded timestamps must be inside; first and last must reach the respective boundaries within tolerance. |
+| `boundary_tolerance_ns` | Nonnegative integer, default 0; at most half the interval length. |
+
+Omit rate/gap/interval/sequence requirements if their assumptions are unavailable. A timestamp of zero is legal, including robot boot time. `publish_time == log_time` may indicate unavailable publication time; it is not evidence of zero latency. No cross-clock subtraction or sensor synchronization diagnosis is performed.
+
+Multiple channels sharing a topic remain separate. A required topic can be present while one of its channels fails its count/encoding/timing requirement. This conservative behavior can produce findings for a zero-message channel; adapt the contract or investigate the recording rather than assuming channels share publishers or clocks.
+
+Absence has different meanings: required missing topic fails C02, while dependent channel checks skip because there is no channel to inspect. If the overall scan fails, C02–C10 all skip and C01 fails. If no requirement applies to a check, it skips. Skipped results do not establish health.
+
+The JSON report embeds the complete contract and hashes its normalized UTF-8 JSON (`sort_keys=True`, compact separators, Unicode preserved). The contract hash identifies effective content rather than the original indentation/byte layout. Reports also include the source byte SHA-256 and tool/reader/Python versions. Contracts and schema bytes are not executed.
+
+## Scan and checksums (C01)
+
+- **Full scan** (default) streams the whole file. It computes the file SHA-256 and verifies every CRC that is present: the data-section CRC in the Data End record, each chunk's CRC of its uncompressed records, and the summary CRC in the footer. Attachment CRCs are not checked. Attachments and unknown record types are hashed but skipped.
+- **CRC coverage rule.** C01 warns about missing CRCs only when the data-section CRC is absent **and** some message data is not covered by another CRC: a chunk without a CRC, or a message outside any chunk. Default ROS 2 recordings, with chunk CRCs but no data-section CRC, therefore pass. Set `missing_crc` to `"ignore"` to suppress the warning entirely.
+- **Compression.** Chunks may be uncompressed, `zstd` or `lz4`. Decompressed output is capped at the chunk's declared uncompressed size. A mismatch, any other codec, or a chunk above the size limit fails C01.
+- **Fast mode** (`--fast` in the CLI, the toggle in the web app) reads only the header, footer and summary section (Statistics, Channel, Schema and indexed Metadata records) and checks the summary CRC. C01–C05 run on that information; C06–C10 skip because they need every timestamp. If the summary is missing or lacks Statistics, the scan falls back to a full scan and records `fast_mode_fallback` in the report. In fast mode `source.sha256` is `null`.
+- **Limits.** Defaults: 256 MiB per record, uncompressed chunk and summary section; 20 million tracked timestamps for sorted-gap checks; 10,000 schemas/channels/metadata records. Exceeding a limit fails C01 with an explanation, rather than exhausting memory. The CLI exposes `--max-chunk-mib`, `--max-record-mib`, `--max-tracked-messages` and `--timeout`. There is no overall file-size cap.