Address clippy allow-list (pedantic + restriction) #256

Description

Strict clippy (pedantic + restriction) was enabled in # (commit 1c3bf19) along with a categorized allow-list in Cargo.toml that captures every currently-failing lint with a count and rationale. This issue tracks incrementally factoring out the remaining allows.

The defensive-coding category was completed in the enabling PR. The remaining categories below are TODOs — pick one, remove its allow, fix the call sites, re-run clippy, repeat.

Counts (from baseline)

After enabling lints, the production-code violation totals were captured in Cargo.toml. Refresh with:

cargo clippy --workspace --all-targets --all-features --message-format=json \
  | jq -r 'select(.reason=="compiler-message") | .message.code.code' \
  | sort | uniq -c | sort -rn

(Clippy stops emitting after a per-file threshold, so iterate by silencing the noisiest, re-running, and adding the next wave.)

Tracks

• Documentation (~302 sites): missing_docs_in_private_items (275), missing_panics_doc (10), missing_inline_in_public_items (9), missing_errors_doc (4), missing_fields_in_debug (4), doc_markdown (4). Mostly mechanical: write doc comments and `# Errors` / `# Panics` sections.
• API design (~80 valuable sites): impl_trait_in_params (26 explicit-generics conversions), return_self_not_must_use (18 builder `#[must_use]`), needless_pass_by_value (16 case-by-case), ref_patterns (11 → `&foo` matching), wildcard_enum_match_arm (7 explicit arms), rc_buffer (4 `Arc<Vec>` → `Arc<[T]>`), unnecessary_wraps (4), renamed_function_params (4), same_name_method (2 inherent-vs-trait shadowing), mutex_atomic (1 → `AtomicBool`), clone_on_ref_ptr (1).
• Imports / paths (~40 sites): absolute_paths (19), unused_trait_names (6), non_std_lazy_statics (6 — quick win, swap `once_cell::Lazy` → `std::sync::LazyLock` since MSRV is Rust 1.91), std_instead_of_alloc (6).
• Output / diagnostics (~26 sites): print_stderr (16), print_stdout (8), unnecessary_debug_formatting (2). Route CLI output through `log::info!`/`log::error!`.
• Style / formatting (~700 sites, mostly intentional): dominated by implicit_return (375, intentional — keep), arbitrary_source_item_ordering (165, cosmetic), module_name_repetitions (78), min_ident_chars (54), single_call_fn (37). Likely keep most allowed; revisit only the small ones.
• Attributes (~8 sites): allow_attributes_without_reason (5), allow_attributes (3) — add `, reason = "..."` to existing `#[allow(...)]` sites.
• Decided not to enforce (document the decision in `Cargo.toml` and resolve): exhaustive_structs (108) and exhaustive_enums (18) — blanket `#[non_exhaustive]` would break user code (no field-syntax construction, no exhaustive match); apply per-type only where genuinely planned. must_use_candidate (117) — most are getters where ignoring the value is impossible. missing_trait_methods (20) — relying on default trait methods is fine.

Done when

• Each track above is either factored out (allow removed from `Cargo.toml`) or explicitly re-justified as intentional with a comment in `Cargo.toml`.
• `cargo clippy --workspace --all-targets --all-features -- -D warnings` continues to pass.
• The allow-list comment header in `Cargo.toml` accurately reflects the current state (counts and intent).

Affected area

CI / Tooling