[carloshvp]

What

Use rfc8785.dumps() in all four hashing examples in the tool-catalog authoring tutorial, and hash the returned bytes directly. Explain the JCS serialization requirement for definition and catalog hashes.

Why

The existing json.dumps(..., sort_keys=True, ensure_ascii=True) examples produce different bytes from RFC 8785 for non-ASCII text and some numbers. With the runtime correction in #838, those examples can produce a rejected definition hash or catalog pin.

Merge dependency: merge #838 (or an equivalent catalog canonicalization fix) first. Current main still uses the previous catalog serialization, so these updated examples are validated against #838 at f2e3c2ddf74202ce0136b742f50dcefb2b520d66. This patch retains the existing tool_name sorting behavior; it does not resolve the separate ordering question on #838.

Security impact

Documentation only. The examples compute hashes using the canonical bytes expected by the runtime correction; runtime validation and enforcement are unchanged.

Test plan

• pytest passes
• ruff check src/ tests/ passes
• mypy src/ passes (77 source files)
• bandit -r src/ -c pyproject.toml -q passes
• Manual test performed: execute all four updated snippets against fix(trace,catalog): canonicalize TRACE claims and catalog hashes with RFC 8785 JCS (#837) #838 using a catalog containing Résumé records and the numeric value 1e-7; verify matching definition and catalog hashes and successful load_catalog(expected_hash=...). Confirm that the old definition hash and old catalog pin are rejected for the same fixture.

On main plus this documentation patch, pytest tests/unit/ -q --tb=short reported 2,532 passed, 21 skipped, 10 failed, and 48 errors. Nine failures and all 48 errors came from socket creation/binding denied by the network-disabled sandbox. The remaining failure was the distribution smoke test because cmcp-runtime package metadata was not installed in the source-path test environment. A fully passing hosted test run remains required before merge.

git diff --check passes. The documentation site was not built locally.

DCO sign-off

• I certify that I wrote or have the right to submit this contribution, and I agree to the Developer Certificate of Origin (https://developercertificate.org).

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!