docs(core): add compile-checked doctests for type-compatibility rules

[phil-opp]

Issue

libraries/core/src/types.rs exposes two public type-compatibility helpers whose behavior is subtle but was only documented in prose:

• types_match — an unparameterized side is a wildcard, and parameter conflicts are only rejected on shared keys (disjoint keys never conflict).
• CompatibilityGraph::is_compatible — the universal * -> std/core/v1/Bytes sink, same-base wildcard matching, and a depth-3 bound on transitive widening chains (BFS).

None of these rules were exercised by a compile-checked doctest, so a refactor could silently change them without any in-file test catching it. Sibling public APIs in the crate (e.g. config::ByteSize) already carry doctests.

Fix

Add # Examples doctests to both functions that pin the intended semantics:

• types_match: identical match, unparameterized wildcard, disjoint-key compatibility, shared-key conflict, different-base mismatch.
• is_compatible: Bytes sink, one-hop and two-hop (UInt8 -> UInt32 -> UInt64) built-in widening, same-base wildcard, and a four-rule chain demonstrating that three hops are reachable but four are beyond the depth limit.

Documentation only — no behavior change.

Validation

cargo test -p dora-core --doc      # 4 passed (2 new)
cargo clippy -p dora-core -- -D warnings
cargo fmt --all -- --check

---

⚠️ This is a machine-generated PR authored by Claude (Claude Code) as part of an automated codebase review. Each finding was verified by hand against origin/main before opening. Please review carefully before merging.

🤖 Generated with Claude Code

---

Generated by Claude Code

[trunk-io]

Merging to main in this repository is managed by Trunk.

• To merge this pull request, check the box to the left or comment /trunk merge below.

After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here

[phil-opp]

Automated codebase-review run — summary

This is the summary for a batch of machine-generated PRs from one automated review pass over origin/main (a8d3bbf). Each finding was verified by hand against current origin/main, checked against prior runs' open PRs for duplicates, and each branch was built off a fresh origin/main.

PRs opened, by category

Correctness

• fix(daemon): compute dora top disk-I/O rate from the real sampling window #3109 — fix(daemon): dora top disk-I/O rate divided per-refresh byte deltas by a hard-coded 2 s constant, over-reporting on the first sample (no baseline → total-since-start) and after any skipped/catch-up cycle (~2×). Now divides by the measured window and suppresses the rate when there is no valid baseline.
• fix(message): don't mislabel signal 23 as SIGURG on macOS/BSD daemon hosts #3110 — fix(message): NodeError Display named signal 23 SIGURG from a Linux-only table, but signal 23 is SIGIO on macOS/BSD — so a signal-23 death on a macOS/BSD daemon host was mislabeled. Now named per target OS.
• fix(node): return an error instead of panicking on a zero-field JSON schema #3112 — fix(node): both JSON→Arrow readers ended with batch.column(0), which panics on a zero-field schema (reachable via a caller/inference-supplied empty schema). Now returns an error via a shared first_column_data helper.

Documentation

• docs(core): add compile-checked doctests for type-compatibility rules #3108 — docs(core): compile-checked doctests for types_match / CompatibilityGraph::is_compatible, pinning the wildcard/disjoint-key parameter rules, the * -> Bytes sink, and the depth-3 BFS bound (this PR).
• docs(cli): correct the dora top note about what each metric column means #3111 — docs(cli): the dora top note claimed all columns are "averaged over the last refresh period", but NET TX/RX and RESTARTS are cumulative, QUEUE/MEMORY are point-in-time, and only I/O is a per-interval rate. Reworded per-column.

Rejected / deferred findings (with reasons)

• SHM copy-fallback over-allocation guard in zenoh_publish — duplicate of open PR fix(node): guard the SHM copy-fallback against an over-allocated buffer #3073, which already guards that exact site.
• MAVLink MavlinkArrow::schema() rebuilt per encode (perf) — real per-frame allocation, but a clean fix means changing the public trait method signature across ~17 impls; too large/API-breaking for an automated PR, better as a focused human change.
• Redundant bincode::serialize(metadata) on the schema-less zenoh send path (perf) — genuine micro-opt, but it sits on the single hottest, most safety-commented send function; restructuring risks the carefully-ordered fallback logic for one avoided small-metadata serialize.
• ros2-bridge per-element string/wstring size cap in sequence.rs (hardening) — the element-count cap already bounds growth and per-element impact is bounded by serde's lazy decode + buffer exhaustion; too weak to act on.
• edit_distance allocates an O(n·m) matrix per candidate in TypeRegistry::suggest (efficiency) — cold path (only on an already-failed type lookup); deprioritized per "hot paths over cold".
• Derive signal names from libc constants (raised by the /simplify altitude pass on fix(message): don't mislabel signal 23 as SIGURG on macOS/BSD daemon hosts #3110) — a deeper fix than the #[cfg] arms, and libc is already a dependency, but it broadens scope to all divergent signals and can't be cross-platform-compile-verified (const-alias / missing-const risks on macOS/Windows) in this environment; left as a follow-up. fix(message): don't mislabel signal 23 as SIGURG on macOS/BSD daemon hosts #3110's fix still corrects the actual mislabel.

Validation (once, on the combined diff of all 5 PRs)

• cargo fmt --all -- --check — clean (toolchain 1.97.1, matching CI).
• cargo clippy --all (excl. Python packages) -- -D warnings — clean.
• cargo test --all (excl. Python packages, dora-examples, and dora-ros2-bridge*) — 39 test binaries pass. The only failures are 2 zenoh_schema_cache integration tests, both failing at Session::open() with tcp/[::]:0: Address family not supported — the sandbox has no IPv6. That test file is untouched by this diff, so the failure is environmental, not a regression.
• /review and /simplify gates run on the combined diff; both surfaced findings were addressed (the disk-I/O panic-reset desync and the JSON first-column duplication) or documented as deferred above.
• Environment notes: dora-ros2-bridge* was excluded from the test run because it needs a ROS2 distro (AMENT_PREFIX_PATH) and its example/test binaries exhausted the sandbox's fixed disk allowance during linking (ld SIGBUS); it is unrelated to this diff.

Each PR is a draft and clearly attributed to Claude (Claude Code). Please review carefully before merging — these are machine-generated.

---

Generated by Claude Code

[phil-opp]

Reviewed the doctests against the actual implementations in libraries/core/src/types.rs — no issues found; all assertions match the real behavior:

• types_match: identical-match, unparameterized wildcard, disjoint-key compatibility, shared-key conflict, and different-base mismatch all reflect the parse-and-compare logic exactly.
• is_compatible: the Bytes sink, one-/two-hop builtin widening, same-base wildcard, and the 4-rule chain all correctly demonstrate the depth-3 BFS bound (the a→e case is unreachable because d is only dequeued at depth 3, where depth >= 3 skips expansion before reaching e).

The API paths (dora_core::types::{types_match, CompatibilityGraph, TypeRule}) resolve correctly, and the doctests genuinely exercise the conversions rather than just compiling. Documentation-only, no behavior change.

---

🤖 Automated review by Claude (Claude Code). This review was generated fully automatically with no human in the loop and has not been vetted by a maintainer — treat it as advisory.

---

Generated by Claude Code