docs(design): differential fuzzer for filter rules vs upstream rsync

[oferchen]

Summary

Adds a 521-line design note for a differential fuzzing harness that compares oc-rsync's filter-rule evaluation byte-for-byte against upstream rsync 3.4.1 over a randomized cross-product of (filter-rule-set, on-disk tree, transfer mode).

Key sections

• Problem statement: 12 interacting filter features, gap between static goldens and unknown divergences.
• Scope: CLI `--filter`/`--exclude`/`--include`/`--exclude-from`/`--include-from`, per-directory `.rsync-filter`, and daemon `rsyncd.conf` directives at `crates/daemon/src/daemon/sections/module_access/helpers.rs:223` (Serialize branding env override tests #1366, Add unit coverage for metadata and exit code helpers #1696).
• Mutation strategies: grammar-based pattern generation, bounded random trees (10K-entry cap), per-directory merge-file mutation.
• Equivalence oracle: `--dry-run --itemize-changes` set comparison against upstream binary; inner-ring direct calls into `crates/filters/src/compiled/rule.rs::CompiledRule::matches` and `crates/filters/src/decision.rs::decision`.
• Special seeds: trailing-slash semantics, `**` vs `*` recursion, re-include after broad exclude, side-applicability modifiers, merge-file edge cases, path-escaping CVE-class inputs from Propagate dir-merge modifiers to nested filters #1062.
• Implementation site: extend existing `crates/filters/fuzz/` rather than spin up a new crate.
• Daemon-server differential mode reusing `scripts/rsync-interop-server.sh`, with optional tcpdump capture (Align skip-copy logic with rsync quick check #2075).
• Resource budget: 1K iters per PR, 100K nightly, 10K-file tree cap, 90 s wall-clock cap per PR.
• Failure handling: `cargo fuzz tmin` shrink, regression-test extraction artefact upload (no auto-commit).
• CI activation: opt-in workflow mirroring the protocol fuzzer harness (Handle --ignore-missing-args in local copy engine #1193).
• Risk register: encoding, locale, fnmatch divergence, tempdir leakage, quick-check flakiness, symlink loops.
• Interaction with Propagate dir-merge modifiers to nested filters #1062, Align decimal --bwlimit rounding with upstream behaviour #1292, Add unit coverage for metadata and exit code helpers #1696, Align skip-copy logic with rsync quick check #2075 enumerated.
• Follow-up TODOs listed but not added to the persistent tracking list.

Wire-compat invariants confirmed

• Filter evaluation is read-only with respect to wire bytes; harness uses `--dry-run` exclusively.
• No CompiledRule field, FilterSet API, or merge-file parser entry point is mutated.
• Production code under `crates/filters/src/`, `crates/daemon/src/`, `crates/transfer/src/generator/filters.rs`, and `crates/core/src/client/remote/flags.rs` remains untouched.
• The harness is purely additive; only new files under `crates/filters/fuzz/` and `.github/workflows/` are envisioned for the implementation PRs.

Test plan

• CI fmt+clippy pass (docs-only change; no Rust touched).
• Markdown renders cleanly on GitHub (verified locally).
• Cross-references to existing files resolve (`crates/filters/src/compiled/mod.rs`, `crates/filters/src/merge/parse.rs`, `crates/daemon/src/daemon/sections/module_access/helpers.rs`, `crates/filters/fuzz/Cargo.toml`).
• No production code modified; `git log origin/master..HEAD --stat` shows exactly one file added.