Summary

Comprehensive code quality review and polish pass across the entire codebase in preparation for initial release. This addresses accumulated technical debt, documentation drift, dead code, and several latent bugs discovered during systematic review.

Motivation

As the project approaches release readiness, a thorough audit revealed:

• 8 bugs ranging from data corruption (UDS frame corruption on partial writes) to incorrect system metadata in output
• 3 dead dependencies inflating compile times and dependency tree
• Dead code and stale development scaffolding left from the blocking mode implementation
• Significant documentation drift where docs described non-existent features or used wrong CLI flags
• Inconsistent logging (println! in tests instead of tracing)

None of these issues would be caught by normal CI — they require manual review and domain knowledge of the codebase's intended behavior.

Changes

Bug Fixes (8)

• Frame corruption in blocking UDS — writev partial-write fallback used incorrect offset calculation (written.saturating_sub(4)) that could corrupt message framing when fewer than 4 bytes were written
• Duration parsing truncation — parse_duration_micros silently truncated fractional values (e.g. "1.5ms" became "1ms") due to as u64 cast
• SHM-direct OOB read — No validation of payload_len read from shared memory before copy_nonoverlapping, enabling potential out-of-bounds reads
• SHM-direct timestamp accuracy — receive_blocking_timed captured a new timestamp instead of using the already-captured msg.receive_time_ns, adding measurement noise
• SHM blocking zero-length frames — read_data_blocking did not reject data_len == 0 (inconsistent with other transports)
• TCP server panic — panic! in multi-server accept loop when try_clone() fails, crashing the entire server
• Hardcoded system metadata — get_memory_gb() returned 16.0 instead of reading /proc/meminfo; rust_version was hardcoded instead of using env!(CARGO_PKG_RUST_VERSION)

Dependency Cleanup (4)

• Remove dead dependencies: statistics, crossbeam, rand (not imported anywhere)
• Remove unused nix "time" feature (code uses libc::clock_gettime directly)
• Fix placeholder repository URL → actual redhat-performance/rusty-comms
• Remove dead docs.rs documentation URL (crate not published on crates.io)

Code Cleanup (5)

• Remove dead current_timestamp_ns() function from utils.rs
• Consolidate identical Message::new/new_for_blocking into inline alias
• Remove dead if true { ... } scaffolding in blocking round-trip loop
• Move misplaced test into mod tests block
• Replace all println! with tracing::trace! in backpressure tests

Documentation Fixes (8)

• Fix incorrect clock source, readiness signal, and CLI flag references in README
• Fix stale "no streaming support" comments (streaming is implemented)
• Fix "zero-copy serialization" and "async I/O throughout" claims in lib.rs
• Fix "JIT compilation" warmup comment (Rust is AOT compiled)
• Rewrite logging.rs module docs to match actual exports
• Fix SHM-direct docs (repr attribute, max payload size constant)
• Mark archived blocking plan as HISTORICAL/COMPLETE
• Fix dashboard README example commands to use correct CLI flags

Performance (1)

• Use .with_context(|| format!(...)) for lazy string allocation in hot path

Validation

• All 476 tests passing (386 unit + 48 integration + 42 doc tests)
• Zero clippy warnings (-D warnings)
• cargo fmt clean
• cargo audit clean (known advisories only: bincode unmaintained, anyhow unsoundness, transitive rand)
• MSRV check passing (Rust 1.70)
• Release build successful

Scope

21 files changed, 241 insertions, 291 deletions (net -50 lines).

Branch: chore/release-polish

Related Issues

This review also identified 15 larger architectural issues that are beyond polish scope, filed separately:

• Async multi-threaded benchmark aggregation produces incorrect metrics #120 through SHM_COMPARISON.md omits async ring buffer, has wrong round-trip scope #134 (multi-threaded aggregation, server flag forwarding, metrics correctness, documentation rewrites, etc.)