docs(rsync_io): audit SSH socketpair vs anonymous pipes for stdio transport (#1938)

[oferchen]

Closes #1938.

Summary

Formalizes the SSH stdio transport audit at docs/audits/ssh-socketpair-vs-pipes.md under tracker #1938. Consolidates prior #1686 working notes (PR #3438), the io_uring boundary documented for #1858 (PR #3418), and the stderr socketpair shipped under #1689 (PR #3383). Restructures the document into the formal seven-section layout (summary, upstream reference, current implementation, trade-offs, decision matrix, recommendation, implementation notes) plus findings and references.

Recommends keeping anonymous pipes for the SSH wire and not pursuing the socketpair migration. The decisive argument is that splice(2) / vmsplice(2) require one of the two FDs to be a pipe; oc-rsync's zero-copy roadmap in #1860 depends on the wire being a pipe so the file<->wire splice path remains direct. A socketpair-backed wire would force a double-splice through an intermediate user-space pipe(2), eliminating the zero-copy benefit. The "unified poll FD" advantage of socketpair only matters inside an event loop, and the async-transport refactor (#2068, #1655) consolidates readiness tracking regardless of primitive.

The audit closes the two pending follow-ups in this tracker family:

• Fix missing imports in daemon tests #1687 (prototype SSH subprocess using socketpair for bidirectional I/O) - do not implement, justified by the splice eligibility argument and absence of measured backpressure stalls on pipes.
• Allow cross-compile workflow entries to be disabled #1902 (verify SSH socketpair vs anonymous-pipe wire claim against rsync_io source) - verified: crates/rsync_io/src/ssh/builder.rs:300-301 uses Stdio::piped() for stdin and stdout (anonymous pipes); upstream uses socketpair(AF_UNIX, SOCK_STREAM, 0) via util1.c::fd_pair called from pipe.c::piped_child. The divergence is intentional.

What stays on the roadmap (untouched by this audit):

• Gate alternatives registration and centralize tarball target metadata #1859 io_uring on pipe FDs (docs/audits/iouring-pipe-stdio.md).
• Restrict limiter test-only re-export #1860 splice/vmsplice for SSH stdio (docs/audits/splice-ssh-stdio.md).
• Avoid checksum comparisons when timestamps match #2068 async SSH transport (docs/audits/async-ssh-transport.md).

Test plan

• No code changes; documentation-only PR.
• All upstream citations re-verified against target/interop/upstream-src/rsync-3.4.1/ source files.
• All crates/rsync_io/src/ssh/ citations verified against worktree line numbers.
• No em-dashes; conventional docs: prefix; branch name docs/ssh-socketpair-1938.
• CI: rustdoc renders without broken intra-doc links.
• CI: fmt+clippy (no code changes, expected to pass).
• CI: nextest (stable) (no code changes, expected to pass).
• CI: Windows / macOS / Linux musl (no code changes, expected to pass).