.gitea/workflows/ci.yaml

@@ -49,6 +49,47 @@ jobs:
         if: github.event_name == 'push'
         run: python3 -m pytest tests/integration/ -n 4 --dist=load -m "not setpriv" --durations=25 --tb=short -q
 
+  # Differential rsync-parity gate: runs real rsync 3.4.1 and FastSync over the
+  # same corpora and compares destinations + normalized output.  The fast subset
+  # guards the ✅ surface on every PR; the full set (with FASTSYNC_PARITY_STRICT
+  # so a fixed caveat must be removed from the allowlist) burns the documented
+  # ⚠️/❌ residuals down on push.  See tests/integration/README.md.
+  parity-fast:
+    runs-on: ubuntu-latest
+    container: gitea.tap-tap.win/taptap/fastsync-ci:v11
+    needs: lint
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Configure
+        run: cmake -B build -S . -DSTRICT_WARNINGS=ON
+
+      - name: Build
+        run: cmake --build build -j$(nproc)
+
+      - name: Differential parity (fast subset)
+        run: python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity_ci -q
+
+  parity-full:
+    runs-on: ubuntu-latest
+    container: gitea.tap-tap.win/taptap/fastsync-ci:v11
+    needs: lint
+    if: github.event_name == 'push'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Configure
+        run: cmake -B build -S . -DSTRICT_WARNINGS=ON
+
+      - name: Build
+        run: cmake --build build -j$(nproc)
+
+      - name: Differential parity (full set)
+        run: FASTSYNC_PARITY_STRICT=1 python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity -q
+
   sanitizers:
     runs-on: ubuntu-latest
     container: gitea.tap-tap.win/taptap/fastsync-ci:v11

AGENTS.md

@@ -56,8 +56,15 @@ cmake -B build -S . && cmake --build build -j$(nproc)
 ./build/tests                # unit tests
 python3 -m pytest tests/integration/ -n 4 --dist=load -m "not setpriv"   # full integration suite (CI excludes env-dependent privilege tests)
 python3 -m pytest tests/integration/ -n 4 --dist=load -m ci   # PR-gate subset only
+
+# Differential rsync-parity gate (real rsync 3.4.1 vs FastSync)
+python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity_ci  # fast PR subset
+python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity     # full set
 ```
 
+See `tests/integration/README.md` for the differential parity gate and its
+`parity_caveats.py` allowlist (the residual burn-down mechanism).
+
 ## CI Workflow — Waiting for Results
 
 When running the CI workflow via `tea` (the task execution agent), always set a sufficient timeout (e.g., 600000ms) to allow CI to finish. After CI completes, check the results yourself — do not assume success. Monitor CI status via the Gitea API (see below) or `tea actions`, then inspect logs on failure.

HANDOFF.md

@@ -53,11 +53,28 @@
    over daemon/TCP (no argv channel in FastSync's binary config handshake;
    rsync-daemon differential pins the rsync behavior) and receiver-side
    `protect`/`risk` re-derivation for destination-only entries (would need a
-   receiver filter engine; differential pins the divergence). Matrix now
-   **109 ✅ / 21 ⚠️ / 26 ❌**. New `tests/integration/test_option_parity.py`
+   receiver filter engine; differential pins the divergence). The options pass
+   stands at **110 ✅ / 21 ⚠️ / 26 ❌**. New `tests/integration/test_option_parity.py`
    holds the rsync differentials (bwlimit parse+rate, info lines, real-setpriv
    `--ignore-errors`, rsync-daemon `-M`, filter-protect pin).
 
+9. **rsync-parity-fs pass** on `fix/parity-fs` (no wire change of its own; integrated
+   on top of the 2.27.0 options wave): recursive transfers now recreate empty source directories (and
+   `-m/--prune-empty-dirs` still suppresses them), a directory entry replaces a
+   blocking destination regular file, and `-R --no-implied-dirs --files-from`
+   places a listed file under a missing implied parent with default attributes
+   instead of refusing (real rsync 3.4.1 parity, differential-tested). `--iconv`
+   now reproduces rsync's push direction (destination charset = the spec's REMOTE
+   half; a server `--iconv` overrides), and `-T/--temp-dir` relative semantics are
+   confirmed identical while the absolute-path confinement is a deliberate
+   divergence. The basis-dir options, `--delay-updates`, `--fuzzy` and `--dry-run`
+   were reclassified to ❌ after a differential test reproduced each exact residual
+   (basis content verification, fixed staging-name collision, heuristic size
+   window, and dry-run would-delete over-report). Differential-gate allowlist
+   entries `min_size`/`empty_dirs_recursive`/`dirs_plain` were removed. The
+   integrated stats+options+fs branch stands at **112 ✅ / 12 ⚠️ / 33 ❌ = 157**;
+   full suite + ASan + clang-format + cppcheck clean.
+
 ## Next steps
 1. **Merge PR #284** (`dev` -> `main`) once reviewed (protected branch).
 2. **Deferred security items** (documented, not implemented):

RSYNC_COMPAT.md

@@ -6,10 +6,10 @@ This document maps rsync's full feature set to FastSync's current implementation
 
 | Status | Count | Description |
 |--------|-------|-------------|
-| ✅ Parity | 109 | Reproduces rsync's semantics for this option's scope |
-| ⚠️ Caveat | 21 | Wired and tested, but carries a documented behavioral difference from rsync (named in the row and/or the wave notes) |
-| ❌ Divergent | 26 | Rejected, an accepted no-op, deliberately non-rsync (native config/auth/batch, privileged namespaces, safe-subset privilege), or impossible on any portable filesystem call |
-| **Total** | **156** | One row per rsync option/feature group; a row may name several spellings |
+| ✅ Parity | 112 | Reproduces rsync's semantics for this option's scope |
+| ⚠️ Caveat | 12 | Wired and tested, but carries a documented behavioral difference from rsync (named in the row and/or the wave notes) |
+| ❌ Divergent | 33 | Rejected, an accepted no-op, deliberately non-rsync (native config/auth/batch, privileged namespaces, safe-subset privilege), or impossible on any portable filesystem call |
+| **Total** | **157** | One row per rsync option/feature group; a row may name several spellings |
 
 This matrix reports honest rsync parity, not "implemented" as a synonym for
 "parsed". A ✅ row matches rsync for the option's scope. A ⚠️ row is real and
@@ -32,8 +32,9 @@ that map to a FastSync event (`name`, `flist`, `del`, `remove`, `nonreg`,
 genuinely non-interoperable residuals are reclassified divergent (`-M` over a
 daemon/TCP connection, which FastSync's binary config handshake has no argv
 channel for, and receiver-side `protect`/`risk` re-derivation for
-destination-only entries, which would need a receiver filter engine). That moves
-the matrix to **109 ✅ / 21 ⚠️ / 26 ❌ = 156**.
+destination-only entries, which would need a receiver filter engine). After the
+combined `fix/parity-stats` + `fix/parity-options` + `fix/parity-fs` passes the
+matrix is **112 ✅ / 12 ⚠️ / 33 ❌ = 157**.
 
 **Parity completion wave (protocol 2.23.0 → 2.26.0).** This wave closed the
 remaining gaps the rsync-parity wave left open (delete timing, wire counters and
@@ -115,8 +116,8 @@ Every one of those has an entry below with its remaining caveats.
 |------|-------------------|-----------------|-------|
 | `-r`, `--recursive` | Recurse into directories | ✅ Parity | Default behavior |
 | `-R`, `--relative` | Use relative path names | ✅ Parity | Protocol 2.26.0 implements rsync's general `-R` path semantics: without a cut the source argument is mirrored in full below the destination root; a `/./` cut in the source argument (`src/./foo`) makes everything after the cut the destination prefix, so the layout matches rsync's relative reconstruction; and `--files-from` entries land under their bare relative path. The delete manifest derives from the sent (relative) paths and is scoped to the transferred prefix subtree, so `--delete` cannot remove destination content outside that prefix (a blocker fix). Works single-threaded and under `-j`/`--threads` |
-| `--no-implied-dirs` | Don't send implied dirs with -R | ✅ Parity | With `-R`, rsync creates the ancestor directories implied by a listed path and, with `--no-implied-dirs`, omits them from the transfer so the destination directories keep the destination's own mode/mtime. Protocol 2.26.0 matches this: the implied-dir walk applies the transfer's per-attribute metadata only to explicitly transferred directories, and a differential test verifies the modes and mtimes of the implied parents against rsync with and without the flag. Works single-threaded and under `-j`/`--threads` |
-| `-d`, `--dirs`, `--old-dirs`, `--old-d` | Transfer dirs without recursing | ⚠️ Caveat | Protocol 2.26.0 implements rsync's one-level `-d` listing for `dir`, `dir/` and `.`: the source's immediate contents are transferred (files with content, directories as explicit entries), matching rsync's destination tree in a differential test. `--dirs --files-from` transfers exactly the listed items — a listed directory is created empty and a listed file with content — under the same `-R` layout rules. Directory entries cross as `STATUS_MKDIR` and appear in the delete manifest, so `--delete` prunes correctly and an empty listed directory survives. Directory times are applied at the end of the transfer; modes/ownership follow the per-attribute policy. **Remaining divergence:** a plain recursive `-a` scan still does not create empty source directories (directory entries are record-only unless `-d`/`--files-from` explicitly lists a directory), and under `--delay-updates` directories are created immediately while only regular files are staged (see the recursive-empty-directory residual in the completion-wave section) |
+| `--no-implied-dirs` | Don't send implied dirs with -R | ✅ Parity | With `-R`, rsync creates the ancestor directories implied by a listed path and, with `--no-implied-dirs`, omits their attributes from the transfer so they keep the destination's own state (or are created with default attributes when absent). Protocol 2.26.0 matches this: without `--files-from` the implied-dir walk applies per-attribute metadata only to explicitly transferred directories, and with `-R --files-from` a listed file whose parent is not itself listed is placed normally — the missing implied parent is created with default attributes (not the source's) and the file transfers with `rc 0`, exactly like rsync 3.4.1 (a differential test verifies the modes and mtimes with and without the flag). Works single-threaded and under `-j`/`--threads` |
+| `-d`, `--dirs`, `--old-dirs`, `--old-d` | Transfer dirs without recursing | ✅ Parity | Protocol 2.26.0 implements rsync's one-level `-d` listing for `dir`, `dir/` and `.`: the source's immediate contents are transferred (files with content, directories as explicit entries), matching rsync's destination tree in a differential test. `--dirs --files-from` transfers exactly the listed items — a listed directory is created empty and a listed file with content — under the same `-R` layout rules. A plain recursive scan also recreates empty source directories now: the scanner emits a payload-less directory entry (with metadata) for every traversed directory that produced no transferred or descended child, unless `-m/--prune-empty-dirs` suppresses it or the run is `--files-from`/`--list-only` (a directory emptied by filtering is recreated too, matching rsync). Directory entries cross as `STATUS_MKDIR` and appear in the delete manifest, so `--delete` prunes correctly and an empty listed directory survives; an incoming directory replaces a destination regular file (rsync removes the non-directory and creates the directory), verified differentially. Directory times are applied at the end of the transfer; modes/ownership follow the per-attribute policy. Under `--delay-updates` directories are created immediately while only regular files are staged, exactly as rsync does |
 | `--mkpath` | Create missing path components | ✅ Parity | Wire option (client → server). At connection start the server creates the client's destination root directory (and any missing leading components below its own authorized root) when `--mkpath` is set, failing the connection cleanly if it cannot. Without `--mkpath` a destination root that does not exist yet is rejected up front (rsync semantics), so the flag is the only way to transfer into a not-yet-created destination directory. Creation is confined by the same secure mkdir walk as file writes (`O_NOFOLLOW`, no `..`) |
 | `--inc-recursive`, `--no-inc-recursive` | Incremental recursion mode | ❌ Divergent | rsync's man-page-only scanning-mode switch (and its short aliases). FastSync always performs a single full recursive scan, so both spellings are rejected as unknown options rather than accepted as a no-op; there is no incremental-recursion engine to toggle. A genuine implementation would be a scan-architecture change with no benefit for FastSync's push model |
 
@@ -136,12 +137,12 @@ Every one of those has an entry below with its remaining caveats.
 
 | Flag | Rsync Description | FastSync Status | Notes |
 |------|-------------------|-----------------|-------|
-| `-n`, `--dry-run` | Trial run with no changes | ⚠️ Caveat | Server-contacting since protocol 2.21.0. The routing predicate `dry_run_targets_server()` selects the server-contacting path for any target a real run would reach over the wire (SSH, daemon `host::module`, explicit `--server-host`/`--server-port`, TLS, source-bind `--address`); the client handshakes with the receiver, which runs the normal read-only per-file check and answers `STATUS_DRY_RUN_TRANSFER`/`STATUS_OK` without mutating anything. Protocol 2.25.0 also reports would-delete lines: with `--delete` the receiver's `STATUS_STATS` carries the extras it would have removed and the client prints rsync-style `*deleting` lines (sequential and `--threads`; control bytes escaped). Dry-run never deletes. **Remaining divergences:** the `*deleting` line ordering can differ from rsync's delete-during walk, and a filtered dry-run can over-report what the real commit would remove |
+| `-n`, `--dry-run` | Trial run with no changes | ❌ Divergent | Server-contacting since protocol 2.21.0. The routing predicate `dry_run_targets_server()` selects the server-contacting path for any target a real run would reach over the wire (SSH, daemon `host::module`, explicit `--server-host`/`--server-port`, TLS, source-bind `--address`); the client handshakes with the receiver, which runs the normal read-only per-file check and answers `STATUS_DRY_RUN_TRANSFER`/`STATUS_OK` without mutating anything. Protocol 2.25.0 also reports would-delete lines: with `--delete` the receiver's `STATUS_STATS` carries the extras it would have removed and the client prints rsync-style `*deleting` lines (sequential and `--threads`; control bytes escaped). Dry-run never deletes. **Reclassified Divergent (differential evidence):** the would-delete report over-reports — it includes the file that is merely being updated (the receiver's extras walk does not see the would-be-transferred file in its keep-set) and, unlike rsync, also lists an excluded-but-protected extra under `--exclude`, and its line ordering differs from rsync's delete-during walk (`test_dry_run_delete_lines_over_report_residual`). A real run remains correct; only the dry-run report diverges |
 | `-b`, `--backup` | Make backups of overwritten files | ✅ Parity | Backup before overwrite |
 | `--backup-dir=DIR` | Backup directory hierarchy | ✅ Parity | `backup_dir` config field |
 | `--suffix=SUFFIX` | Backup suffix (default ~) | ✅ Parity | `suffix` config field |
-| `--delay-updates` | Put updated files in place at end | ⚠️ Caveat | Successfully received files are staged under a private 0700 `.fastsync-stage` dir inside the receive root and atomically renamed into their final destinations only after the whole transfer (manifest/delete handling included) succeeds, just before the success/outcome frame is sent. The delete walker deliberately skips the staging dir at the receive root, so `--delete` removes genuine extras but never the staged files (deletion runs before publication; rsync's delete-after ordering is not implemented). `--existing`/`--ignore-existing`/`--update` decide against the final destination path at stage time; `--backup` moves the old file aside at publication, and **`--force` is honored at publication** (protocol 2.23.0): a staged regular file or symlink may replace a destination directory that blocks it. Incompatible with `--inplace` and with `--backup-dir=.fastsync-stage` (the internal staging name is reserved; both are rejected). The staging dir name is fixed, so two simultaneous delayed transfers to the same destination root are serialized with an exclusive advisory lock held for the whole transfer: the second session fails cleanly instead of corrupting the first. Aborting or failing before publication installs nothing and removes the staging tree; a crash between stage and publish leaves staged leftovers that the next delayed run wipes at start (process death releases the lock). A stage→publish failure aborts the transfer (best-effort cleanup of the not-yet-published staged files; already-published files are not rolled back). Works in single-threaded and `-j`/`--threads` modes |
-| `-T`, `--temp-dir=DIR` | Create temporary files in DIR | ⚠️ Caveat | `--temp-dir` with the rsync short `-T` (the timeout alias moved to long-only `--timeout`). **Protocol 2.23.0 receiver policy: the scratch dir is confined to the receive root — a relative dir is resolved below it, and an absolute path or one containing `..` is rejected by the receiver** (an absolute/foreign-filesystem scratch dir was the divergence; rsync's standalone mode would follow an absolute `--temp-dir`, while its daemon also confines). Temp copies use a unique name there and are atomically renamed into place. **On `EXDEV` (scratch dir and destination on different filesystems) the receiver falls back to a non-atomic copy instead of aborting the transfer**, matching rsync. `--inplace` and `--partial-dir` writes bypass the scratch dir |
+| `--delay-updates` | Put updated files in place at end | ❌ Divergent | Successfully received files are staged under a private 0700 `.fastsync-stage` dir inside the receive root and atomically renamed into their final destinations only after the whole transfer (manifest/delete handling included) succeeds, just before the success/outcome frame is sent. The delete walker deliberately skips the staging dir at the receive root, so `--delete` removes genuine extras but never the staged files (deletion runs before publication; rsync's delete-after ordering is not implemented). `--existing`/`--ignore-existing`/`--update` decide against the final destination path at stage time; `--backup` moves the old file aside at publication, and **`--force` is honored at publication** (protocol 2.23.0): a staged regular file or symlink may replace a destination directory that blocks it. Incompatible with `--inplace` and with `--backup-dir=.fastsync-stage` (the internal staging name is reserved; both are rejected). The staging dir name is fixed, so two simultaneous delayed transfers to the same destination root are serialized with an exclusive advisory lock held for the whole transfer: the second session fails cleanly instead of corrupting the first. Aborting or failing before publication installs nothing and removes the staging tree; a crash between stage and publish leaves staged leftovers that the next delayed run wipes at start (process death releases the lock). A stage→publish failure aborts the transfer (best-effort cleanup of the not-yet-published staged files; already-published files are not rolled back). **Reclassified Divergent (differential evidence):** the staging name is fixed and a delayed run wipes a pre-existing destination tree of that name at start even without `--delete`, whereas rsync uses its own internal temp name and leaves a genuine destination entry named `.fastsync-stage` untouched (`test_delay_updates_staging_name_collision_residual`); deletion also runs before publication while rsync's `--delay-updates` implies `--delete-after`. Works in single-threaded and `-j`/`--threads` modes |
+| `-T`, `--temp-dir=DIR` | Create temporary files in DIR | ❌ Divergent | `--temp-dir` with the rsync short `-T` (the timeout alias moved to long-only `--timeout`). A **relative** dir matches rsync exactly: it is resolved below the receive/destination root and must already exist (differentially verified: `rsync -a --temp-dir=scratch src/ dst/` and FastSync produce identical trees and an empty scratch dir). **Reclassified as a deliberate divergence because an absolute `--temp-dir` is rejected by the receiver** — it is resolved verbatim by rsync standalone (which will use `/tmp` or any other absolute directory, including one outside the destination), but FastSync's security-reviewed receiver confines the scratch dir to the authorized receive root and rejects any absolute path or one containing `..`. A differential test confirms rsync exits 0 using an absolute scratch dir while FastSync refuses before writing anything into it (the scratch dir stays empty). Its daemon mode also confines relative to the module, but standalone rsync's absolute-temp-dir behavior is not reproduced because it would let a client place receiver scratch files outside the sandbox. Temp copies use a unique name in the scratch dir and are atomically renamed into place; **on `EXDEV` (scratch dir and destination on different filesystems, reachable via a confined relative symlink) the receiver falls back to a non-atomic copy instead of aborting**, matching rsync. `--inplace` and `--partial-dir` writes bypass the scratch dir |
 | `--partial` | Keep partially transferred files | ✅ Parity | On a failed/interrupted write the already-written temp file is retained at the destination path (best-effort rename instead of unlink) so a later `--append`/`--append-verify` run can resume it. Retention never runs when no data was actually written or under `--ignore-existing`/`--existing` (the destination is not ours to overwrite), and it only ever renames the already-written temp. A failed rename falls back to the normal unlink |
 | `--partial-dir=DIR` | Keep partial files in DIR | ✅ Parity | With `--partial`, the working file is written under the confined partial directory (a relative dir below the receive root) and atomically renamed into place once complete, so an interrupted transfer leaves a resumable copy there and completed transfers do not linger under it. `--inplace` bypasses the partial dir (rsync parity). Requires `--partial` |
 
@@ -158,7 +159,7 @@ Every one of those has an entry below with its remaining caveats.
 | `--max-delete=NUM` | Max files to delete | ✅ Parity | `max_delete` config field (default -1 = no client limit; 0 = delete nothing). **Protocol 2.23.0 matches rsync's partial semantics:** the receiver deletes up to NUM entries (regular files, symlinks and empty directories; each directory removal counts as one) and then **stops deleting, skips the rest, and reports the run as partial**. The client prints a "deletions stopped due to `--max-delete` limit" message and exits **25** (rsync's `RERR_PARTIAL`), not a hard failure — the transfer itself succeeded. NUM only applies together with `--delete` (it is inert otherwise, matching rsync). A client NUM below the server hard bound `MAX_SERVER_DELETE_COUNT` (100000) replaces it; a NUM above it never raises that cap. Deleting an entire destination with no limit is still bounded by the server's 100000-entry ceiling. `--delete-missing-args` exact-path deletions and the ordinary extras walk draw from the same budget, matching rsync |
 | `--ignore-errors` | Delete even with I/O errors | ✅ Parity | Sender-side, client-only config field. Matches rsync's semantics exactly: an unreadable source subdirectory is always skipped so the readable tree transfers (the transfer root itself stays fatal), and the run reports rsync's partial-transfer exit **23**. Deletion policy follows rsync: by default an I/O error suppresses deletion (`IO error encountered -- skipping file deletion`), while `--ignore-errors` lets the deletion commit. The decision applies to every timing (`--delete`, `--delete-before`, `--delete-during`, `--delete-delay`, `--delete-after`) in both the sequential and `--threads` send paths. Differential-tested against rsync 3.4.1 with both tools run as an unprivileged user (mode-000 source directory); the reference build's root-only gate still excludes the EACCES differential, but the setpriv differential test exercises it. The piece that stays FastSync-specific is documented under the recursive-empty-directory residual: FastSync never emits an unreadable (or empty) directory entry, so that mirror is an extra that a run with `--ignore-errors` removes, where rsync emits the directory and keeps its mirror |
 | `--force` | Force deletion of non-empty dirs | ✅ Parity | `force_delete` receiver config field (crosses the wire). rsync's `--force` lets an incoming non-directory replace a destination directory; FastSync implements exactly that: when a regular file (or symlink) is written to a path that is currently a (possibly non-empty) destination directory, `--force` removes that directory tree first — confined to the receive root and symlink-safe (O_NOFOLLOW fd walk, symlinks removed by name, never followed) — so the install can place the file. **Protocol 2.23.0 honors `--force` on the `--delay-updates` publication path too**, not only the immediate-install path. Without `--force` such a write fails and the run aborts. Gated by the server `--allow-delete` policy (a client cannot use `--force` to remove a destination tree on a server that forbids deletion) |
-| `-m`, `--prune-empty-dirs` | Prune empty dir chains | ✅ Parity | `-m`/`--prune-empty-dirs` (Phase 7 Wave A freed the rsync short `-m`; FastSync multithreading is now `-j`/`--threads`). FastSync's recursive transfer records directory times but never CREATES an empty directory (a `STATUS_DIR_TIMES` entry is record-only, and `--dirs` empty entries are pruned by this flag), so empty directories are inherently never transferred (which is rsync's `-m` behavior) and truly-empty destination directory chains are removed by `--delete` regardless of this flag. The flag's additional real effect is on the `--dirs` explicit directory-entry generator: a plain `-d <empty-dir>` run omits the empty source directory's entry, so nothing is created at the destination (no `STATUS_MKDIR`, no `-i`/`--out-format` change line, and an existing empty mirror becomes an extra that `--delete` prunes). Explicitly `--files-from`-listed directories always pass through (documented `--files-from` behavior). A directory that still holds an excluded-but-protected file survives, matching the `--delete-excluded` default |
+| `-m`, `--prune-empty-dirs` | Prune empty dir chains | ✅ Parity | `-m`/`--prune-empty-dirs` (Phase 7 Wave A freed the rsync short `-m`; FastSync multithreading is now `-j`/`--threads`). A recursive transfer now recreates empty source directories by default (rsync parity); this flag suppresses that emission, so an empty directory (physically empty, or emptied by filtering) is not created and a true empty-directory chain is removed by `--delete`, matching rsync's `-m`. It also affects the `--dirs` explicit directory-entry generator: a plain `-d <empty-dir>` run omits the empty source directory's entry, so nothing is created at the destination (no `STATUS_MKDIR`, no `-i`/`--out-format` change line, and an existing empty mirror becomes an extra that `--delete` prunes). Explicitly `--files-from`-listed directories always pass through (documented `--files-from` behavior; `--files-from` runs never emit implicit empty directories). A directory that still holds an excluded-but-protected file survives, matching the `--delete-excluded` default |
 
 **Deletion-timing implementation notes (Phase 3):** the delete flags above are
 real. Two new config booleans (`delete_during`, `delete_delay`) join the already
@@ -302,7 +303,7 @@ why plain `--append` works on the normal atomic path, not only with `--inplace`.
 | `--write-devices` | Write to devices as files | ❌ Divergent | Writes only into an existing char/block node under the confined receive root (`O_NOFOLLOW` + `O_NONBLOCK`); a missing, symlinked, FIFO-with-no-reader, non-device, or otherwise unusable destination is skipped with a warning rather than allowed or aborted. Deliberate confinement divergence from rsync's more permissive behavior |
 | `-U`, `--atimes` | Preserve access times | ✅ Parity | Captures the source access time (from the scanner's pre-read stat, so it is not clobbered by reading the file for transfer) and transmits it over the wire; the receiver restores it together with the mtime via `futimens`/`utimensat`. Implies metadata transmission (the times travel inside the shared metadata payload), but does not enable ownership application (that stays opt-in via the identity flags). Wire: `atime` fields on the metadata frame + a `preserve_atimes` config boolean; `PROTOCOL_VERSION` bumped **2.11.0 → 2.12.0** |
 | `-N`, `--crtimes` | Preserve create times | ❌ Divergent | Birth-times cannot be set by any portable filesystem call (`utimensat`/`futimens` only set atime/mtime), so this row is an explicit **Divergent** entry (Phase 7 Wave B). Capture + transmit stays: `statx(STATX_BTIME)` on Linux records the source birth time as a wire field; the receiver logs a debug note that it cannot be applied and continues — never failing the transfer and never pretending it worked. On platforms without `statx` it parses as a documented no-op (flag accepted; nothing is captured). Implies metadata transmission. Wire: new `crtime` fields + a `preserve_crtimes` config boolean; `PROTOCOL_VERSION` bumped **2.11.0 → 2.12.0** (see the Phase-4 metadata-time notes) |
-| `-O`, `--omit-dir-times` | Omit dirs from --times | ✅ Parity | Real modifier now that FastSync preserves directory times. With metadata on, the scanner captures every traversed source directory's mtime (and atime under `-U`) and the sender transmits them in trailing `STATUS_DIR_TIMES` frame(s) **after all file data and the optional delete manifest** (chunked at the receiver's `MAX_MANIFEST_ENTRIES` per-frame cap); a dir-time entry only RECORDS metadata and never creates the directory, so empty source directories stay untransferred. The receiver defers applying them until its delete / `--delay-updates` publication phases have committed, so writing or removing a child never clobbers a parent directory's mtime (rsync applies directory times at the end for exactly this reason). When `-O` is set (the boolean crosses the wire) the receiver does not apply any of them; without `-O` an `-a`/`--preserve` transfer now restores directory times (reversing the old "never preserves dir times" divergence). Wire change: the terminal `STATUS_DIR_TIMES` frame; `PROTOCOL_VERSION` bumped **2.16.0 → 2.17.0** |
+| `-O`, `--omit-dir-times` | Omit dirs from --times | ✅ Parity | Real modifier now that FastSync preserves directory times. With metadata on, the scanner captures every traversed source directory's mtime (and atime under `-U`) and the sender transmits them in trailing `STATUS_DIR_TIMES` frame(s) **after all file data and the optional delete manifest** (chunked at the receiver's `MAX_MANIFEST_ENTRIES` per-frame cap); a dir-time entry only RECORDS metadata and never creates the directory (an empty source directory is created by the separate `STATUS_MKDIR` entry the scanner now emits, and `-m/--prune-empty-dirs` suppresses that; the trailing dir-time simply re-applies the metadata). The receiver defers applying them until its delete / `--delay-updates` publication phases have committed, so writing or removing a child never clobbers a parent directory's mtime (rsync applies directory times at the end for exactly this reason). When `-O` is set (the boolean crosses the wire) the receiver does not apply any of them; without `-O` an `-a`/`--preserve` transfer now restores directory times (reversing the old "never preserves dir times" divergence). Wire change: the terminal `STATUS_DIR_TIMES` frame; `PROTOCOL_VERSION` bumped **2.16.0 → 2.17.0** |
 | `-J`, `--omit-link-times` | Omit symlinks from --times | ✅ Parity | Real modifier now that FastSync preserves symlink times. Symlink entries already carried their metadata on `STATUS_SYMLINK`; the receiver now applies it with **no-follow primitives only** (`utimensat(..., AT_SYMLINK_NOFOLLOW)`, plus best-effort `fchmodat(..., AT_SYMLINK_NOFOLLOW)` and policy-gated `fchownat(..., AT_SYMLINK_NOFOLLOW)`), so the link itself is stamped without ever dereferencing it, confined fd-relative below the authorized receive root. A symlink has no children, so the times are applied immediately at creation. When `-J` is set (the boolean crosses the wire) the receiver skips the timestamps (mode/ownership are unaffected); without `-J` an `-a`/`-l` transfer restores symlink mtimes. Wire change alongside `-O`: the shared `STATUS_DIR_TIMES` frame; `PROTOCOL_VERSION` bumped **2.16.0 → 2.17.0** |
 | `--super` | Receiver attempts super-user activities | ❌ Divergent | Safe-subset privilege model. `--super` permits the receiver to attempt already-confined super-user activities (ownership application, char/block device-node creation, `--write-devices`); `--no-super` forbids them even for root; `auto` keeps the historical best-effort attempt. **FastSync never elevates** — no `setuid`/`seteuid`/`setgid` — and `--super` never bypasses the confinement floor, so it diverges from rsync's real elevation. A server `--no-super` veto forces it off for every connection; a privileged standalone listener defaults off without `--allow-super`; daemon modules opt in with `client owner = yes` |
 | `--fake-super` | Store/recover privileged attrs via xattrs | ❌ Divergent | Records the resolved `uid:gid:mode:mtime_sec:mtime_nsec` in a reserved `user.fastsync.stat` xattr and immediately replays mode/times fd-relative, but **never performs a real `chown`** (the owner is recorded for a later privileged restore). The on-disk key and format are FastSync-native, not rsync's `user.rsync.%stat%`, so recordings are not interoperable with rsync — the same class as the native auth and batch formats. Implies metadata transmission; incompatible with `-s` |
@@ -644,10 +645,10 @@ targets verbatim, matching rsync.
 |------|-------------------|-----------------|-------|
 | `--checksum` | Skip based on checksum | ✅ Parity | `-c`/`--checksum` compares per-file whole-file content digests to skip unchanged files. **As of protocol 2.23.0 the short `-c` implies the checksum quick-check**, so a plain `-c` run verifies content rather than only affecting the `--incremental` handshake. The digest algorithm is `xxh128` by default (protocol 2.26.0's negotiated default) and is selectable via `--checksum-choice`/`--cc` (`xxh128`/`xxh3`/`xxh64`/`xxhash`/`md5`/`md4`/`sha1`/`none`/`auto`, plus rsync's two-name form) and `--checksum-seed=NUM` (see those rows) |
 | `--checksum-choice=STR`, `--cc=STR` | Choose checksum algorithm | ⚠️ Caveat | Real algorithm selection for the per-file whole-file digest used by the `--incremental`/`--checksum` handshake and basis-dir verification. **Protocol 2.26.0 accepts rsync 3.4.1's full set** — `xxh128` (the negotiated default), `xxh3`, `xxh64`, `xxhash`, `md5`, `md4`, `sha1`, `none`, `auto`, and the two-name `transfer,pre-transfer` form — with rsync's exit-4 rejection of an unknown name and of `none` on the transfer side when `--checksum` is on. `--cc=ALG` and space forms both parse. The algorithm id and seed cross the wire; the receiver hashes its old file with the same algorithm+seed and the per-file `STATUS_CHECK` handshake carries a bounded digest pinned to the negotiated length. `checksum_digest_file` now streams **every** supported algorithm (md4 via the self-contained RFC 1320 code, sha1/md5 via EVP, none as an empty digest), so the streaming path matches its contract, and `--out-format %C` uses the selected **transfer** half of a two-name choice and renders each algorithm byte-for-byte like rsync (xxh128 high-then-low, xxh64/xxh3 big-endian, md5/md4/sha1 standard hex, none a blank 2-char column) — differential-tested across all algorithms. **Remaining divergences:** rsync uses this choice for the block checksum on the wire too, while FastSync selects only the whole-file comparison digest and keeps the delta BLOCK strong checksum at xxHash32; the `RSYNC_CHECKSUM_LIST` environment variable is not consulted; and `auto` always resolves deterministically to the first supported entry in rsync's preference order rather than probing the peer |
-| `--compare-dest=DIR` | Compare dest files relative to DIR | ⚠️ Caveat | DIR is a receiver-side basis; protocol 2.26.0 uses an absolute path verbatim (rsync semantics) and resolves a relative path below the destination root (`..` components are rejected, `//` collapsed and trailing `/` dropped). On the receiver's per-file check (implies `--incremental`) an exact match = same size + mtime (unless `--size-only`; `-I` disables matching) **and** equal xxHash64 of the sender's file; a match suppresses the data transfer. compare-dest never copies: it only skips a file the destination does **not** already hold (sparse destination, rsync parity), and is consulted before the normal delta/full paths. Repeatable; searched in command-line order, first match wins. Divergences: when the destination already holds a *different* version rsync deletes it but FastSync instead transfers the data (keeps the mirror complete; never deletes without `--delete`); attribute-only differences on a match are not re-applied (data is skipped so the sender never sends metadata); content is verified by xxHash64, stricter than rsync's default quick check. Sizing: FastSync's whole-file payload limit is 256 MiB on **every** transfer path (not basis-specific); rsync applies basis dirs to arbitrary sizes, so FastSync refuses a basis run whose source contains a larger file up front with a clear error before any transfer. Wire: a basis-count field is always present on the config frame (protocol 2.9.0, so clients and servers must both be 2.9.0) |
-| `--copy-dest=DIR` | Include copies of unchanged files | ⚠️ Caveat | Same basis rules as `--compare-dest`, but an exact match materializes a **local copy** of the DIR file into the destination (via the normal atomic temp+rename store path, so `--existing`/`--ignore-existing`/`--update`/`--backup`/`--delay-updates` all still apply) instead of transferring data. Repeatable; command-line order = priority. Content is xxHash64-verified before the copy. Divergences: a basis-hit destination keeps the basis file's own mode/uid/gid and mtime (the sender sends no metadata on a skip), so with `--size-only` its mtime can differ from the source and attribute-only differences are copied with the basis attributes rather than rsync's "copy + fix attributes". Requires `--incremental` (implied); incompatible with `-s`. Wire: protocol 2.9.0 |
-| `--link-dest=DIR` | Hardlink to files when unchanged | ⚠️ Caveat | Same basis rules as `--copy-dest`, but an exact match installs an atomic **hard link** to the DIR file (temp hard link + rename) so no data or disk space is used; where the link is impossible (basis on another filesystem, filesystem refuses links) it falls back cleanly to a byte-identical local copy, never a corrupt/partial file. `--delay-updates` stages the link and publishes by rename, so the final entry stays a real hard link. Repeatable (searched in command-line order, first match wins). Content is xxHash64-verified before linking. Divergences and caveats: protocol 2.26.0 re-links an already up-to-date destination file to the basis (the relink path installs the hard link when the content matches); a link keeps the basis inode's own mode/uid/gid and mtime — metadata is never written through the shared inode (that would mutate the basis file), so a later `--inplace` run that rewrites such a destination path **will mutate the basis snapshot** through the shared inode (use `--copy-dest` when the destination must stay independently writable); with `--size-only` the linked mtime can differ from the source; a `--remove-source-files` source satisfied by a basis dir is treated as skipped and therefore **retained** (never removed); basis dirs are excluded from `--delete`. Requires `--incremental` (implied); incompatible with `-s`. Wire: protocol 2.9.0 |
-| `-y`, `--fuzzy`, `--no-fuzzy` | Find similar file for basis | ⚠️ Caveat | `-y/--fuzzy` is a pure bandwidth optimization on the existing receiver-driven delta path: when a file must be transferred and the destination holds no usable content at the exact path (file absent, or the destination file is outside the delta engine's size bounds), the receiver searches the SAME destination directory for an existing regular file whose basename is similar to the incoming name and uses it as the delta basis, so the sender transmits only the differences instead of the whole file. The output is always byte-exact regardless of which (or whether any) basis is chosen. Decision location: the receiver performs the candidate search inside `receive_incremental_check` and sends the normal `STATUS_DELTA_SIGNATURE`; the sender never learns the basis was a different file, so no new frame type or sender logic was needed — only the config frame grew a `fuzzy` boolean, so `PROTOCOL_VERSION` was bumped **2.8.0 → 2.9.0** (peers must match). Similarity heuristic (deterministic, simpler than rsync's deliberately-fuzzy matching, and documented precisely): candidates are the target's sibling entries in its destination directory, opened `O_NOFOLLOW`/`AT_SYMLINK_NOFOLLOW` under the confined root (symlinks never followed; nothing outside the destination root is ever read or hashed); dotfiles, directories, the target's own name, and the `.fastsync-stage`/temp scratch names are excluded; like the ordinary delta path, the block signature the receiver transmits is derived from on-disk content it may not otherwise send, so a negotiated `--fuzzy` run exposes the destination's sibling files (at block granularity) to the sender as a known-plaintext oracle — the same information class as the normal delta handshake over the file being replaced; the size gate is the delta engine's own bounds (both files ≥ 16 KiB, ≤ `--delta-max`, ratio ≤ 10×) rather than rsync's ~1.5× size window; protocol 2.26.0 uses a name-distance/suffix heuristic modelled on rsync's plus an exact size+mtime pass, and reads a single best candidate; the exact tie-break order can still differ from rsync's; the directory scan is capped at 4096 entries so a pathological directory cannot stall a transfer. When fuzzy applies: only to files the receiver would otherwise send whole — the destination's own file is always preferred as the delta basis when it exists and fits the delta size bounds, so fuzzy does NOT replace an existing-but-different destination basis; FastSync's 10× delta size-ratio bound means an existing destination file that is too far away in size still lets the fuzzy search run. When no similar candidate exists the transfer falls back to the normal whole-file transfer. rsync-divergence note: rsync's own matching uses a fuzzy name/size rule set; FastSync implements the closest safe deterministic approximation above. Because FastSync's delta machinery is off by default (rsync's is on), `--fuzzy` implies `--incremental` + `--delta` (unless `--whole-file`/`-W` or an explicit `--no-delta` switched delta off, in which case fuzzy is inert — matching rsync where `--whole-file` makes fuzzy irrelevant). Unlike the basis-dir options, `--fuzzy` honors an explicit `--no-incremental` (it does not force the handshake back on); an explicit `--no-incremental` also suppresses the delta implication so no invalid `--delta requires --incremental` config results. `--no-fuzzy` negates it. All surrounding semantics are untouched: a fuzzy-reconstructed file is stored as a normal file, so `--remove-source-files`, itemize/`-i`, `--stats`, `--backup`, `--delay-updates`, `--existing`/`--ignore-existing`/`--update` behave exactly as for a whole-file transfer (the fuzzy delta does not skip the file) |
+| `--compare-dest=DIR` | Compare dest files relative to DIR | ❌ Divergent | DIR is a receiver-side basis; protocol 2.26.0 uses an absolute path verbatim (rsync semantics) and resolves a relative path below the destination root (`..` components are rejected, `//` collapsed and trailing `/` dropped). On the receiver's per-file check (implies `--incremental`) an exact match = same size + mtime (unless `--size-only`; `-I` disables matching) **and** equal xxHash64 of the sender's file; a match suppresses the data transfer. compare-dest never copies: it only skips a file the destination does **not** already hold (sparse destination, rsync parity), and is consulted before the normal delta/full paths. Repeatable; searched in command-line order, first match wins. **Reclassified Divergent (differential evidence):** FastSync verifies a basis hit's content with xxHash64 while rsync's `--size-only` quick check trusts size (and mtime) alone, so with a same-size/different-content basis rsync skips/links the *wrong* basis content while FastSync transfers the source — a deliberate safety-stricter behavior that cannot match rsync (see `test_basis_dir_size_only_content_residual` in `tests/integration/test_parity_quickwins.py`). Attribute-only differences on a match are also not re-applied (data is skipped so the sender never sends metadata). Sizing: FastSync's whole-file payload limit is 256 MiB on **every** transfer path (not basis-specific); rsync applies basis dirs to arbitrary sizes, so FastSync refuses a basis run whose source contains a larger file up front with a clear error before any transfer. Wire: a basis-count field is always present on the config frame (protocol 2.9.0, so clients and servers must both be 2.9.0) |
+| `--copy-dest=DIR` | Include copies of unchanged files | ❌ Divergent | Same basis rules as `--compare-dest`, but an exact match materializes a **local copy** of the DIR file into the destination (via the normal atomic temp+rename store path, so `--existing`/`--ignore-existing`/`--update`/`--backup`/`--delay-updates` all still apply) instead of transferring data. Repeatable; command-line order = priority. Content is xxHash64-verified before the copy. **Reclassified Divergent** for the same basis-hit verification divergence as `--compare-dest`: rsync's `--size-only` size/quick-check match rings a same-size/different-content file as unchanged and copies the wrong basis bytes, while FastSync's xxHash verification transfers the source (differential test `test_basis_dir_size_only_content_residual`); a basis-hit also keeps whatever metadata the copy derived from the basis rather than rsync's "copy + fix attributes" in attribute-only cases. Requires `--incremental` (implied); incompatible with `-s`. Wire: protocol 2.9.0 |
+| `--link-dest=DIR` | Hardlink to files when unchanged | ❌ Divergent | Same basis rules as `--copy-dest`, but an exact match installs an atomic **hard link** to the DIR file (temp hard link + rename) so no data or disk space is used; where the link is impossible (basis on another filesystem, filesystem refuses links) it falls back cleanly to a byte-identical local copy, never a corrupt/partial file. `--delay-updates` stages the link and publishes by rename, so the final entry stays a real hard link. Repeatable (searched in command-line order, first match wins). Content is xxHash64-verified before linking. **Reclassified Divergent** for the shared basis-hit divergence: with `--size-only` a same-size/different-content basis is linked by rsync (installing wrong content) but FastSync detects the xxHash mismatch and transfers the source (differential test `test_basis_dir_size_only_content_residual`). Other inherent caveats: protocol 2.26.0 re-links an already up-to-date destination file to the basis; a link keeps the basis inode's own mode/uid/gid and mtime — metadata is never written through the shared inode (that would mutate the basis file), so a later `--inplace` run that rewrites such a destination path **will mutate the basis snapshot** through the shared inode (use `--copy-dest` when the destination must stay independently writable); a `--remove-source-files` source satisfied by a basis dir is treated as skipped and therefore **retained** (never removed); basis dirs are excluded from `--delete`. Requires `--incremental` (implied); incompatible with `-s`. Wire: protocol 2.9.0 |
+| `-y`, `--fuzzy`, `--no-fuzzy` | Find similar file for basis | ❌ Divergent | `-y/--fuzzy` is a pure bandwidth optimization on the existing receiver-driven delta path: when a file must be transferred and the destination holds no usable content at the exact path (file absent, or the destination file is outside the delta engine's size bounds), the receiver searches the SAME destination directory for an existing regular file whose basename is similar to the incoming name and uses it as the delta basis, so the sender transmits only the differences instead of the whole file. The output is always byte-exact regardless of which (or whether any) basis is chosen. Decision location: the receiver performs the candidate search inside `receive_incremental_check` and sends the normal `STATUS_DELTA_SIGNATURE`; the sender never learns the basis was a different file, so no new frame type or sender logic was needed — only the config frame grew a `fuzzy` boolean, so `PROTOCOL_VERSION` was bumped **2.8.0 → 2.9.0** (peers must match). Similarity heuristic (deterministic, simpler than rsync's deliberately-fuzzy matching, and documented precisely): candidates are the target's sibling entries in its destination directory, opened `O_NOFOLLOW`/`AT_SYMLINK_NOFOLLOW` under the confined root (symlinks never followed; nothing outside the destination root is ever read or hashed); dotfiles, directories, the target's own name, and the `.fastsync-stage`/temp scratch names are excluded; like the ordinary delta path, the block signature the receiver transmits is derived from on-disk content it may not otherwise send, so a negotiated `--fuzzy` run exposes the destination's sibling files (at block granularity) to the sender as a known-plaintext oracle — the same information class as the normal delta handshake over the file being replaced; the size gate is the delta engine's own bounds (both files ≥ 16 KiB, ≤ `--delta-max`, ratio ≤ 10×) rather than rsync's ~1.5× size window; protocol 2.26.0 uses a name-distance/suffix heuristic modelled on rsync's plus an exact size+mtime pass, and reads a single best candidate; the exact tie-break order can still differ from rsync's; the directory scan is capped at 4096 entries so a pathological directory cannot stall a transfer. When fuzzy applies: only to files the receiver would otherwise send whole — the destination's own file is always preferred as the delta basis when it exists and fits the delta size bounds, so fuzzy does NOT replace an existing-but-different destination basis; FastSync's 10× delta size-ratio bound means an existing destination file that is too far away in size still lets the fuzzy search run. When no similar candidate exists the transfer falls back to the normal whole-file transfer. rsync-divergence note: rsync's own matching uses a fuzzy name/size rule set; FastSync implements the closest safe deterministic approximation above. Because FastSync's delta machinery is off by default (rsync's is on), `--fuzzy` implies `--incremental` + `--delta` (unless `--whole-file`/`-W` or an explicit `--no-delta` switched delta off, in which case fuzzy is inert — matching rsync where `--whole-file` makes fuzzy irrelevant). Unlike the basis-dir options, `--fuzzy` honors an explicit `--no-incremental` (it does not force the handshake back on); an explicit `--no-incremental` also suppresses the delta implication so no invalid `--delta requires --incremental` config results. `--no-fuzzy` negates it. All surrounding semantics are untouched: a fuzzy-reconstructed file is stored as a normal file, so `--remove-source-files`, itemize/`-i`, `--stats`, `--backup`, `--delay-updates`, `--existing`/`--ignore-existing`/`--update` behave exactly as for a whole-file transfer (the fuzzy delta does not skip the file). **Reclassified Divergent:** because the output is always byte-exact, the residual is the candidate-selection heuristic itself — a deterministic name-distance/suffix rule with a 10× size-ratio window (vs rsync's ~1.5× window), not rsync's deliberately fuzzy matcher, so the chosen basis (and thus the wire bytes) can differ from rsync even though the final tree cannot. The Integration fuzzy suite (`TestFuzzy`) pins FastSync's thresholds (exact-size+mtime pass, name-distance rejection, 10× unsuitable-destination fallback); a bit-identical basis choice is not achievable without porting rsync's matcher |
 
 ## 12. Compression
 
@@ -748,7 +749,7 @@ modes or links.
 | `--stop-at=TIME` | Stop at specified time | ✅ Parity | Deadline transfer stop (client-only, never serialized). Protocol 2.26.0 accepts rsync's full date/time grammar (`2030-12-31T23:59`, `2030/12/31T23:59`, `2030-12-31`, `12-31`, `14:00`, `:59`, `1`) in addition to FastSync's `HH:MM[:SS]` and `now+N[smhd]`; a past time stops immediately. Everything already transferred is kept and an early stop suppresses the late `--delete` keep-set so unscanned source mirrors survive. Works single-threaded and under `-j`/`--threads` |
 | `--fsync` | Fsync every written file before publication | ✅ Parity | |
 | `--protocol=NUM` | Force older protocol version | ❌ Divergent | Forces the wire protocol version for this transfer. FastSync has exactly ONE wire format (`PROTOCOL_VERSION`, currently 2.27.0) with no downgrade/backward-compat code paths, so `--protocol=2.27.0` is accepted (it sets the version claim the client sends, which the server already requires to match exactly) and **every other value is rejected up front** with a clear error before any connection — it does not and cannot speak an older or virtual wire format. Divergence from rsync (which negotiates a range and downgrades to an integer 0..31): FastSync's honest contract is force-to-the-one-supported-value; a genuine downgrade would require a per-version compatibility layer that does not exist. Client-only; the server-side exact-match check is unchanged. `--protocol=2.26.0`/`2.25.0`/`2.24.0`/`2.23.0`/`2.22.0`/`2.21.0`/`2.20.0`/`2.19.0`/`2.18.0`/`2.17.0`/`2.16.0`/`2.15.0`/`216`/`31`/garbage are all rejected. See the Phase-6 protocol note below |
-| `--iconv=CONVERT_SPEC` | Charset conversion | ⚠️ Caveat | Charset conversion of FILE NAMES (not content) at the protocol boundary via iconv(3): `--iconv=LOCAL[,REMOTE]` — the sender converts each local filename LOCAL→REMOTE before transmitting, and the receiver converts each wire filename REMOTE→LOCAL before creating/writing. The full CONVERT_SPEC is serialized into the config frame as a new trailing string field so the peer knows the wire charset; **PROTOCOL_VERSION bumped 2.15.0 → 2.16.0**. `LOCAL[,REMOTE]` parse: single charset ⇒ LOCAL==REMOTE (identity both ways); garbage rejected up front; protocol 2.26.0 additionally accepts `--iconv=.` (the locale's default charset for both directions), `--iconv=-` and `--no-iconv` (disable conversion). Validation probes BOTH directions (a spec that only opens one way is refused, as is a NUL-emitting target charset like utf-16/utf-32/ucs-2, since filenames cannot contain NUL). An unrepresentable name (EILSEQ/EINVAL) fails that path cleanly with a logged `--iconv: cannot convert file name ...` and is never written mangled/truncated. Conversion is applied at EVERY wire-path site (regular/MKDIR/hardlink path+target/symlink path+target/SPECIAL, the delete manifest, the incremental-check path, and the `-s`/`chunk_serialize` embedded blob path), on both client and server (`--iconv` is also a server/daemon option). Zero overhead when unset. See the Phase-6 iconv notes below |
+| `--iconv=CONVERT_SPEC` | Charset conversion | ✅ Parity | Charset conversion of FILE NAMES (not content) at the protocol boundary via iconv(3): `--iconv=LOCAL[,REMOTE]` — the sender converts each local filename LOCAL→REMOTE before transmitting, matching rsync's rule that the spec "stays the same whether you're pushing or pulling": on a PUSH the destination end's charset is the spec's REMOTE half, so the default receiver writes the wire bytes verbatim, and only a server started with its own `--iconv` (the daemon `charset` analog) declares a different destination charset and converts REMOTE→that LOCAL (rsync push parity, differential-tested with and without a server `--iconv`). The full CONVERT_SPEC is serialized into the config frame as a new trailing string field so the peer knows the wire charset; **PROTOCOL_VERSION bumped 2.15.0 → 2.16.0**. `LOCAL[,REMOTE]` parse: single charset ⇒ LOCAL==REMOTE (identity both ways); garbage rejected up front; protocol 2.26.0 additionally accepts `--iconv=.` (the locale's default charset for both directions), `--iconv=-` and `--no-iconv` (disable conversion). Validation probes BOTH directions (a spec that only opens one way is refused, as is a NUL-emitting target charset like utf-16/utf-32/ucs-2, since filenames cannot contain NUL). An unrepresentable name (EILSEQ/EINVAL) fails that path cleanly with a logged `--iconv: cannot convert file name ...` and is never written mangled/truncated. Conversion is applied at EVERY wire-path site (regular/MKDIR/hardlink path+target/symlink path+target/SPECIAL, the delete manifest, the incremental-check path, and the `-s`/`chunk_serialize` embedded blob path), on both client and server (`--iconv` is also a server/daemon option). Zero overhead when unset. See the Phase-6 iconv notes below |
 | `--checksum-seed=NUM` | Set checksum seed | ✅ Parity | Sets the seed for FastSync's whole-file xxHash digest (full 64-bit seed) and for the delta path's per-block xxHash32 strong checksum (low 32 bits of the seed). **As of protocol 2.23.0 a seed of `0` — the default when the flag is unset — is randomized per transfer and the chosen seed is sent to the receiver**, exactly like rsync, so two runs against different content do not share a predictable seed; an explicit non-zero seed is used verbatim, so an explicit seed deterministically reproduces every computed digest on BOTH endpoints (the seed crosses in the config frame). `--checksum-choice=md5` has no seed and ignores it (documented). The value is a strict decimal 0..2⁶⁴-1 (blank, signed, or non-numeric values are rejected). Like rsync, a seed only matters where a digest is actually computed (`--checksum` or a basis-dir run, or a delta transfer); it does not by itself enable `--checksum`/`--delta` |
 | `--secluded-args`, `-s` | Use protocol to send args | ❌ Divergent | Accepted for CLI compatibility (including the rsync short `-s`, Phase 7 Wave A) but a documented **no-op / divergence**. rsync's `-s` protects arguments from shell expansion by shipping them over the protocol; FastSync never passes remote arguments through a shell expansion boundary in the first place — its SSH transport builds the remote argv as **single-quote-escaped shell words** (`ssh_build_remote_command`), so the injection/leak that `-s` guards against does not exist and there is nothing to "seclude". Implementing a true arg-send protocol would mean replacing the argv-based SSH launch with an in-band argument channel, a large redesign of the transport that buys no security here. Chunk serialization remains the long-only `--chunk-serialization`. |
 | `--protect-args` | Old name of --secluded-args | ❌ Divergent | Accepted for CLI compatibility as a documented no-op; the same rationale as `--secluded-args`/`-s` (FastSync's remote SSH argv is already built injection-safe, so there is no argument-leak to close) |
@@ -862,7 +863,7 @@ These are the hardest compatibility items because they require durable formats o
 
 **Phase 6, Wave A (stop deadline) shipping note:** `--stop-after=MINS` and `--stop-at=TIME` are client-only sender stop deadlines. `--stop-after` takes a positive minute count (0/negative/garbage rejected); `--stop-at` takes `HH:MM`, `HH:MM:SS`, or `now+N[smhd]` (a past time stops immediately, a garbage spec is rejected at parse time). The deadline is computed once at the start of the transfer (CLOCK_MONOTONIC for `--stop-after`, wall clock via `time()` for `--stop-at`) and checked at every chunk boundary in both the single-threaded `send_files` loop and the multithreaded `send_chunks_multithreaded` path, and inside the scanner loops so a busy scan itself stops. When it fires, the transfer stops ELEGANTLY: the in-flight chunk completes, the existing completion tail runs (summary, `disconnect`), and the run returns 0 — exactly like rsync's clean early stop. Because the deadline is client-only and never crosses the wire config frame, no PROTOCOL_VERSION bump is required. The safety-critical interaction is with `--delete`: FastSync streams while scanning, so a deadline can cut the source scan short and yield a PARTIAL keep-set manifest; committing that would make the receiver delete destination mirrors of source files not yet scanned. So the sender tracks `scan_stopped_early` and, when it is true on the late/delete-after (`--delete`/`--delete-after`/`--delete-delay`) path, SUPPRESSES the keep-set manifest (logs a warning) so no deletion happens from an incomplete set — this is the safe direction (preserves data; the delete simply does not run). `--delete-before`/`--delete-during` are unaffected: their complete pre-scan runs before any data and ignores the deadline (a stop can be exceeded by that pre-scan). Under `-j`/`--threads` the stop is symmetric and the scanner thread's still-in-progress manifest appends can never race the tail because the tail does not read the manifest on the early-stop path.
 
-**Phase 6, Wave B (iconv) shipping note (PROTOCOL 2.15.0 → 2.16.0):** `--iconv=LOCAL[,REMOTE]` converts file NAMES at the wire boundary (never content). The full CONVERT_SPEC is serialized into the config frame as a new trailing string field (empty→NULL canonicalized), so both ends share the same wire charset interpretation; this required the PROTOCOL bump because the frame is a strict ordered sequence and a peer that does not parse the new trailing field would desynchronize. Each end derives LOCAL (its own charset) and REMOTE (the wire charset): the sender opens LOCAL→REMOTE and converts every transmitted filename; the receiver opens REMOTE→LOCAL and converts every received filename before creating/writing. Conversion is applied at every wire-path site (regular/MKDIR/hardlink path+target/symlink path+target/SPECIAL, the delete manifest keep/protected/missing entries, the incremental-check path, and the embedded `-s`/chunk-blob path). A name it cannot convert (EILSEQ/EINVAL) is failed cleanly with a logged `--iconv: cannot convert file name ...` and is never written truncated/mangled. Validation probes both directions up front (both the sender local→remote and the receiver remote→local, and, for a server/daemon with its own `--iconv`, the client-REMOTE→server-LOCAL pair) so an unusable spec is rejected before the connection rather than mid-transfer, and NUL-emitting target charsets (utf-16/utf-32/ucs-2) are refused because filenames cannot contain NUL. Divergence documented upstream: the receiver does NOT half-swap; the wire charset always comes from the sender's REMOTE half, so a server whose local charset differs from the client's LOCAL must declare it with its own `--iconv`. Conversion is process-global and runs on a single thread per process (sender thread / receiver-loop thread), initialized before worker threads start and freed after they join.
+**Phase 6, Wave B (iconv) shipping note (PROTOCOL 2.15.0 → 2.16.0):** `--iconv=LOCAL[,REMOTE]` converts file NAMES at the wire boundary (never content). The full CONVERT_SPEC is serialized into the config frame as a new trailing string field (empty→NULL canonicalized), so both ends share the same wire charset interpretation; this required the PROTOCOL bump because the frame is a strict ordered sequence and a peer that does not parse the new trailing field would desynchronize. Each end derives its charset and the wire charset: the sender opens LOCAL→REMOTE and converts every transmitted filename; on a push the receiver's destination charset is the spec's REMOTE half, so it writes the wire bytes verbatim, unless the server was started with its own `--iconv` naming a different LOCAL charset (then it opens REMOTE→that LOCAL). Conversion is applied at every wire-path site (regular/MKDIR/hardlink path+target/symlink path+target/SPECIAL, the delete manifest keep/protected/missing entries, the incremental-check path, and the embedded `-s`/chunk-blob path). A name it cannot convert (EILSEQ/EINVAL) is failed cleanly with a logged `--iconv: cannot convert file name ...` and is never written truncated/mangled. Validation probes both directions up front (both the sender local→remote and the receiver remote→destination, and, for a server/daemon with its own `--iconv`, the client-REMOTE→server-LOCAL pair) so an unusable spec is rejected before the connection rather than mid-transfer, and NUL-emitting target charsets (utf-16/utf-32/ucs-2) are refused because filenames cannot contain NUL. The wire charset always comes from the sender's REMOTE half; a server whose local charset differs from the client's REMOTE must declare it with its own `--iconv` (the daemon `charset` analog). Conversion is process-global and runs on a single thread per process (sender thread / receiver-loop thread), initialized before worker threads start and freed after they join.
 
 **Phase 6, Wave C (protocol-version) shipping note (no PROTOCOL_VERSION change):** `--protocol=NUM` lets the client force the wire protocol version for a transfer. FastSync's protocol is a single lockstep format: the config frame is a strict ordered sequence and the server requires the client's version string to equal `PROTOCOL_VERSION` exactly (`config_receive_with_validate`, src/shared/config.c) — there are no older-format code paths and no downgrade/negotiation machinery, so a lower/higher/virtual version can never be spoken. The honest contract is therefore: the current `PROTOCOL_VERSION` (2.26.0 as of the parity-completion wave) is accepted and stored into the client's `version` claim (which `config_send` already transmits), and every other value — `2.25.0`, `2.24.0`, `2.23.0`, `2.22.0`, `2.21.0`, `2.20.0`, `2.19.0`, `2.18.0`, `2.18`, `2.17.0`, `2.16.0`, `2.15.0`, `3.0.0`, rsync-integer spellings like `216`/`31`, garbage, empty — is rejected up front in `validate_config()` before any connection, with a clear error that FastSync supports only its current wire protocol and cannot speak an older or virtual one. Implementation is client-only: a server-side `--protocol` is intentionally not added because the server has no negotiation (it only enforces exact match), and it could only ever be the current version. This preserves (and slightly tightens) existing validation: the client now also refuses to launch with a version it cannot actually speak, rather than only the server rejecting it later. A genuine downgrade would require a per-version compatibility layer for every frame/feature added since (append 2.10, preallocate 2.11, hardlinks 2.12, devices/specials/symlink-trust/xattr 2.13, remote-option 2.14, daemon module/auth 2.15, iconv 2.16, dir/symlink times 2.17, privilege flags --super/--copy-as 2.18, SCRAM daemon auth 2.19, packed metadata 2.20, error-detail/dry-run 2.21, preserve-attribute split 2.22, rsync-parity wave 2.23) and is intentionally out of scope — documented divergences from rsync's integer-negotiated downgrade remain.
 
@@ -893,7 +894,7 @@ These are the last compatibility items and the closing phase toward rsync flag p
 
 **Wave D — Times superstructure & arg-protection no-ops (✅ implemented, `--secluded-args` ❌).** `-O`/`--omit-dir-times` and `-J`/`--omit-link-times` are now **real modifiers** (both `🔄 → ✅ Implemented`), reversing the old "never preserves directory/symlink times" divergence:
 
-- **Directory times.** The recursive scanner captures every traversed source directory's metadata (mtime, plus atime under `-U`) into a per-transfer list — two paths are covered: the sequential `DirectoryScanner` captures each opened directory (including the transfer root), and the parallel scanner captures both the root in `parallel_scanner_create_with_options` and each worker's subdirectories in `open_next_directory` (appends are guarded by a mutex shared with the sender's pipeline context). The sender transmits them in trailing `STATUS_DIR_TIMES` frames (each: int count + count × (wire path, metadata) pairs) sent **after all file data and after the optional delete manifest**, just before `STATUS_FINISHED`. A tree larger than `MAX_MANIFEST_ENTRIES` (1 048 576) directories is chunked into repeated frames, each within the receiver's per-frame bound. A dir-time entry is RECORD-ONLY (`file->dir_time_only`): `file_save_to_disk_full` returns `FILE_SAVE_SKIPPED` without creating anything, so a source directory that was empty (or pruned by `-m/--prune-empty-dirs`) is never resurrected. The receiver accumulates received directory metadata in a `DirTimeList` and applies it only at the very end — after the entire stream, after the commit-style `--delete` deletion, and after `--delay-updates` publication — because creating or removing a child bumps the parent's mtime. Application is fd-relative/walk-confined (`file_open_secure_parent` + `utimensat(..., AT_SYMLINK_NOFOLLOW)`) and best-effort per entry: an absent path (an intentionally uncreated empty dir) is skipped QUIETLY and only a real existing directory is stamped. `-O` (config boolean, already on the wire) makes the receiver skip the whole set. The single-threaded sink applies in `receiver_send_success_frame`; the `-j`/`--threads` sink accumulates in `write_thread` and server.c applies after both threads join and the deletion commits.
+- **Directory times.** The recursive scanner captures every traversed source directory's metadata (mtime, plus atime under `-U`) into a per-transfer list — two paths are covered: the sequential `DirectoryScanner` captures each opened directory (including the transfer root), and the parallel scanner captures both the root in `parallel_scanner_create_with_options` and each worker's subdirectories in `open_next_directory` (appends are guarded by a mutex shared with the sender's pipeline context). The sender transmits them in trailing `STATUS_DIR_TIMES` frames (each: int count + count × (wire path, metadata) pairs) sent **after all file data and after the optional delete manifest**, just before `STATUS_FINISHED`. A tree larger than `MAX_MANIFEST_ENTRIES` (1 048 576) directories is chunked into repeated frames, each within the receiver's per-frame bound. A dir-time entry is RECORD-ONLY (`file->dir_time_only`): `file_save_to_disk_full` returns `FILE_SAVE_SKIPPED` without creating anything (the directory's creation, when it is empty, is now carried by a separate `STATUS_MKDIR` entry the scanner emits for every directory that produced no transferred child, and `-m/--prune-empty-dirs` suppresses that). The receiver accumulates received directory metadata in a `DirTimeList` and applies it only at the very end — after the entire stream, after the commit-style `--delete` deletion, and after `--delay-updates` publication — because creating or removing a child bumps the parent's mtime. Application is fd-relative/walk-confined (`file_open_secure_parent` + `utimensat(..., AT_SYMLINK_NOFOLLOW)`) and best-effort per entry: an absent path (an intentionally uncreated empty dir) is skipped QUIETLY and only a real existing directory is stamped. `-O` (config boolean, already on the wire) makes the receiver skip the whole set. The single-threaded sink applies in `receiver_send_success_frame`; the `-j`/`--threads` sink accumulates in `write_thread` and server.c applies after both threads join and the deletion commits.
 - **Symlink times/owner/mode.** `STATUS_SYMLINK` already carried metadata; the receiver now applies it with no-follow primitives only: `utimensat(..., AT_SYMLINK_NOFOLLOW)`, best-effort `fchmodat(..., AT_SYMLINK_NOFOLLOW)` (honest no-op where unsupported, e.g. Linux), and policy-gated `fchownat(..., AT_SYMLINK_NOFOLLOW)` via a new `identity_apply_ownership_link` that shares the identity resolver with the fd path. `-J` suppresses only the timestamps; ownership stays governed by the identity opt-in (`--numeric-ids`/`--usermap`/`--groupmap`/`--chown`) exactly like regular files. A symlink has no children, so this is applied immediately at creation.
 - **Wire:** the shared `STATUS_DIR_TIMES` frame (and metadata on `STATUS_MKDIR` for `--dirs` entries) is a frame-sequence change, so `PROTOCOL_VERSION` was bumped **2.16.0 → 2.17.0**; every version-sensitive test (`--protocol` accepted/rejected values) was updated. The config-frame layout itself is unchanged (the omit booleans already crossed). Non-metadata and `--no-preserve` transfers send no `STATUS_DIR_TIMES` frame and no directory metadata, keeping them byte-identical.
 
@@ -907,7 +908,7 @@ These are the last compatibility items and the closing phase toward rsync flag p
 
 **Wire:** two trailing config-frame blocks after the `--iconv` spec, in fixed order — `send_privilege_options`/`receive_privilege_options` (one `super_mode` int, validated `0..2`), then `send_copy_as_options`/`receive_copy_as_options` (presence int + two int32 ids, validated `>= 0`, with `copy_as_set ⇒ use_metadata`). `PROTOCOL_VERSION` bumped **2.17.0 → 2.18.0**. **Divergences from rsync:** rsync's `--super` elevates the receiver and `--copy-as` actually switches its credentials; FastSync never elevates and only permits/forwards confined attempts, and `--copy-as` forces ownership rather than switching identity.
 
-**Honest status after the parity-completion wave (protocol 2.26.0), updated by the rsync-parity-stats pass.** ✅ Parity 107 / ⚠️ Caveat 25 / ❌ Divergent 24 = 156 rows. Earlier revisions of this document reported "143 ✅ / 0 divergence / 0 partial"; that conflated "parsed and tested" with "rsync parity", because many rows carried documented behavioral differences and some short options were not parsed at all. This reclassification makes every difference explicit. The completion wave closed 23 previously-caveated rows (9 that triage showed were already parity, plus 14 genuine fixes) and turned the 17 inherently non-rsync rows — native daemon config/auth, the FastSync batch container, the safe-subset device/privilege flags, `-X`'s privileged namespaces, `--fake-super`'s native xattr format, and the `--old-args` no-op — into explicit ❌ divergences. The stats pass flipped `--delete-delay` to ✅ (actual-removal accounting) and reclassified `--out-format` to ❌ (protocol-specific `%b`/delta-`%c`), and sharpened the `--stats`/`--progress`/`--checksum-choice` residuals. The remaining ⚠️ rows are the ones with a documented residual (see the row notes and the **Parity Completion Wave (protocol 2.26.0)** section below).
+**Honest status after the parity-completion wave (protocol 2.27.0), updated by the rsync-parity-stats, rsync-parity-options, and rsync-parity-fs passes.** ✅ Parity 112 / ⚠️ Caveat 12 / ❌ Divergent 33 = 157 rows. Earlier revisions of this document reported "143 ✅ / 0 divergence / 0 partial"; that conflated "parsed and tested" with "rsync parity", because many rows carried documented behavioral differences and some short options were not parsed at all. This reclassification makes every difference explicit. The completion wave closed 23 previously-caveated rows (9 that triage showed were already parity, plus 14 genuine fixes) and turned the 17 inherently non-rsync rows — native daemon config/auth, the FastSync batch container, the safe-subset device/privilege flags, `-X`'s privileged namespaces, `--fake-super`'s native xattr format, and the `--old-args` no-op — into explicit ❌ divergences. The stats pass flipped `--delete-delay` to ✅ (actual-removal accounting) and reclassified `--out-format` to ❌ (protocol-specific `%b`/delta-`%c`), and sharpened the `--stats`/`--progress`/`--checksum-choice` residuals. The options pass flipped `--bwlimit` and `--ignore-errors` to ✅ (rsync-exact size parsing and ~100 ms leaky-bucket throttling, and rsync's skip-unreadable-subdir plus IO-error-suppressed deletion with exit 23) and emits rsync-format `--info=name/flist/del/remove/nonreg/progress` lines (real-run `deleting`/`*deleting` carried over a new trailing `report_deletes` wire bool, `PROTOCOL_VERSION` 2.26.0 → 2.27.0), while reclassifying `-M` over daemon/TCP and receiver-side `protect`/`risk` re-derivation to ❌ (no argv channel / receiver filter engine). The fs pass flipped `-d/--dirs` and `--iconv` to ✅ — recursive transfers now recreate empty source directories (and replace a blocking destination non-directory with an incoming directory); `-R --no-implied-dirs --files-from` places a listed file under a missing implied parent with default attributes instead of refusing; and `--iconv` now reproduces rsync's push direction (destination charset = the spec's REMOTE half) — and reclassified seven rows to ❌ after reproducing their exact residual with differential tests: `--temp-dir` (the receiver confines the scratch dir to the receive root, so an absolute temp dir is deliberately rejected although standalone rsync follows it), the three basis-dir options (FastSync xxHash-verifies a basis hit while rsync's `--size-only` quick check installs the wrong basis content), `--delay-updates` (fixed staging name wipes an unrelated destination entry of that name), `--fuzzy` (deterministic heuristic with a 10× size window, not rsync's matcher), and `--dry-run` (would-delete report over-reports). The remaining ⚠️ rows are the ones with a documented residual (see the row notes and the **Parity Completion Wave (protocol 2.26.0)** section below).
 
 **Preserve-attribute split (protocol 2.21.0 → 2.22.0) — ✅ implemented.** FastSync splits the former single metadata bundle into four independent, rsync-compatible per-attribute flags — `-p/--perms`, `-t/--times`, `-o/--owner`, `-g/--group` — each with a negation (`--no-perms`/`--no-times`/`--no-owner`/`--no-group`, short `--no-p`/`--no-t`/`--no-o`/`--no-g`), plus `--no-preserve` clearing all four. `-a/--archive` is now full rsync `-rlptgoD` (owner and group included, though their application stays privilege-gated), `-A/--acls` implies `-p`, `-X/--xattrs` does not, `-E/--executability` sets only executability, and `-U`/`-N` do not imply `-t`. `--incremental`/`--delta` still auto-preserve perms+times unless the user explicitly negated them. Wire: the binary config frame gains four appended booleans (`preserve_perms`/`preserve_times`/`preserve_owner`/`preserve_group`) after `omit_link_times`, so `PROTOCOL_VERSION` is bumped **2.21.0 → 2.22.0**; the fixed-width `FileMetadata` layout is unchanged and the receiver gates the metadata frame on a derived `use_metadata`. Receiver behavior: each attribute is applied independently, directory modes are applied under `-p` (at the end of the transfer, alongside dir times), symlink mode under `-p`, and `-O/--omit-dir-times` suppresses directory times only. Documented divergences as of 2.22.0, **all but (d)/(e) removed by the rsync-parity wave (protocol 2.23.0)**: (a) the mode-masking divergence is **gone** — under `-p` the source mode is now copied exactly, including `S_IWGRP`/`S_IWOTH` and setuid/setgid/sticky; (b) a brand-new file without `-p` still gets `source_mode & ~umask` when metadata is present (else the historical fixed `0644`), and a new *directory* without `-p` still uses FastSync's `0755` default; (c) the `--chmod`-implies-`-p` divergence is **gone** — `--chmod` no longer implies `-p` (rsync parity); (d) `-o`/`-g` map by name on the receiver with a raw-numeric fallback (only numeric ids cross the wire); (e) a daemon module without `client owner = yes` does not refuse a plain `-a`/`-o`/`-g` — it forces super off, applies no ownership, and logs a warning, while explicit `--chown`/`--usermap`/`--groupmap`/`--numeric-ids`/`--copy-as`/`--super` are still refused.
 
@@ -1154,13 +1155,14 @@ These remain after the wave; the individual rows carry the precise wording.
   sender-derived). `--ignore-errors` exits 23 but its EACCES differential is not
   exercised in CI.
 - **`--delay-updates`** uses a fixed staging name with an advisory lock and
-  deletes before publication; **`--temp-dir`** rejects absolute/foreign paths;
-  **`--remote-option`** is SSH-only; **`--iconv`** keeps the receiver
-  half-swap/charset-declaration caveat.
+  deletes before publication; **`--temp-dir`** rejects absolute/foreign paths
+  (deliberately confined, see the row); **`--remote-option`** is SSH-only.
+  **`--iconv`** now matches rsync's push direction (destination charset = the
+  spec's REMOTE half; a server `--iconv` overrides it).
 - **Basis dirs** do not re-apply attributes on a match, keep the
   `--size-only` mtime caveat, and share the 256 MiB whole-file cap; **`--fuzzy`**
-  has a different tie-break order; recursive transfers still do not create empty
-  directories; and **`--bwlimit`** rejects rsync's `0`/decimal/suffixed rates.
+  has a different tie-break order; and **`--bwlimit`** rejects rsync's
+  `0`/decimal/suffixed rates.
 - **`--inc-recursive`/`--no-inc-recursive`** are not implemented (rejected).
 
 ### Intentional divergences (explicit ❌ rows)

pytest.ini

@@ -8,3 +8,6 @@ markers =
     daemon_detach: real double-fork backgrounding path (--daemon without
         --no-detach); slower/fragile, so it runs in the full suite but not the
         fast PR gate
+    parity: differential rsync-parity case (full set; runs on push to
+        dev/main)
+    parity_ci: fast differential rsync-parity subset (runs on the PR gate)

src/client/client_send.c

@@ -472,6 +472,13 @@ static bool prepare_scanner(const Config* config, int num_threads, PreparedScann
   options->exclude_per_dir_filter_files = config->per_dir_filter_count >= 2;
   options->dirs = config->dirs;
   options->relative = config->relative;
+  /* A real recursive transfer recreates empty source directories (rsync
+     parity); low-level scanner users leave this off. */
+  options->emit_empty_dirs = true;
+  /* --no-implied-dirs only has meaning with -R (rsync): without it the option
+     is a documented no-op, so the scanner must not suppress directory
+     metadata. */
+  options->no_implied_dirs = config->no_implied_dirs && config->relative;
   /* -R/--relative outside --files-from reconstructs every destination path from
    * the source spec (rsync's '/./' cut point).  With --files-from the listed
    * entry already supplies the bare relative path, so no prefix is built. */
@@ -635,72 +642,6 @@ static const char* delete_plan_walk_root(const Config* config, const ArrayList*
   return marker;
 }
 
-/* True when some --files-from entry is an ancestor-or-equal directory of
- * `rel` (an empty entry -- the whole tree "." -- counts as the root). */
-static bool file_list_ancestor_listed(const FileListSet* set, const char* rel) {
-  if (!set)
-    return true;
-  for (int i = 0; i < set->count; i++) {
-    const char* listed = set->entries[i];
-    if (listed[0] == '\0')
-      return true;
-    size_t n = strlen(listed);
-    if (strncmp(rel, listed, n) == 0 && (rel[n] == '/' || rel[n] == '\0'))
-      return true;
-  }
-  return false;
-}
-
-/* --no-implied-dirs (meaningful only with -R + --files-from): a listed file
- * may only be placed when its parent directory (or one of its ancestors) is
- * itself an explicitly listed entry.  rsync omits a file whose implied parent
- * directory is suppressed, and an explicitly listed file that cannot be placed
- * fails the transfer; FastSync fails the whole run up front with a clear error
- * (it has no per-entry skip channel).  Without -R or --files-from the option
- * has no effect. */
-static bool no_implied_dirs_files_from_valid(const Config* config) {
-  if (!config->no_implied_dirs || !config->relative)
-    return true;
-  const FileListSet* set = (const FileListSet*)config->files_from_set;
-  if (!set)
-    return true;
-  for (int i = 0; i < set->count; i++) {
-    const char* entry = set->entries[i];
-    if (entry[0] == '\0')
-      continue;
-    char* full = path_cat(config->send_directory, entry);
-    if (!full)
-      return false;
-    struct stat st;
-    bool is_file = lstat(full, &st) == 0 && S_ISREG(st.st_mode);
-    free(full);
-    if (!is_file)
-      continue;
-    const char* slash = strrchr(entry, '/');
-    if (!slash)
-      continue; /* top-level file: its parent is the receive root */
-    size_t parent_len = (size_t)(slash - entry);
-    if (parent_len == 0)
-      continue;
-    char* parent = malloc(parent_len + 1);
-    if (!parent)
-      return false;
-    memcpy(parent, entry, parent_len);
-    parent[parent_len] = '\0';
-    bool listed = file_list_ancestor_listed(set, parent);
-    if (!listed) {
-      log_message(LOG_LEVEL_ERROR,
-                  "--no-implied-dirs: cannot place file '%s': parent directory '%s' is not "
-                  "explicitly listed (list the directory or drop --no-implied-dirs)",
-                  entry, parent);
-    }
-    free(parent);
-    if (!listed)
-      return false;
-  }
-  return true;
-}
-
 /* The destination-relative mirror path for a missing --files-from entry: where
    a PRESENT entry with the same name would have been written.  With -R that is
    the entry's bare relative path (the bare wire path the receiver uses);
@@ -814,7 +755,7 @@ static bool files_from_list_check(const Config* config, ArrayList* missing_dest,
                   "--ignore-missing-args: ignored %d missing --files-from entr%s", *skipped_out,
                   *skipped_out == 1 ? "y" : "ies");
   }
-  return no_implied_dirs_files_from_valid(config);
+  return true;
 }
 
 /* Basis directories are honored by the receiver's per-file incremental check,

src/client/scanner.c

@@ -854,7 +854,8 @@ static bool scanner_capture_dir_time(ArrayList* dir_entries, mtx_t* mutex, const
                                      const char* fs_path, bool relative_mode,
                                      const char* relative_prefix, bool preserve_atimes,
                                      bool preserve_crtimes, bool preserve_xattrs,
-                                     bool preserve_acls) {
+                                     bool preserve_acls, bool no_implied_dirs,
+                                     const FileListSet* file_list) {
   if (!dir_entries || !root_path || !fs_path)
     return true;
   struct stat st;
@@ -863,6 +864,13 @@ static bool scanner_capture_dir_time(ArrayList* dir_entries, mtx_t* mutex, const
   char* rel = scanner_path_relative(root_path, fs_path);
   if (!rel)
     return true;
+  /* --no-implied-dirs: an implied parent directory (not listed, and not under
+     a listed directory) keeps the destination's own/default attributes, so its
+     source metadata is not transmitted. */
+  if (no_implied_dirs && file_list && !file_list_dir_in_scope(file_list, rel)) {
+    free(rel);
+    return true;
+  }
   if (relative_mode && rel[0] == '\0') {
     /* -R + --files-from: the transfer root itself has no bare relative wire
        path (matches the -R scan, which never emits the root). */
@@ -926,6 +934,43 @@ static bool scanner_capture_dir_time(ArrayList* dir_entries, mtx_t* mutex, const
   return true;
 }
 
+/* Recursive scan: emit a payload-less directory entry for the directory that
+ * just finished scanning.  rsync creates every source directory at the
+ * destination; FastSync otherwise creates one only implicitly through a
+ * transferred child, so a directory emptied on the transfer side (physically
+ * empty, or all of its entries filtered out) would never appear.  The transfer
+ * root is skipped (it maps to the receive root, which already exists), as are
+ * --files-from (only listed items and their implied parents transfer),
+ * --list-only (directory lines are emitted by the caller) and
+ * -m/--prune-empty-dirs.  Returns false on allocation failure. */
+static bool scanner_emit_empty_dir(DirectoryScanner* scanner, ArrayList* chunk_data) {
+  if (!scanner->current_path || !scanner->current_rel || scanner->current_rel[0] == '\0')
+    return true;
+  struct stat st;
+  if (stat(scanner->current_path, &st) != 0 || !S_ISDIR(st.st_mode))
+    return true;
+  File* dir = scanner_build_dir_file(scanner->current_path, &st, &scanner->options);
+  if (!dir)
+    return false;
+  if (scanner->relative_mode) {
+    dir->send_path = str_dup(scanner->current_rel);
+  } else if (scanner->options.relative_prefix) {
+    dir->send_path =
+        scanner_prefix_send_path(scanner->options.relative_prefix, scanner->current_rel);
+  }
+  if ((scanner->relative_mode || scanner->options.relative_prefix) && !dir->send_path) {
+    file_destroy(dir);
+    return false;
+  }
+  if (scanner->options.preserve_xattrs || scanner->options.preserve_acls)
+    dir->xattrs = xattr_capture_path(scanner->current_path, scanner->options.preserve_acls);
+  if (!array_list_add(chunk_data, dir)) {
+    file_destroy(dir);
+    return false;
+  }
+  return true;
+}
+
 /* Open the next queued directory and set up its filter context.  Returns 1 when
    a directory is open, 0 when the queue is exhausted, and -1 on a fatal error.
    A directory that cannot be opened is an I/O error: it is recorded on the
@@ -949,6 +994,7 @@ static int open_next_directory(DirectoryScanner* scanner) {
      * the directory that enqueued them. */
     const FilterNode* inherited = scanner->at_seed_dir ? scanner->seed_node : de->context;
     scanner->at_seed_dir = false;
+    scanner->current_dir_produced = false;
     free(de);
 
     free(scanner->current_rel);
@@ -1016,7 +1062,8 @@ static int open_next_directory(DirectoryScanner* scanner) {
             scanner->options.dir_entries, scanner->options.dir_entries_mutex, scanner->root_path,
             scanner->current_path, scanner->relative_mode, scanner->options.relative_prefix,
             scanner->options.preserve_atimes, scanner->options.preserve_crtimes,
-            scanner->options.preserve_xattrs, scanner->options.preserve_acls)) {
+            scanner->options.preserve_xattrs, scanner->options.preserve_acls,
+            scanner->options.no_implied_dirs, scanner->options.file_list)) {
       closedir(scanner->current_dir);
       scanner->current_dir = NULL;
       free(scanner->current_path);
@@ -1381,10 +1428,22 @@ Chunk* directory_scanner_next(DirectoryScanner* scanner) {
 
     const struct dirent* entry = readdir(scanner->current_dir);
     if (entry == NULL) {
+      /* The directory is exhausted: if nothing was transferred or descended
+         from it, recreate it at the destination as an explicit entry. */
+      if (scanner->options.emit_empty_dirs && !scanner->current_dir_produced &&
+          !scanner->options.prune_empty_dirs && !scanner->options.list_dirs &&
+          scanner->options.file_list == NULL) {
+        if (!scanner_emit_empty_dir(scanner, chunk_data))
+          scanner->failed = true;
+      }
       closedir(scanner->current_dir);
       scanner->current_dir = NULL;
       free(scanner->current_path);
       scanner->current_path = NULL;
+      if (scanner->failed) {
+        array_list_delete(chunk_data);
+        return NULL;
+      }
       continue;
     }
 
@@ -1519,6 +1578,7 @@ Chunk* directory_scanner_next(DirectoryScanner* scanner) {
           scanner->failed = true;
           break;
         }
+        scanner->current_dir_produced = true;
         free(cur_path);
         continue;
       }
@@ -1533,6 +1593,7 @@ Chunk* directory_scanner_next(DirectoryScanner* scanner) {
           break;
         }
       }
+      scanner->current_dir_produced = true;
       int next_depth = scanner->current_depth + 1;
       if (scanner->options.max_depth <= 0 || next_depth < scanner->options.max_depth) {
         DirEntry* de = dir_entry_create(cur_path, next_depth, scanner->current_node);
@@ -1609,6 +1670,7 @@ Chunk* directory_scanner_next(DirectoryScanner* scanner) {
         scanner->failed = true;
         break;
       }
+      scanner->current_dir_produced = true;
       chunk_data_size += file->data->size;
       if (chunk_data_size > scanner->options.chunk_size) {
         free(rel_copy);
@@ -2236,11 +2298,11 @@ ParallelScanner* parallel_scanner_create_with_options(const char* root_directory
      transfer root itself (it hands the root's immediate subdirectories to
      workers), so capture the root's directory time here. */
   if (options->capture_dir_times &&
-      !scanner_capture_dir_time(options->dir_entries, options->dir_entries_mutex, root_directory,
-                                root_directory, options->relative && options->file_list != NULL,
-                                options->relative_prefix, options->preserve_atimes,
-                                options->preserve_crtimes, options->preserve_xattrs,
-                                options->preserve_acls)) {
+      !scanner_capture_dir_time(
+          options->dir_entries, options->dir_entries_mutex, root_directory, root_directory,
+          options->relative && options->file_list != NULL, options->relative_prefix,
+          options->preserve_atimes, options->preserve_crtimes, options->preserve_xattrs,
+          options->preserve_acls, options->no_implied_dirs, options->file_list)) {
     array_list_delete(root_files);
     array_list_delete(subdirs);
     parallel_scanner_destroy(ps);

src/client/scanner.h

@@ -160,6 +160,17 @@ typedef struct {
   bool capture_dir_times;
   ArrayList* dir_entries;
   mtx_t* dir_entries_mutex;
+  /* Recreate empty source directories on a recursive transfer: emit a
+   * payload-less directory entry for every traversed directory that produced
+   * no transferred/descended child.  Off by default so low-level scanner users
+   * (unit helpers, --list-only) see only the historical file list; the real
+   * sender sets it in prepare_scanner. */
+  bool emit_empty_dirs;
+  /* --no-implied-dirs with -R + --files-from: a directory that is only an
+   * implied parent of a listed entry (not itself listed, nor below a listed
+   * directory) must not carry source metadata; it is created with default
+   * attributes at the destination, matching rsync. */
+  bool no_implied_dirs;
 } ScannerOptions;
 
 /* Internal per-scanner filter state. FilterNode chains represent the ordered
@@ -177,6 +188,11 @@ typedef struct {
   int current_depth;
   dev_t root_dev;
   bool failed;
+  /* Recursive scan: whether the open directory yielded any transferred or
+     descended entry.  When it did not, closing it emits a directory entry so
+     the empty source directory is recreated at the destination (rsync
+     parity). */
+  bool current_dir_produced;
   /* Phase 2 (files-from / filter layer). */
   char* root_path;          /* transfer root (fs path) for rel computation */
   char* current_rel;        /* rel path of the open directory ("" == root) */

src/client/usage.c

@@ -90,8 +90,8 @@ void print_usage(void) {
   printf("                      entry's destination mirror receiver-side.  Independent of\n");
   printf("                      --delete (it does not imply --delete; a non-empty directory\n");
   printf("                      mirror is removed only with --force or --delete)\n");
-  printf("  -m, --prune-empty-dirs  Do not transfer empty directory entries (--dirs mode);\n");
-  printf("                      recursive transfers never send empty dirs\n");
+  printf("  -m, --prune-empty-dirs  Do not create empty directories (a recursive transfer\n");
+  printf("                      otherwise recreates them, like rsync)\n");
   printf("  Note: each timing flag implies --delete.  Combining a timing flag with\n");
   printf("  --no-delete (in either order) is rejected as a config error.\n");
   printf("  --ignore-existing  Skip files that already exist on receiver\n");
@@ -103,8 +103,9 @@ void print_usage(void) {
   printf("  -R, --relative    With --files-from, preserve each listed entry's relative path\n");
   printf("                    below the destination root instead of mirroring the full\n");
   printf("                    source path (no effect without --files-from)\n");
-  printf("  --no-implied-dirs  With -R --files-from, refuse to place a listed file whose\n");
-  printf("                    parent directory is not itself listed\n");
+  printf("  --no-implied-dirs  With -R, do not apply the source metadata of a listed file's\n");
+  printf("                    implied parent directories (they are still created with\n");
+  printf("                    default attributes)\n");
   printf("  --mkpath          Create the destination root directory on the server when it\n");
   printf("                    does not exist yet\n");
   printf("  --exclude <pattern>, --exclude=<pattern>  Exclude files matching pattern\n");

src/shared/charset.c

@@ -168,9 +168,14 @@ bool charset_spec_valid_direction(const char* from_charset, const char* to_chars
   return direction_probe_valid(from_charset, to_charset);
 }
 
-/* The receiver's real conversion is wire(client REMOTE) -> server-local (the
- * server's own --iconv LOCAL half, or the client's LOCAL half when the server
- * has no --iconv).  A dedicated pre-ack check so an impossible direction is
+/* The receiver's conversion is wire charset -> destination charset.  rsync's
+ * CONVERT_SPEC is LOCAL,REMOTE and "stays the same whether you're pushing or
+ * pulling", so for a PUSH (FastSync's only direction) the destination end's
+ * charset is the spec's REMOTE half: the client converts LOCAL -> REMOTE on the
+ * sender and the receiver writes the wire bytes verbatim.  Only a server that
+ * declares its OWN --iconv (the daemon "charset" analog) has a different local
+ * charset, and then it is that spec's LOCAL half and the receiver converts
+ * wire -> server-local.  A dedicated pre-ack check so an impossible direction is
  * rejected before the connection instead of refusing mid-transfer. */
 bool charset_wire_receiver_spec_valid(const char* spec, const char* server_spec) {
   if (!spec)
@@ -180,7 +185,7 @@ bool charset_wire_receiver_spec_valid(const char* spec, const char* server_spec)
   if (charset_spec_parse(spec, &local, &remote) != 0)
     return false;
   const char* wire = remote;
-  const char* target_local = local;
+  const char* target_local = remote;
   char* server_local = NULL;
   char* server_remote = NULL;
   if (server_spec) {
@@ -302,13 +307,13 @@ bool charset_wire_init_receiver(const char* spec, const char* server_spec) {
   char* remote;
   if (charset_spec_parse(spec, &local, &remote) != 0)
     return false;
-  /* The wire charset is the client spec's REMOTE half; the local charset is
-   * the client spec's LOCAL half unless the server was itself started with
-   * --iconv naming a different local charset (the server halves above never
-   * travel, so the server's own flag is the only way its local charset can
-   * differ from what the client assumed). */
+  /* The wire charset is the client spec's REMOTE half (rsync's LOCAL,REMOTE
+   * spec stays the same push or pull, so on a push the destination end's
+   * charset is REMOTE and the receiver writes the wire bytes verbatim).  Only a
+   * server started with its own --iconv declares a different local charset (the
+   * server halves above never travel), and then it is that spec's LOCAL half. */
   const char* wire = remote;
-  const char* target_local = local;
+  const char* target_local = remote;
   char* server_local = NULL;
   char* server_remote = NULL;
   if (server_spec) {

src/shared/charset.h

@@ -57,8 +57,9 @@ void charset_conversion_close(void* conversion);
 /* Process-wide wire conversion.  charset_wire_init_sender (client side) opens
  * LOCAL->REMOTE; charset_wire_init_receiver (server side) opens
  * wire(REMOTE)->server-local.  server_spec is the server's own --iconv, whose
- * LOCAL half may override the local charset the client assumed; NULL reuses
- * the client spec's LOCAL half.  Both return false on an unsupported spec.
+ * LOCAL half overrides the destination charset; NULL means the destination
+ * charset is the client spec's REMOTE half (rsync's push semantics: the wire
+ * bytes are written verbatim).  Both return false on an unsupported spec.
  * The state is freed with charset_wire_free. */
 bool charset_wire_init_sender(const char* spec);
 bool charset_wire_init_receiver(const char* spec, const char* server_spec);
@@ -66,9 +67,9 @@ void charset_wire_free(void);
 bool charset_wire_active(void);
 
 /* Pre-ack receiver-direction sanity (see charset_wire_init_receiver): true
- * when the exact wire->server-local conversion the receiver will use (client
- * spec's REMOTE half into the server's own LOCAL half, or the client's LOCAL
- * half when the server has no --iconv) opens and produces NUL-free output. */
+ * when the exact wire->destination conversion the receiver will use (client
+ * spec's REMOTE half into the server's own LOCAL half, or REMOTE->REMOTE when
+ * the server has no --iconv) opens and produces NUL-free output. */
 bool charset_wire_receiver_spec_valid(const char* spec, const char* server_spec);
 
 /* Convert a path across the wire in the process direction.  Returns a malloc'd

src/shared/config.h

@@ -432,8 +432,10 @@ typedef struct Config {
    * repeated -F adds --filter='- .rsync-filter' so they are excluded too. */
   int per_dir_filter_count;
   bool one_file_system; /* -x/--one-file-system: do not cross filesystem boundaries */
-  /* --no-implied-dirs: client-only.  With -R + --files-from, refuse to place a
-   * listed file whose ancestor directory is not itself explicitly listed. */
+  /* --no-implied-dirs: client-only.  With -R, do not transfer the source
+   * metadata of the parent directories implied by a listed path; an unlisted
+   * implied parent is still created (with default attributes) so the listed
+   * file can be placed, matching rsync. */
   bool no_implied_dirs;
   /* -d/--dirs: client-only.  Transfer the directory entries named by the
    * source argument / --files-from list without recursing into contents. */

src/shared/file.c

@@ -807,6 +807,26 @@ bool file_ensure_directory_secure(const char* path) {
     } else if (errno == EEXIST) {
       dir_fd = openat(parent_fd, leaf, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
     }
+  } else if (dir_fd < 0 && (errno == ENOTDIR || errno == ELOOP)) {
+    /* rsync replaces a destination non-directory (regular file or symlink)
+       with an incoming directory.  Confined to the already-opened secure
+       parent fd: the leaf is unlinked by name (never followed) and only a
+       non-directory is ever removed, so this cannot escape the authorized
+       root or remove a pre-existing directory tree.  A symlink is left alone:
+       replacing it is not required for FastSync's transferred directories and
+       keeps --keep-dirlinks semantics untouched. */
+    struct stat leaf_st;
+    if (fstatat(parent_fd, leaf, &leaf_st, AT_SYMLINK_NOFOLLOW) == 0 && !S_ISDIR(leaf_st.st_mode) &&
+        !S_ISLNK(leaf_st.st_mode)) {
+      if (unlinkat(parent_fd, leaf, 0) == 0) {
+        if (mkdirat(parent_fd, leaf, (mode_t)(0777 & ~(mode_t)file_process_umask())) == 0) {
+          created = true;
+        } else if (errno != EEXIST) {
+          /* leave dir_fd < 0 so the caller sees the failure */
+        }
+        dir_fd = openat(parent_fd, leaf, O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC);
+      }
+    }
   }
   bool ok = dir_fd >= 0;
   /* --copy-as owns a directory this call just created (the final component;

tests/integration/README.md

@@ -0,0 +1,77 @@
+# Integration tests
+
+The integration suite drives the built `build/server` and `build/client`
+against local corpora. Unit tests live in `tests/` (the custom C framework);
+the Python suite here covers the full transfer pipeline, transports, features,
+and rsync parity.
+
+## Running
+
+```bash
+# Full suite (excludes privilege-dependent tests on CI runners)
+python3 -m pytest tests/integration/ -n 4 --dist=load -m "not setpriv"
+
+# Fast PR subset only
+python3 -m pytest tests/integration/ -n 4 --dist=load -m ci
+```
+
+The tests expect `build/server` and `build/client` (configure/build with CMake
+first); `common.py` derives `BUILD_DIR` from the repository root.
+
+## Differential rsync-parity gate
+
+`test_differential_parity.py` runs the **same** transfer with real
+`rsync 3.4.1` and with FastSync over separate destinations, then compares:
+
+- the destination trees — relative paths, file content hashes, symlink
+  targets, modes (where the case is about perms), and hard-link grouping;
+- the normalized stdout for output-oriented flags (`-i`,
+  `--out-format=...`, `--stats`), after stripping volatile fields
+  (timings, rates, wire byte counts) and directory-only itemize lines that
+  FastSync's recursive scanner documents as absent.
+
+FastSync mirrors the absolute source path under its receive root (see
+`get_dest_received_dir`); the harness normalizes that layout (and the
+`-R`/`--files-from` layouts) before comparing.
+
+```bash
+# Fast subset that guards the ✅ surface on pull requests
+python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity_ci
+
+# Full set (all ✅ cases plus the documented ⚠️/❌ residuals)
+python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity
+```
+
+The suite skips cleanly when `rsync` is not installed.
+
+## Allowlist (`parity_caveats.py`)
+
+`parity_caveats.py` is the single data-driven allowlist of known differences.
+Each entry maps a case id to the aspects that may differ (`tree`, `stdout`,
+`extra`, `rc`) and cites the governing row in `RSYNC_COMPAT.md`:
+
+```python
+CAVEATS = {
+    "min_size": {
+        "tree": "recursive transfer does not create a source directory that "
+                "becomes empty after --min-size filtering. ref: RSYNC_COMPAT.md "
+                "`-d/--dirs` row and completion-wave residual.",
+    },
+}
+```
+
+A differential mismatch in an aspect that is **not** listed fails the gate with
+a readable tree/stdout diff.
+
+If a case is allowlisted but now matches rsync, the gate emits a loud warning
+naming the stale entry — that is the parity burn-down signal. Run with
+`FASTSYNC_PARITY_STRICT=1` to make stale entries fail instead (the full CI
+parity job sets this). To add a residual:
+
+1. Reproduce it with `-m parity` and read the failure's tree/stdout diff.
+2. Confirm it is a documented `⚠️`/`❌` residual (or get the `✅` row
+   reclassified) and cite the row.
+3. Add the case id and aspect(s) to `CAVEATS`, keeping the reason concise.
+
+Do not allowlist an undocumented divergence from a `✅` row — fix it or get the
+row reclassified first.

tests/integration/parity_caveats.py

@@ -0,0 +1,46 @@
+"""Data-driven allowlist for the differential rsync-parity gate.
+
+Every entry maps a case id (see ``test_differential_parity.py``) to the aspects
+that are *known* to differ from ``rsync 3.4.1`` and the documented reason.  A
+differential mismatch in an aspect that is **not** listed here fails the gate.
+
+Aspect keys
+-----------
+``tree``    destination tree differs (paths, file hashes, symlink targets,
+            modes, hardlink grouping)
+``stdout``  normalized output for ``-i`` / ``--stats`` / ``--out-format``
+``extra``   a case-specific assertion differs (basis/inode checks, ...)
+``rc``      exit status differs
+
+Burn-down
+---------
+If a case is listed here but now matches rsync, the gate emits a loud
+``pytest`` warning naming the stale entry: delete the entry (and, when the
+underlying row in ``RSYNC_COMPAT.md`` is now parity, update that row).  Set
+``FASTSYNC_PARITY_STRICT=1`` to turn stale entries into failures in CI.
+
+Keep the values concise but cite the governing row so the entry can be
+re-triaged when the row moves.
+"""
+
+# case id -> {aspect: "reason (ref: RSYNC_COMPAT.md ...)"}
+CAVEATS = {
+    # --max-delete stops the extras walk part-way and exits 25 in both
+    # implementations; which of the remaining extras survives depends on
+    # deletion order, which neither tool specifies.  The exit code and the
+    # number of survivors match (asserted implicitly by the harness's rc
+    # comparison and the one-for-one diff below).
+    "max_delete": {
+        "tree": "which destination extras survive a partial --max-delete abort "
+                "is deletion-order dependent and unspecified; rc=25 and the "
+                "number of survivors match rsync. ref: RSYNC_COMPAT.md "
+                "`--max-delete=NUM` row.",
+    },
+}
+
+# Accepted aspect names (guards against typos in this file).
+ASPECTS = ("tree", "stdout", "extra", "rc")
+
+
+def caveat_for(case_id: str) -> dict:
+    return CAVEATS.get(case_id, {})

tests/integration/parity_harness.py

@@ -0,0 +1,502 @@
+"""Differential rsync-parity harness.
+
+Runs the SAME transfer with real ``rsync`` and with FastSync over separate
+destinations and compares the resulting trees and (optionally) normalized
+stdout.  ``test_differential_parity.py`` drives this module with a table of
+cases; ``parity_caveats.py`` is the data-driven allowlist of documented
+residuals.
+
+Design notes
+------------
+FastSync mirrors the *absolute* source path below its receive root, while
+rsync copies the source contents directly into the destination.  ``Case.layout``
+tells the harness which pair of directory roots to compare:
+
+* ``MIRROR``     -- rsync ``DEST/`` vs FastSync ``DEST/<abs-src>/`` (the common
+  case; matches ``common.get_dest_received_dir``).
+* ``MIRROR_ABS`` -- ``rsync -R`` without a cut lays the full absolute path
+  under the destination, so rsync ``DEST/<abs-src>/`` is compared against the
+  same FastSync mirror path.
+* ``RELATIVE``   -- ``rsync -R --files-from`` lays bare relative paths under the
+  destination and FastSync does the same, so both destination roots compare
+  directly.
+
+Only ``tests/integration/common.py`` is used to reach the build products and the
+server manager; the harness never duplicates that plumbing.
+"""
+import difflib
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Callable, Dict, List, Optional, Tuple
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import (  # noqa: E402  (path bootstrap above)
+    TEST_DATA_DIR,
+    clean_dir,
+    get_dest_received_dir,
+    run_client,
+)
+
+RSYNC = shutil.which("rsync")
+
+# Comparison layouts (see module docstring).
+MIRROR = "mirror"
+MIRROR_ABS = "mirror_abs"
+RELATIVE = "relative"
+
+# stdout comparators.
+STDOUT_NONE = None
+STDOUT_ITEMIZE = "itemize"
+STDOUT_OUTFMT = "outfmt"
+STDOUT_STATS = "stats"
+
+# rsync --stats lines that are protocol-independent and must match exactly.
+# Deliberately excluded: the per-type "Number of files"/"Number of created
+# files" breakdown and Total bytes sent/received (documented residual, see the
+# `--stats` row in RSYNC_COMPAT.md).
+STATS_KEYS = (
+    "Number of deleted files",
+    "Number of regular files transferred",
+    "Total file size",
+    "Total transferred file size",
+    "Literal data",
+    "Matched data",
+    "File list size",
+)
+
+_ITEMIZE_RE = re.compile(r"^(<|>|c|h|\.|\*)[fdLDS][.+\-][.+\-][.+\-][.+\-]")
+
+
+@dataclass
+class Case:
+    """One differential scenario: a corpus, a flag set, and how to compare."""
+
+    id: str
+    corpus: str
+    flags: List[str]
+    fastsync_flags: Optional[List[str]] = None
+    layout: str = MIRROR
+    server_args: Tuple[str, ...] = ("--allow-super",)
+    seed: Optional[Callable] = None
+    stdout: Optional[str] = STDOUT_NONE
+    compare_modes: bool = False
+    compare_hardlinks: bool = False
+    ignore_paths: Tuple[str, ...] = ()
+    extra_check: Optional[Callable] = None
+    files_from: Optional[Tuple[str, ...]] = None
+    # rsync receives ``src + "/"``; FastSync mirrors the path it is given, so a
+    # trailing-slash-sensitive case must hand FastSync the same form.
+    fs_src_suffix: str = ""
+    ci: bool = False
+    ref: str = ""
+
+    def fs_flags(self) -> List[str]:
+        return list(self.flags if self.fastsync_flags is None else self.fastsync_flags)
+
+
+# ---------------------------------------------------------------------------
+# Corpora
+# ---------------------------------------------------------------------------
+
+# Deterministic mtimes so quick-check decisions are reproducible.
+_SRC_MTIME = 1_600_000_000
+
+
+def _write(path: str, data: bytes, mode: Optional[int] = None) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "wb") as fh:
+        fh.write(data)
+    os.utime(path, (_SRC_MTIME, _SRC_MTIME))
+    if mode is not None:
+        os.chmod(path, mode)
+
+
+def _set_mode(path: str, mode: int) -> None:
+    os.chmod(path, mode)
+
+
+def corpus_basic(root: str) -> None:
+    """Regular files + nested dirs (dirs are implied by their files)."""
+    clean_dir(root)
+    _write(os.path.join(root, "a.txt"), b"hello world\n")
+    _write(os.path.join(root, "sub", "b.bin"),
+           bytes((i * 7) & 0xFF for i in range(5000)))
+    _write(os.path.join(root, "sub", "deep", "c.txt"), "w\u00f6rld\n".encode())
+
+
+def corpus_unicode(root: str) -> None:
+    clean_dir(root)
+    _write(os.path.join(root, "uni \u00f1\u6587.txt"), b"unicode\n")
+    _write(os.path.join(root, "sub", "sp ace \u00e9.dat"), b"spaced\n")
+    _set_mode(os.path.join(root, "sub"), 0o750)
+
+
+def corpus_links(root: str) -> None:
+    corpus_basic(root)
+    os.symlink("a.txt", os.path.join(root, "rel_link"))
+    os.symlink("/etc/hostname", os.path.join(root, "abs_link"))
+    os.symlink("nowhere/target", os.path.join(root, "broken_link"))
+
+
+def corpus_hardlinks(root: str) -> None:
+    clean_dir(root)
+    _write(os.path.join(root, "h1.txt"), b"hardlinked payload\n")
+    os.link(os.path.join(root, "h1.txt"), os.path.join(root, "h2.txt"))
+    _write(os.path.join(root, "other.txt"), b"other\n")
+
+
+def corpus_sparse(root: str) -> None:
+    clean_dir(root)
+    _write(os.path.join(root, "small.txt"), b"small\n")
+    sparse = os.path.join(root, "sparse.bin")
+    with open(sparse, "wb") as fh:
+        fh.seek(1024 * 1024 - 1)
+        fh.write(b"\0")
+    os.utime(sparse, (_SRC_MTIME, _SRC_MTIME))
+
+
+def corpus_filters(root: str) -> None:
+    clean_dir(root)
+    _write(os.path.join(root, "keep.txt"), b"keep\n")
+    _write(os.path.join(root, "drop.log"), b"log\n")
+    _write(os.path.join(root, "sub", "keep2.txt"), b"keep2\n")
+    _write(os.path.join(root, "sub", "drop2.log"), b"log2\n")
+    _write(os.path.join(root, "sub", "data.bin"), b"bin\n")
+
+
+def corpus_empty_dir(root: str) -> None:
+    clean_dir(root)
+    _write(os.path.join(root, "keep.txt"), b"keep\n")
+    os.makedirs(os.path.join(root, "emptydir"), exist_ok=True)
+    os.utime(os.path.join(root, "emptydir"), (_SRC_MTIME, _SRC_MTIME))
+    _write(os.path.join(root, "nonempty", "f.txt"), b"f\n")
+
+
+def corpus_relative(root: str) -> None:
+    """Tree for the -R/--files-from cases."""
+    clean_dir(root)
+    _write(os.path.join(root, "a.txt"), b"a\n")
+    _write(os.path.join(root, "b.txt"), b"b\n")
+    _write(os.path.join(root, "sub", "x.txt"), b"x\n")
+    _write(os.path.join(root, "sub", "y.txt"), b"y\n")
+    os.makedirs(os.path.join(root, "dir1"), exist_ok=True)
+    os.utime(os.path.join(root, "dir1"), (_SRC_MTIME, _SRC_MTIME))
+    _write(os.path.join(root, "dir1", "keep.txt"), b"keep\n")
+
+
+def corpus_iconv(root: str) -> None:
+    """Latin-1 (ISO-8859-1) encoded filenames, matching the --iconv direction."""
+    clean_dir(root)
+    for rel, data in ((b"caf\xe9.txt", b"caf\xe9\n"),
+                      (os.path.join(b"sub", b"\xfcber.txt"), b"\xfcber\n")):
+        full = os.path.join(os.fsencode(root), rel)
+        os.makedirs(os.path.dirname(full), exist_ok=True)
+        with open(full, "wb") as fh:
+            fh.write(data)
+        os.utime(full, (_SRC_MTIME, _SRC_MTIME))
+
+
+CORPORA: Dict[str, Callable[[str], None]] = {
+    "basic": corpus_basic,
+    "unicode": corpus_unicode,
+    "links": corpus_links,
+    "hardlinks": corpus_hardlinks,
+    "sparse": corpus_sparse,
+    "filters": corpus_filters,
+    "empty_dir": corpus_empty_dir,
+    "relative": corpus_relative,
+    "iconv": corpus_iconv,
+}
+
+
+# ---------------------------------------------------------------------------
+# Tree snapshotting / comparison
+# ---------------------------------------------------------------------------
+
+def snapshot(root: str, compare_modes: bool = False) -> Dict[str, tuple]:
+    """Map relative path -> descriptor for every entry below ``root``.
+
+    Files hash their contents with SHA-256 (structural comparison, so differing
+    quick-check metadata cannot mask a payload difference).  Symlinks record
+    their target.  Empty directories are included (as ``("dir", ...)``) so the
+    recursive-empty-directory residual is observable.
+    """
+    out: Dict[str, tuple] = {}
+    if not os.path.isdir(root):
+        return out
+
+    def describe(path: str) -> Optional[tuple]:
+        st = os.lstat(path)
+        if os.path.islink(path):
+            return ("link", os.readlink(path))
+        if os.path.isdir(path):
+            mode = oct(st.st_mode & 0o7777) if compare_modes else None
+            return ("dir", mode)
+        h = hashlib.sha256()
+        with open(path, "rb") as fh:
+            for chunk in iter(lambda: fh.read(65536), b""):
+                h.update(chunk)
+        mode = oct(st.st_mode & 0o7777) if compare_modes else None
+        return ("file", h.hexdigest()[:16], mode)
+
+    # The comparison root itself is not part of the tree diff: a no-transfer
+    # result legitimately leaves FastSync's mirror directory absent while rsync
+    # leaves an existing (empty) destination root.
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames.sort()
+        for name in sorted(dirnames):
+            p = os.path.join(dirpath, name)
+            rel = os.path.relpath(p, root)
+            if os.path.islink(p):
+                out[rel] = ("link", os.readlink(p))
+                dirnames.remove(name)
+            else:
+                out[rel] = describe(p)
+        for name in sorted(filenames):
+            p = os.path.join(dirpath, name)
+            out[os.path.relpath(p, root)] = describe(p)
+    return out
+
+
+def _hardlink_groups(root: str) -> Dict[str, str]:
+    """Assign a stable group letter to each inode shared by >1 regular file."""
+    inodes: Dict[tuple, List[str]] = {}
+    for dirpath, _dirs, filenames in os.walk(root, followlinks=False):
+        for name in filenames:
+            p = os.path.join(dirpath, name)
+            if os.path.islink(p):
+                continue
+            st = os.lstat(p)
+            if st.st_nlink > 1:
+                inodes.setdefault((st.st_dev, st.st_ino), []).append(
+                    os.path.relpath(p, root))
+    groups: Dict[str, str] = {}
+    for i, (_key, members) in enumerate(sorted(inodes.items())):
+        for rel in members:
+            groups[rel] = chr(ord("A") + i)
+    return groups
+
+
+def _drop_ignored(tree: Dict[str, tuple], ignore_paths) -> Dict[str, tuple]:
+    if not ignore_paths:
+        return tree
+    out = {}
+    for rel, desc in tree.items():
+        if any(rel == ig or rel.startswith(ig.rstrip("/") + "/") for ig in ignore_paths):
+            continue
+        out[rel] = desc
+    return out
+
+
+def tree_diff(rsync_root: str, fs_root: str, case: Case) -> List[str]:
+    """Return a list of human-readable differences (empty when identical)."""
+    rtree = _drop_ignored(snapshot(rsync_root, case.compare_modes), case.ignore_paths)
+    ftree = _drop_ignored(snapshot(fs_root, case.compare_modes), case.ignore_paths)
+    if case.compare_hardlinks:
+        rgroups = _hardlink_groups(rsync_root)
+        fgroups = _hardlink_groups(fs_root)
+    else:
+        rgroups = fgroups = {}
+    diffs: List[str] = []
+    for rel in sorted(set(rtree) | set(ftree)):
+        r = rtree.get(rel)
+        f = ftree.get(rel)
+        if r == f:
+            continue
+        if r is None:
+            diffs.append(f"+ fastsync-only: {rel!r} {f}")
+        elif f is None:
+            diffs.append(f"- rsync-only:    {rel!r} {r}")
+        else:
+            diffs.append(f"~ differs:       {rel!r} rsync={r} fastsync={f}")
+    if case.compare_hardlinks:
+        for rel in sorted(set(rgroups) | set(fgroups)):
+            if rgroups.get(rel) != fgroups.get(rel):
+                diffs.append(
+                    f"~ hardlink group: {rel!r} rsync={rgroups.get(rel)} "
+                    f"fastsync={fgroups.get(rel)}")
+    return diffs
+
+
+# ---------------------------------------------------------------------------
+# stdout normalization
+# ---------------------------------------------------------------------------
+
+def _parse_bytes(text: str) -> str:
+    m = re.match(r"([\d,]+)", text.strip())
+    return m.group(1).replace(",", "") if m else text.strip()
+
+
+def normalize_stdout(text: str, mode: Optional[str]) -> object:
+    if mode == STDOUT_ITEMIZE:
+        lines = []
+        for line in (text or "").splitlines():
+            line = line.rstrip()
+            if not line:
+                continue
+            if line.startswith("*deleting"):
+                lines.append(line)
+                continue
+            if not _ITEMIZE_RE.match(line):
+                continue
+            # Directories are not transfer entries in FastSync's recursive
+            # scanner, so rsync's `cd+++++++++ name/` lines have no counterpart
+            # (documented recursive-empty-dir residual).  Compare file/link
+            # itemization only.
+            if line.rsplit(" ", 1)[-1].endswith("/"):
+                continue
+            lines.append(line)
+        return sorted(lines)
+    if mode == STDOUT_OUTFMT:
+        lines = []
+        for line in (text or "").splitlines():
+            line = line.rstrip()
+            if not line:
+                continue
+            # Directory entries are emitted by rsync but not by FastSync's
+            # recursive scanner (documented residual).  Tokens are either
+            # `%n %l` (path first) or `%i %n` (path last); drop a line when
+            # either end-token is a directory path.
+            first = line.split(" ", 1)[0]
+            last = line.rsplit(" ", 1)[-1]
+            if first.endswith("/") or last.endswith("/"):
+                continue
+            lines.append(line)
+        return sorted(lines)
+    if mode == STDOUT_STATS:
+        found = {}
+        for line in (text or "").splitlines():
+            for key in STATS_KEYS:
+                if line.startswith(key + ":"):
+                    found[key] = _parse_bytes(line.split(":", 1)[1])
+        return found
+    # raw
+    return sorted(l.rstrip() for l in (text or "").splitlines() if l.strip())
+
+
+def stdout_diff(rsync_out: str, fs_out: str, mode: Optional[str]) -> List[str]:
+    r = normalize_stdout(rsync_out, mode)
+    f = normalize_stdout(fs_out, mode)
+    if r == f:
+        return []
+    if mode == STDOUT_STATS:
+        return [f"stats rsync={r}", f"stats fastsync={f}"]
+    return list(difflib.unified_diff(
+        [str(x) for x in r], [str(x) for x in f],
+        fromfile="rsync", tofile="fastsync", lineterm=""))
+
+
+# ---------------------------------------------------------------------------
+# Running one case
+# ---------------------------------------------------------------------------
+
+def run_rsync(src: str, rdst: str, flags: List[str]) -> subprocess.CompletedProcess:
+    args = [RSYNC] + list(flags) + [src + "/", rdst + "/"]
+    return subprocess.run(
+        args, capture_output=True, text=True,
+        env=dict(os.environ, LC_ALL="C"), timeout=180)
+
+
+def run_fastsync(src: str, fdst: str, flags: List[str], port: int):
+    return run_client(src, fdst, flags=list(flags), port=port)
+
+
+def run_differential(  # noqa: PLR0913 (explicit scenario parameters)
+    src: str,
+    rdst: str,
+    fdst: str,
+    rs_flags: List[str],
+    fs_flags: List[str],
+    server,
+    layout: str = MIRROR,
+    seed: Optional[Callable] = None,
+    stdout: Optional[str] = STDOUT_NONE,
+    compare_modes: bool = False,
+    compare_hardlinks: bool = False,
+    ignore_paths: Tuple[str, ...] = (),
+    extra_check: Optional[Callable] = None,
+    files_from: Optional[Tuple[str, ...]] = None,
+    fs_src_suffix: str = "",
+) -> Dict[str, object]:
+    """Run one rsync/FastSync pair and return the diff aspects.
+
+    Returned dict keys: ``rsync_rc``, ``fastsync_rc``, ``rsync_stderr``,
+    ``fastsync_stderr``, ``tree``, ``stdout``, ``extra``.
+    """
+    clean_dir(rdst)
+    clean_dir(fdst)
+    abs_src = os.path.abspath(src)
+    rel = abs_src.lstrip(os.sep)
+    if layout == RELATIVE:
+        rroot, froot = rdst, fdst
+    elif layout == MIRROR_ABS:
+        rroot, froot = os.path.join(rdst, rel), get_dest_received_dir(fdst, src)
+    else:
+        rroot, froot = rdst, get_dest_received_dir(fdst, src)
+    if seed:
+        seed(src, rroot, froot)
+
+    rs_flags = list(rs_flags)
+    fs_flags = list(fs_flags)
+    if files_from is not None:
+        list_path = os.path.join(TEST_DATA_DIR, "parity_" +
+                                 os.path.basename(src) + ".list")
+        write_list(list_path, files_from)
+        rs_flags.append(f"--files-from={list_path}")
+        fs_flags.append(f"--files-from={list_path}")
+
+    rs = run_rsync(src, rdst, rs_flags)
+    fs_result, _ = run_fastsync(src + fs_src_suffix, fdst, fs_flags, server.port)
+
+    class _View:
+        """Adapter so tree_diff/extra_check keep the Case-shaped interface."""
+
+        def __init__(self) -> None:
+            self.compare_modes = compare_modes
+            self.compare_hardlinks = compare_hardlinks
+            self.ignore_paths = ignore_paths
+
+    result = {
+        "rsync_rc": rs.returncode,
+        "fastsync_rc": fs_result.returncode,
+        "rsync_stderr": rs.stderr,
+        "fastsync_stderr": fs_result.stderr or fs_result.stdout,
+        "tree": tree_diff(rroot, froot, _View()),
+        "stdout": [],
+        "extra": [],
+    }
+    if stdout is not None:
+        result["stdout"] = stdout_diff(rs.stdout, fs_result.stdout, stdout)
+    if extra_check:
+        result["extra"] = list(extra_check(src, rroot, froot, rs, fs_result) or [])
+    return result
+
+
+def execute_case(case: Case, server) -> Dict[str, object]:
+    """Run a table-driven case and return the diff aspects."""
+    tag = case.id
+    src = os.path.join(TEST_DATA_DIR, f"parity_{tag}_src")
+    rdst = os.path.join(TEST_DATA_DIR, f"parity_{tag}_rdst")
+    fdst = os.path.join(TEST_DATA_DIR, f"parity_{tag}_fdst")
+    CORPORA[case.corpus](src)
+    return run_differential(
+        src, rdst, fdst,
+        case.flags, case.fs_flags(), server,
+        layout=case.layout, seed=case.seed, stdout=case.stdout,
+        compare_modes=case.compare_modes, compare_hardlinks=case.compare_hardlinks,
+        ignore_paths=case.ignore_paths, extra_check=case.extra_check,
+        files_from=case.files_from, fs_src_suffix=case.fs_src_suffix,
+    )
+
+
+def write_list(path: str, entries) -> str:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as fh:
+        for e in entries:
+            fh.write(e + "\n")
+    return path

tests/integration/test_differential_parity.py

@@ -0,0 +1,520 @@
+"""Differential rsync-parity gate.
+
+Runs real ``rsync 3.4.1`` and FastSync over the same corpora and flags, then
+compares the destination trees and the normalized output of the
+output-oriented flags.  This is the executable counterpart of
+``RSYNC_COMPAT.md``: the fast subset (``-m parity_ci``) guards the ✅ surface on
+every pull request, and the full set (``-m parity``) burns the documented
+⚠️/❌ residuals down.
+
+Known, documented differences live in ``parity_caveats.py``; anything else
+fails with a readable tree/stdout diff.  A stale allowlist entry is reported
+loudly (and fails when ``FASTSYNC_PARITY_STRICT=1``).
+
+Run locally::
+
+    python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity_ci
+    python3 -m pytest tests/integration/test_differential_parity.py -n 4 --dist=load -m parity
+"""
+import os
+import shutil
+import sys
+import warnings
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import (  # noqa: E402
+    ServerManager,
+    TEST_DATA_DIR,
+    clean_dir,
+)
+from parity_caveats import ASPECTS, caveat_for  # noqa: E402
+import parity_harness as H  # noqa: E402
+
+RSYNC = shutil.which("rsync")
+requires_rsync = pytest.mark.skipif(RSYNC is None, reason="rsync 3.4.1 not installed")
+
+# `--allow-super` matches the rest of the integration suite; `--allow-delete`
+# is needed only by the delete cases.
+SUPER = ("--allow-super",)
+DELETE = ("--allow-super", "--allow-delete")
+_OLD_MTIME = 1_500_000_000
+
+parity = pytest.mark.parity
+parity_ci = pytest.mark.parity_ci
+
+
+@pytest.fixture(scope="session")
+def parity_server_factory():
+    """Lazily start one server per distinct extra-argument set, per xdist worker."""
+    servers = {}
+
+    def get(extra):
+        key = tuple(extra)
+        if key not in servers:
+            s = ServerManager()
+            s.start(extra_args=list(extra))
+            servers[key] = s
+        return servers[key]
+
+    yield get
+    for s in servers.values():
+        s.stop()
+
+
+def _pin(path, mtime):
+    os.utime(path, (mtime, mtime))
+
+
+def _mk(path, data, mtime=None):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "wb") as fh:
+        fh.write(data)
+    if mtime is not None:
+        _pin(path, mtime)
+
+
+# --- destination seeds ------------------------------------------------------
+
+def seed_extras(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "extra.txt"), b"extra\n")
+        _mk(os.path.join(root, "extradir", "z.txt"), b"z\n")
+
+
+def seed_update(_src, rroot, froot):
+    for root in (rroot, froot):
+        p = os.path.join(root, "a.txt")
+        _mk(p, b"destination is newer and longer\n", 2_000_000_000)
+
+
+def seed_ignore_existing(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "a.txt"), b"destination-kept\n", _OLD_MTIME)
+
+
+def seed_append(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "a.txt"), b"hello ", _OLD_MTIME)
+
+
+def seed_backup(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "a.txt"), b"OLD-CONTENT\n", _OLD_MTIME)
+
+
+def seed_size_only(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "a.txt"), b"XXXXXXXXXXX\n", _OLD_MTIME)
+
+
+def seed_delete_excluded(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "drop.log"), b"stale log\n", _OLD_MTIME)
+        _mk(os.path.join(root, "extra.txt"), b"extra\n", _OLD_MTIME)
+        _mk(os.path.join(root, "keep.txt"), b"keep\n", _OLD_MTIME)
+
+
+def seed_max_delete(_src, rroot, froot):
+    for root in (rroot, froot):
+        _mk(os.path.join(root, "extra1.txt"), b"e1\n", _OLD_MTIME)
+        _mk(os.path.join(root, "extra2.txt"), b"e2\n", _OLD_MTIME)
+
+
+def max_delete_count_check(_src, rroot, froot, _rs, _fs):
+    """The exact survivor set is order-dependent; the count must still match."""
+    r = H.snapshot(rroot)
+    f = H.snapshot(froot)
+    if len(r) != len(f):
+        return [f"survivor count differs: rsync={len(r)} fastsync={len(f)}"]
+    return []
+
+
+# --- case table -------------------------------------------------------------
+
+_CASES = [
+    # --- core archive / recursion -----------------------------------------
+    H.Case("archive", "basic", ["-a"], ci=True, ref="-a/--archive"),
+    H.Case("recursive", "basic", ["-r"], ci=True, ref="-r/--recursive"),
+    H.Case("unicode_names", "unicode", ["-a"], ci=True, ref="-a unicode names"),
+    H.Case("links_archive", "links", ["-a"], ci=True, ref="-l/--links"),
+    H.Case("copy_links", "links", ["-aL"], ref="-L/--copy-links"),
+    H.Case("hardlinks", "hardlinks", ["-a", "-H"], compare_hardlinks=True,
+           ci=True, ref="-H/--hard-links"),
+    H.Case("hardlinks_without_H", "hardlinks", ["-a"], compare_hardlinks=True,
+           ref="hardlinks without -H"),
+    H.Case("sparse", "sparse", ["-a", "-S"], ref="-S/--sparse"),
+
+    # --- compression / checksums ------------------------------------------
+    H.Case("compress_zstd", "basic", ["-a", "-z"], ci=True, ref="-z/--compress"),
+    H.Case("checksum", "basic", ["-a", "-c"], ref="-c/--checksum"),
+    H.Case("checksum_choice_xxh64", "basic",
+           ["-a", "-c", "--checksum-choice=xxh64"], ref="--checksum-choice"),
+
+    # --- selection --------------------------------------------------------
+    H.Case("exclude", "filters", ["-a", "--exclude=*.log"], ci=True,
+           ref="--exclude"),
+    H.Case("include_exclude", "filters",
+           ["-a", "--include=*.txt", "--exclude=*"], ci=True,
+           ref="--include/--exclude ordering"),
+    H.Case("filter_rules", "filters",
+           ["-a", "-f", "- *.log", "-f", "+ *.txt", "-f", "- *"],
+           ref="--filter/-f grammar"),
+    H.Case("max_size", "basic", ["-a", "--max-size=1000"], ref="--max-size"),
+    H.Case("min_size", "basic", ["-a", "--min-size=1000"], ref="--min-size"),
+
+    # --- output-oriented --------------------------------------------------
+    H.Case("stats", "basic", ["-a", "--stats"], stdout=H.STDOUT_STATS,
+           ci=True, ref="--stats"),
+    H.Case("itemize", "links", ["-a", "-i"], stdout=H.STDOUT_ITEMIZE,
+           ci=True, ref="-i/--itemize-changes"),
+    H.Case("out_format_n_l", "basic", ["-a", "--out-format=%n %l"],
+           stdout=H.STDOUT_OUTFMT, ref="--out-format %n %l"),
+    H.Case("out_format_i_n", "basic", ["-a", "--out-format=%i %n"],
+           stdout=H.STDOUT_OUTFMT, ref="--out-format %i %n"),
+
+    # --- transfer modifications -------------------------------------------
+    H.Case("update", "basic", ["-a", "--update"], seed=seed_update,
+           ref="-u/--update"),
+    H.Case("ignore_existing", "basic", ["-a", "--ignore-existing"],
+           seed=seed_ignore_existing, ci=True, ref="--ignore-existing"),
+    H.Case("size_only", "basic",
+           ["-a", "--size-only"], fastsync_flags=["-a", "--incremental", "--size-only"],
+           seed=seed_size_only, ref="--size-only"),
+    H.Case("append", "basic", ["-a", "--append"], seed=seed_append,
+           ref="--append"),
+    H.Case("append_verify", "basic", ["-a", "--append-verify"], seed=seed_append,
+           ref="--append-verify"),
+    H.Case("backup", "basic", ["-a", "--backup"], seed=seed_backup,
+           ref="--backup"),
+    H.Case("chmod", "basic", ["-a", "--chmod=Fu+rwx"], compare_modes=True,
+           ci=True, ref="--chmod"),
+
+    # --- deletion ---------------------------------------------------------
+    H.Case("delete", "basic", ["-a", "--delete"], seed=seed_extras,
+           server_args=DELETE, ci=True, ref="--delete"),
+    H.Case("delete_before", "basic", ["-a", "--delete-before"], seed=seed_extras,
+           server_args=DELETE, ref="--delete-before"),
+    H.Case("delete_during", "basic", ["-a", "--delete-during"], seed=seed_extras,
+           server_args=DELETE, ref="--delete-during"),
+    H.Case("delete_delay", "basic", ["-a", "--delete-delay"], seed=seed_extras,
+           server_args=DELETE, ref="--delete-delay"),
+    H.Case("delete_after", "basic", ["-a", "--delete-after"], seed=seed_extras,
+           server_args=DELETE, ref="--delete-after"),
+    H.Case("delete_excluded", "filters",
+           ["-a", "--delete", "--delete-excluded", "--exclude=*.log"],
+           seed=seed_delete_excluded, server_args=DELETE, ref="--delete-excluded"),
+    H.Case("max_delete", "basic", ["-a", "--delete", "--max-delete=1"],
+           seed=seed_max_delete, server_args=DELETE,
+           extra_check=max_delete_count_check, ref="--max-delete"),
+
+    # --- relative / dirs --------------------------------------------------
+    H.Case("relative_general", "basic", ["-a", "-R"], layout=H.MIRROR_ABS,
+           compare_modes=True, ref="-R/--relative"),
+    H.Case("relative_no_implied_dirs", "basic",
+           ["-a", "-R", "--no-implied-dirs"], layout=H.MIRROR_ABS,
+           compare_modes=True, ref="--no-implied-dirs"),
+    H.Case("files_from", "relative", ["--dirs", "-R"],
+           files_from=("dir1", "sub/x.txt"), layout=H.RELATIVE, ci=True,
+           ref="-d/--dirs + --files-from"),
+    H.Case("dirs_plain", "basic", ["-d"], fs_src_suffix="/",
+           ref="-d/--dirs (plain)"),
+    H.Case("empty_dirs_recursive", "empty_dir", ["-a"],
+           ref="recursive empty-directory residual"),
+    H.Case("empty_dirs_files_from", "empty_dir", ["--dirs", "-R"],
+           files_from=("emptydir",), layout=H.RELATIVE, ci=True,
+           ref="-d/--dirs explicit empty directory"),
+
+    # --- codecs -----------------------------------------------------------
+    H.Case("iconv_identity", "basic", ["-a", "--iconv=UTF-8,UTF-8"],
+           ref="--iconv identity"),
+    H.Case("iconv_convert", "iconv",
+           ["-a", "--iconv=ISO-8859-1,UTF-8"],
+           server_args=("--allow-super", "--iconv=UTF-8"),
+           ref="--iconv conversion (receiver declares its own charset)"),
+    # rsync's spec is LOCAL,REMOTE and the destination end's charset is REMOTE
+    # on a push, so a default server writes the wire (UTF-8) names verbatim.
+    H.Case("iconv_default_server", "iconv",
+           ["-a", "--iconv=ISO-8859-1,UTF-8"],
+           ref="--iconv push direction (default receiver charset = REMOTE)"),
+
+    # --- partial ----------------------------------------------------------
+    H.Case("partial_complete", "basic", ["-a", "--partial"], ref="--partial"),
+]
+
+# Cases that must always be tolerated (documented ⚠️/❌ residuals) get an
+# allowlist entry; the table below stays the exact ✅ surface.
+ALL_CASES = _CASES
+
+
+def _params():
+    out = []
+    for case in ALL_CASES:
+        marks = [parity]
+        if case.ci:
+            marks.append(parity_ci)
+        out.append(pytest.param(case, id=case.id, marks=marks))
+    return out
+
+
+def _aspects_to_check(result):
+    return {
+        "tree": result["tree"],
+        "stdout": result["stdout"],
+        "extra": result["extra"],
+    }
+
+
+def _assert_no_unexpected(case_id, mismatches, caveat, ref=""):
+    unexpected = {a: v for a, v in mismatches.items() if v and a not in caveat}
+    if unexpected:
+        lines = [f"differential parity mismatch for case {case_id!r}:"]
+        lines.append(f"  ref: {ref or 'see RSYNC_COMPAT.md'}")
+        for aspect, detail in unexpected.items():
+            lines.append(f"  --- {aspect} ---")
+            lines.extend("  " + str(d) for d in detail)
+        lines.append("If this is a documented residual, add it to "
+                     "tests/integration/parity_caveats.py with a RSYNC_COMPAT.md "
+                     "reference.  Do not allowlist an undocumented divergence.")
+        pytest.fail("\n".join(lines))
+
+    stale = [a for a in ASPECTS
+             if a in caveat and a != "rc" and not mismatches.get(a)]
+    if stale:
+        msg = (f"stale parity allowlist entry for case {case_id!r}, aspect(s) "
+               f"{stale}: FastSync now matches rsync. Remove it from "
+               f"parity_caveats.py (and update RSYNC_COMPAT.md if the row moved).")
+        if os.environ.get("FASTSYNC_PARITY_STRICT") == "1":
+            pytest.fail(msg)
+        warnings.warn(msg, stacklevel=2)
+
+
+@requires_rsync
+@pytest.mark.parametrize("case", _params())
+def test_differential_case(case, parity_server_factory):
+    server = parity_server_factory(case.server_args)
+    result = H.execute_case(case, server)
+    caveat = caveat_for(case.id)
+
+    mismatches = _aspects_to_check(result)
+    if result["rsync_rc"] != result["fastsync_rc"]:
+        mismatches["rc"] = [
+            f"rsync rc={result['rsync_rc']} fastsync rc={result['fastsync_rc']} "
+            f"(rsync stderr: {result['rsync_stderr'][:200]!r}, "
+            f"fastsync stderr: {result['fastsync_stderr'][:200]!r})"]
+    _assert_no_unexpected(case.id, mismatches, caveat, ref=case.ref)
+
+
+# ---------------------------------------------------------------------------
+# Multi-run and setup-heavy scenarios (kept as explicit tests)
+# ---------------------------------------------------------------------------
+
+def _result_aspects(result):
+    return _aspects_to_check(result)
+
+
+_STANDALONE_REFS = {
+    "incremental_modified": "-i/--itemize-changes + incremental second run",
+    "compare_dest": "--compare-dest",
+    "link_dest": "--link-dest",
+    "added_and_deleted": "--delete across two runs",
+    "added_and_deleted_seed": "--delete across two runs",
+    "one_file_system": "-x/--one-file-system",
+}
+
+
+def _run_and_check(case_id, result, ref=""):
+    mismatches = _result_aspects(result)
+    if result["rsync_rc"] != result["fastsync_rc"]:
+        mismatches["rc"] = [
+            f"rsync rc={result['rsync_rc']} fastsync rc={result['fastsync_rc']} "
+            f"(rsync stderr: {result['rsync_stderr'][:200]!r}, "
+            f"fastsync stderr: {result['fastsync_stderr'][:200]!r})"]
+    _assert_no_unexpected(case_id, mismatches, caveat_for(case_id),
+                          ref=ref or _STANDALONE_REFS.get(case_id, ""))
+
+
+@requires_rsync
+@parity
+def test_incremental_modified_file(parity_server_factory):
+    """A second run sends only the modified file; destinations stay identical."""
+    case_id = "incremental_modified"
+    src = os.path.join(TEST_DATA_DIR, "parity_inc_src")
+    rdst = os.path.join(TEST_DATA_DIR, "parity_inc_rdst")
+    fdst = os.path.join(TEST_DATA_DIR, "parity_inc_fdst")
+    H.CORPORA["basic"](src)
+    server = parity_server_factory(SUPER)
+
+    # Seed both destinations with the initial content.
+    H.run_differential(src, rdst, fdst, ["-a"], ["-a"], server,
+                       extra_check=lambda *a: [])
+    with open(os.path.join(src, "a.txt"), "wb") as fh:
+        fh.write(b"hello world, now modified and longer\n")
+    _pin(os.path.join(src, "a.txt"), 1_650_000_000)
+
+    result = H.run_differential(
+        src, rdst, fdst, ["-a", "-i"], ["-a", "-i", "--incremental"], server,
+        stdout=H.STDOUT_ITEMIZE)
+    _run_and_check(case_id, result)
+
+
+def _seed_basis(rel_entries):
+    def seed(src, rroot, froot):
+        for root in (rroot, froot):
+            os.makedirs(root, exist_ok=True)
+            for rel, data in rel_entries.items():
+                _mk(os.path.join(root, rel), data)
+    return seed
+
+
+@requires_rsync
+@parity
+def test_compare_dest_skips_basis(parity_server_factory):
+    """--compare-dest: a file present in the basis is not copied."""
+    case_id = "compare_dest"
+    src = os.path.join(TEST_DATA_DIR, "parity_cmpd_src")
+    rdst = os.path.join(TEST_DATA_DIR, "parity_cmpd_rdst")
+    fdst = os.path.join(TEST_DATA_DIR, "parity_cmpd_fdst")
+    clean_dir(src)
+    _mk(os.path.join(src, "f.txt"), b"basis-content\n")
+    server = parity_server_factory(SUPER)
+    rel = os.path.abspath(src).lstrip(os.sep)
+
+    # rsync resolves --compare-dest relative to the destination dir; FastSync
+    # resolves it under the receive root and appends the mirrored source path.
+    def seed(_src, rroot, froot):
+        _mk(os.path.join(rroot, "basis", "f.txt"), b"basis-content\n")
+        _mk(os.path.join(fdst, "basis", rel, "f.txt"), b"basis-content\n")
+
+    def extra(_src, rroot, froot, _rs, _fs):
+        out = []
+        for label, root in (("rsync", rroot), ("fastsync", froot)):
+            if os.path.exists(os.path.join(root, "f.txt")):
+                out.append(f"{label} copied a file that is present in the "
+                           f"compare basis")
+        return out
+
+    result = H.run_differential(
+        src, rdst, fdst,
+        ["-a", "--compare-dest=basis"],
+        ["-a", f"--compare-dest={os.path.join(fdst, 'basis')}", "--incremental"],
+        server, seed=seed, ignore_paths=("basis",), extra_check=extra)
+    _run_and_check(case_id, result)
+
+
+@requires_rsync
+@parity
+def test_link_dest_hardlinks_basis(parity_server_factory):
+    """--link-dest: an unchanged file is hard-linked to the basis, not copied."""
+    case_id = "link_dest"
+    src = os.path.join(TEST_DATA_DIR, "parity_linkd_src")
+    rdst = os.path.join(TEST_DATA_DIR, "parity_linkd_rdst")
+    fdst = os.path.join(TEST_DATA_DIR, "parity_linkd_fdst")
+    clean_dir(src)
+    _mk(os.path.join(src, "f.txt"), b"link-basis-content\n")
+    server = parity_server_factory(SUPER)
+    rel = os.path.abspath(src).lstrip(os.sep)
+
+    def seed(_src, rroot, froot):
+        _mk(os.path.join(rroot, "basis", "f.txt"), b"link-basis-content\n")
+        _mk(os.path.join(fdst, "basis", rel, "f.txt"), b"link-basis-content\n")
+
+    def extra(_src, rroot, froot, _rs, _fs):
+        r_basis = os.stat(os.path.join(rroot, "basis", "f.txt")).st_ino
+        f_basis = os.stat(os.path.join(fdst, "basis", rel, "f.txt")).st_ino
+        out = []
+        for label, root, basis in (("rsync", rroot, r_basis),
+                                   ("fastsync", froot, f_basis)):
+            target = os.path.join(root, "f.txt")
+            if not os.path.exists(target):
+                out.append(f"{label}: f.txt missing")
+            elif os.stat(target).st_ino != basis:
+                out.append(f"{label}: f.txt is not hard-linked to the basis")
+        return out
+
+    result = H.run_differential(
+        src, rdst, fdst,
+        ["-a", "--link-dest=basis"],
+        ["-a", f"--link-dest={os.path.join(fdst, 'basis')}", "--incremental"],
+        server, seed=seed, ignore_paths=("basis",), extra_check=extra)
+    _run_and_check(case_id, result)
+
+
+@requires_rsync
+@parity
+def test_added_and_deleted_between_runs(parity_server_factory):
+    """A source deletion and addition sync correctly under --delete."""
+    case_id = "added_and_deleted"
+    src = os.path.join(TEST_DATA_DIR, "parity_addel_src")
+    rdst = os.path.join(TEST_DATA_DIR, "parity_addel_rdst")
+    fdst = os.path.join(TEST_DATA_DIR, "parity_addel_fdst")
+    server = parity_server_factory(DELETE)
+    H.CORPORA["basic"](src)
+
+    seed = seed_extras
+    result = H.run_differential(
+        src, rdst, fdst, ["-a", "--delete"], ["-a", "--delete"], server,
+        seed=seed)
+    _run_and_check(case_id + "_seed", result)
+
+    os.remove(os.path.join(src, "a.txt"))
+    _mk(os.path.join(src, "added.txt"), b"added between runs\n")
+    result = H.run_differential(
+        src, rdst, fdst, ["-a", "--delete", "-i"],
+        ["-a", "--delete", "-i", "--incremental"], server,
+        stdout=H.STDOUT_ITEMIZE)
+    _run_and_check(case_id, result)
+
+
+@requires_rsync
+@parity
+def test_one_file_system(parity_server_factory):
+    """-x emits the mount-point directory but not its contents."""
+    case_id = "one_file_system"
+    local = os.stat(".")
+    shm = "/dev/shm"
+    if not os.path.isdir(shm):
+        pytest.skip("/dev/shm not available")
+    if os.stat(shm).st_dev == local.st_dev:
+        pytest.skip("no cross-device filesystem available")
+
+    src = os.path.join(TEST_DATA_DIR, "parity_ofs_src")
+    rdst = os.path.join(TEST_DATA_DIR, "parity_ofs_rdst")
+    fdst = os.path.join(TEST_DATA_DIR, "parity_ofs_fdst")
+    clean_dir(src)
+    _mk(os.path.join(src, "keep.txt"), b"keep\n")
+    probe = os.path.join(shm, f"fastsync_ofs_{os.getpid()}")
+    shutil.rmtree(probe, ignore_errors=True)
+    os.makedirs(probe)
+    _mk(os.path.join(probe, "inside.txt"), b"cross\n")
+    try:
+        os.symlink(probe, os.path.join(src, "nested_link"))
+        server = parity_server_factory(SUPER)
+        result = H.run_differential(
+            src, rdst, fdst,
+            ["-a", "--copy-links", "-x"],
+            ["-a", "--copy-links", "-x"], server)
+        _run_and_check(case_id, result)
+    finally:
+        shutil.rmtree(probe, ignore_errors=True)
+
+
+@requires_rsync
+@parity
+def test_parity_caveats_reference_known_cases():
+    """Every allowlist entry must name a real case id and aspect."""
+    from parity_caveats import CAVEATS
+    known = {c.id for c in ALL_CASES} | {
+        "incremental_modified", "compare_dest", "link_dest",
+        "added_and_deleted", "added_and_deleted_seed", "one_file_system",
+    }
+    problems = []
+    for case_id, entry in CAVEATS.items():
+        if case_id not in known:
+            problems.append(f"unknown case id in parity_caveats.py: {case_id!r}")
+        for aspect in entry:
+            if aspect not in ASPECTS:
+                problems.append(
+                    f"{case_id!r}: unknown aspect {aspect!r} (expected {ASPECTS})")
+    assert not problems, "\n".join(problems)

tests/integration/test_features.py

@@ -583,6 +583,55 @@ class TestRemoteDryRun:
             assert os.path.exists(extra), f"{flags} deleted an extra in dry-run"
             assert _snapshot_tree(received) == before, f"{flags} mutated the destination"
 
+    @pytest.mark.skipif(shutil.which("rsync") is None, reason="rsync not installed")
+    def test_dry_run_delete_lines_over_report_residual(self):
+        """Documented residual (RSYNC_COMPAT.md `-n/--dry-run` row): FastSync's
+        dry-run would-delete report includes the file that is merely being
+        updated (derived from the receiver's STATUS_STATS extras) and, unlike
+        rsync, also reports an excluded-but-protected extra.  rsync `-n -i
+        --delete` lists only genuine extras.  Pins the residual that keeps the
+        row Divergent."""
+        source = os.path.join(TEST_DATA_DIR, "dryrep_src")
+        rdst = os.path.join(TEST_DATA_DIR, "dryrep_rdst")
+        fdst = os.path.join(TEST_DATA_DIR, "dryrep_fdst")
+        clean_dir(source)
+        clean_dir(rdst)
+        clean_dir(fdst)
+        with open(os.path.join(source, "a.txt"), "wb") as fh:
+            fh.write(b"new content\n")
+        os.utime(os.path.join(source, "a.txt"), (1_700_000_000, 1_700_000_000))
+        for root in (rdst, fdst):
+            with open(os.path.join(root, "a.txt"), "wb") as fh:
+                fh.write(b"old\n")
+            for name, data in (("extra.log", b"log\n"), ("extra.txt", b"extra\n")):
+                with open(os.path.join(root, name), "wb") as fh:
+                    fh.write(data)
+            for p in (os.path.join(root, "a.txt"), os.path.join(root, "extra.log"),
+                      os.path.join(root, "extra.txt")):
+                os.utime(p, (1_500_000_000, 1_500_000_000))
+
+        r = subprocess.run(["rsync", "-an", "-i", "--delete", "--exclude=*.log",
+                            source + "/", rdst + "/"],
+                           capture_output=True, text=True,
+                           env=dict(os.environ, LC_ALL="C"))
+        assert r.returncode == 0, r.stderr
+        rsync_del = {l.split(None, 1)[1] for l in r.stdout.splitlines()
+                     if l.startswith("*deleting")}
+        assert rsync_del == {"extra.txt"}, f"unexpected rsync deleting set: {rsync_del}"
+
+        with ServerManager() as server:
+            server.start(extra_args=["--allow-delete"])
+            result, _ = run_client(source, fdst,
+                                   flags=["-a", "-n", "-i", "--delete", "--exclude=*.log"],
+                                   port=server.port)
+        assert result.returncode == 0, (result.stderr or result.stdout)[:300]
+        fs_del = {l.split(None, 1)[1] for l in (result.stdout or "").splitlines()
+                  if l.startswith("*deleting")}
+        # Documented over-report: the transferred/updated file and the excluded
+        # extra appear in FastSync's would-delete set.
+        assert "a.txt" in fs_del, "residual changed: FastSync no longer over-reports the update"
+        assert "extra.log" in fs_del, "residual changed: FastSync no longer reports excluded extra"
+
     @pytest.mark.ci
     def test_remote_dry_run_quiet_is_silent(self, shared_server):
         source = os.path.join(TEST_DATA_DIR, "remote_dry_quiet_src")
@@ -2376,6 +2425,61 @@ class TestTempDir:
         assert not mismatches, f"Mismatch: {mismatches}"
         self._assert_clean_scratch(os.path.join(dest, "scratch"))
 
+    @pytest.mark.skipif(shutil.which("rsync") is None, reason="rsync not installed")
+    def test_relative_temp_dir_matches_rsync_absolute_rejected(self):
+        """Differential: a relative --temp-dir is resolved under the destination
+        by both (rsync 3.4.1 and FastSync), producing identical trees.  An
+        absolute --temp-dir is used verbatim by rsync standalone, but the
+        receiver deliberately confines it to the receive root (security
+        invariant), so FastSync rejects it without writing outside the root.
+        """
+        source = self._make_source("tempdir_diff_src")
+        rdst = os.path.join(TEST_DATA_DIR, "tempdir_diff_rdst")
+        fdst = os.path.join(TEST_DATA_DIR, "tempdir_diff_fdst")
+        clean_dir(rdst)
+        clean_dir(fdst)
+        os.makedirs(os.path.join(rdst, "scratch"), exist_ok=True)
+        os.makedirs(os.path.join(fdst, "scratch"), exist_ok=True)
+        r = subprocess.run(["rsync", "-a", "--temp-dir=scratch", source + "/", rdst + "/"],
+                           capture_output=True, text=True,
+                           env=dict(os.environ, LC_ALL="C"))
+        assert r.returncode == 0, r.stderr
+        with ServerManager() as server:
+            server.start()
+            result, _ = run_client(source, fdst, flags=["--temp-dir=scratch"],
+                                   port=server.port)
+        assert result.returncode == 0, (result.stderr or result.stdout)[:300]
+        # rsync lays the source contents directly in rdst; FastSync mirrors the
+        # absolute source path below fdst.  Compare the mirrored content trees
+        # (the scratch dir lives at each destination root).
+        rtree = sorted(os.path.relpath(os.path.join(dp, n), rdst)
+                       for dp, dn, fn in os.walk(rdst)
+                       for n in dn + fn if os.path.join(dp, n) != os.path.join(rdst, "scratch"))
+        mirror = get_dest_received_dir(fdst, source)
+        ftree = sorted(os.path.relpath(os.path.join(dp, n), mirror)
+                       for dp, dn, fn in os.walk(mirror) for n in dn + fn)
+        assert rtree == ftree, f"relative temp-dir tree mismatch: {rtree} != {ftree}"
+        assert _walk_tmp_files(os.path.join(rdst, "scratch")) == []
+        assert _walk_tmp_files(os.path.join(fdst, "scratch")) == []
+
+        # Absolute temp dir: rsync accepts it; FastSync rejects it safely.
+        abs_scratch = os.path.join(TEST_DATA_DIR, "tempdir_diff_abs")
+        clean_dir(abs_scratch)
+        rdst2 = os.path.join(TEST_DATA_DIR, "tempdir_diff_rdst2")
+        clean_dir(rdst2)
+        r2 = subprocess.run(["rsync", "-a", "--temp-dir=" + abs_scratch, source + "/", rdst2 + "/"],
+                            capture_output=True, text=True,
+                            env=dict(os.environ, LC_ALL="C"))
+        assert r2.returncode == 0, r2.stderr
+        fdst2 = os.path.join(TEST_DATA_DIR, "tempdir_diff_fdst2")
+        clean_dir(fdst2)
+        with ServerManager() as server:
+            server.start()
+            result2, _ = run_client(source, fdst2, flags=["--temp-dir", abs_scratch],
+                                    port=server.port)
+        assert result2.returncode != 0, "an absolute --temp-dir must be rejected (confined)"
+        assert os.listdir(abs_scratch) == [], "receiver wrote into an unconfined temp dir"
+
     def test_default_behavior_has_no_scratch_dir(self, shared_server):
         source = self._make_source("tempdir_default_src")
         dest = os.path.join(TEST_DATA_DIR, "tempdir_default_dst")
@@ -2837,6 +2941,41 @@ class TestDelayUpdates:
         assert not os.path.isdir(os.path.join(delay_dest, self.STAGING)), \
             "staging directory left behind after a successful delayed transfer"
 
+    @pytest.mark.skipif(shutil.which("rsync") is None, reason="rsync not installed")
+    def test_delay_updates_staging_name_collision_residual(self):
+        """Documented residual (RSYNC_COMPAT.md `--delay-updates` row): FastSync
+        uses a fixed `.fastsync-stage` staging name and wipes a pre-existing tree
+        of that name at the start of a delayed run (crash-leftover cleanup),
+        even without `--delete`; rsync leaves a genuine destination entry of that
+        name untouched.  Pins the divergence that keeps the row Divergent."""
+        source = self._make_source("delay_collide_src")
+        rdst = os.path.join(TEST_DATA_DIR, "delay_collide_rdst")
+        fdst = os.path.join(TEST_DATA_DIR, "delay_collide_fdst")
+        clean_dir(rdst)
+        clean_dir(fdst)
+        for root in (rdst, fdst):
+            with open(os.path.join(root, "top.txt"), "wb") as fh:
+                fh.write(b"old\n")
+            stage = os.path.join(root, self.STAGING)
+            os.makedirs(stage, exist_ok=True)
+            with open(os.path.join(stage, "keepme.txt"), "wb") as fh:
+                fh.write(b"genuine user data\n")
+
+        r = subprocess.run(["rsync", "-a", "--delay-updates", source + "/", rdst + "/"],
+                           capture_output=True, text=True,
+                           env=dict(os.environ, LC_ALL="C"))
+        assert r.returncode == 0, r.stderr
+        assert os.path.exists(os.path.join(rdst, self.STAGING, "keepme.txt")), \
+            "rsync removed an unrelated destination entry named like the staging dir"
+
+        with ServerManager() as server:
+            server.start()
+            result, _ = run_client(source, fdst, flags=["--delay-updates"],
+                                   port=server.port)
+        assert result.returncode == 0, (result.stderr or result.stdout)[:300]
+        assert not os.path.exists(os.path.join(fdst, self.STAGING)), \
+            "FastSync did not wipe the reserved staging name (residual changed)"
+
     @pytest.mark.parametrize("mt", [False, True])
     def test_delay_updates_incremental_rerun_no_leftovers(self, shared_server, mt):
         source = self._make_source("delay_rerun_src")
@@ -3523,23 +3662,25 @@ class TestMissingArgs:
 
 
 class TestNoImpliedDirs:
-    """--no-implied-dirs (only meaningful with -R + --files-from) refuses to
-    place a listed file whose parent directory is not itself listed."""
+    """--no-implied-dirs (meaningful with -R) omits the source metadata of a
+    listed path's implied parent directories but still creates those parents
+    with default attributes, matching rsync 3.4.1."""
 
     def _make(self):
         return _make_relative_source("noimplied_src")
 
     @pytest.mark.parametrize("mt", [False, True])
-    def test_implied_dir_only_fails_entry(self, shared_server, mt):
+    def test_implied_dir_created_with_default_attrs(self, shared_server, mt):
         source = self._make()
         dest = os.path.join(TEST_DATA_DIR, "noimplied_dst")
         clean_dir(dest)
         lst = _write_rel_list(b"a/b.txt\n")  # "a" itself is not listed
         flags = ["--files-from", lst, "-R", "--no-implied-dirs"] + (["--threads"] if mt else [])
         result, _ = run_client(source, dest, flags=flags, port=shared_server.port)
-        assert result.returncode != 0, "implied parent directory was not rejected"
-        assert "--no-implied-dirs" in (result.stderr or result.stdout)
-        assert not os.path.exists(os.path.join(dest, "a", "b.txt"))
+        assert result.returncode == 0, \
+            f"implied parent directory was not created: {result.stderr[:200]}"
+        assert os.path.isdir(os.path.join(dest, "a")), "implied parent 'a' was not created"
+        assert _read_file(os.path.join(dest, "a", "b.txt")) == b"nested\n"
 
     @pytest.mark.parametrize("mt", [False, True])
     def test_listed_dir_allows_file(self, shared_server, mt):
@@ -3666,9 +3807,10 @@ class TestDirs:
                 files.extend(os.path.relpath(os.path.join(root, n), mirror) for n in names)
             assert files == [], f"--dirs descended into contents: {files}"
 
-    def test_dirs_listed_dir_colliding_with_file_fails(self, shared_server):
-        """A listed directory that already exists as a regular file at the
-        destination fails the transfer cleanly instead of clobbering the file."""
+    def test_dirs_listed_dir_replaces_blocking_file(self, shared_server):
+        """rsync parity: a listed directory replaces a regular file already at
+        its destination path (rsync removes the non-directory and creates the
+        directory)."""
         source = self._make()
         dest = os.path.join(TEST_DATA_DIR, "dirs_coll_dst")
         clean_dir(dest)
@@ -3678,8 +3820,10 @@ class TestDirs:
         lst = _write_rel_list(b"dir1\n")
         result, _ = run_client(source, dest, flags=["--files-from", lst, "--dirs", "-R"],
                                port=shared_server.port)
-        assert result.returncode != 0, "dir entry over an existing file did not fail"
-        assert os.path.isfile(blocker), "blocking regular file was clobbered"
+        assert result.returncode == 0, \
+            f"dir entry over an existing file failed: {(result.stderr or result.stdout)[:300]}"
+        assert os.path.isdir(blocker) and not os.path.islink(blocker), \
+            "blocking regular file was not replaced by the incoming directory"
 
 
 class TestMkpath:
@@ -6696,11 +6840,10 @@ class TestDirectoryAndSymlinkTimes:
 
     @pytest.mark.ci
     @pytest.mark.parametrize("mt", [False, True])
-    def test_preserve_does_not_create_empty_source_dir(self, shared_server, mt):
-        """P7 Wave D #1: a captured-but-EMPTY source directory is never created
-        at the destination.  The scanner records its time (it is transmitted via
-        STATUS_DIR_TIMES), but the receiver treats that entry as record-only, so
-        `-a` keeps the documented "empty dirs are never transferred" behavior."""
+    def test_preserve_creates_empty_source_dir(self, shared_server, mt):
+        """rsync parity: a recursive `-a` transfer recreates an empty source
+        directory at the destination (the scanner emits it as an explicit
+        directory entry)."""
         source = os.path.join(TEST_DATA_DIR, f"empty_dir_{'m' if mt else 's'}_src")
         dest = os.path.join(TEST_DATA_DIR, f"empty_dir_{'m' if mt else 's'}_dst")
         clean_dir(source)
@@ -6711,8 +6854,8 @@ class TestDirectoryAndSymlinkTimes:
         flags = ["-a"] + (["--threads"] if mt else [])
         received = self._run(source, dest, flags, shared_server)
         assert os.path.isfile(os.path.join(received, "keep.txt")), "regular file missing"
-        assert not os.path.lexists(os.path.join(received, "empty_sub")), \
-            f"-a created an empty source directory at {received}/empty_sub"
+        assert os.path.isdir(os.path.join(received, "empty_sub")), \
+            f"-a did not recreate the empty source directory at {received}/empty_sub"
 
     @pytest.mark.ci
     @pytest.mark.parametrize("mt", [False, True])
@@ -6735,10 +6878,10 @@ class TestDirectoryAndSymlinkTimes:
 
     @pytest.mark.ci
     @pytest.mark.parametrize("mt", [False, True])
-    def test_collision_at_dir_time_path_does_not_abort(self, shared_server, mt):
-        """P7 Wave D #1: a pre-existing regular file at a source-empty-dir's
-        mirror path must not abort the transfer (the old mkdir failed and failed
-        the run) and must not be clobbered."""
+    def test_collision_at_empty_dir_path_replaces_blocker(self, shared_server, mt):
+        """rsync parity: a pre-existing regular file at a source empty-dir's
+        mirror path is replaced by the incoming directory (rsync removes the
+        non-directory and creates the directory); the run succeeds."""
         source = os.path.join(TEST_DATA_DIR, f"dirtime_collide_{'m' if mt else 's'}_src")
         dest = os.path.join(TEST_DATA_DIR, f"dirtime_collide_{'m' if mt else 's'}_dst")
         clean_dir(source)
@@ -6757,10 +6900,8 @@ class TestDirectoryAndSymlinkTimes:
         assert result.returncode == 0, \
             f"-a aborted on a pre-existing file at an empty-dir path: " \
             f"{(result.stderr or result.stdout)[:400]}"
-        assert os.path.isfile(blocker) and not os.path.islink(blocker), \
-            "the pre-existing blocker was replaced by a directory"
-        with open(blocker, "rb") as fh:
-            assert fh.read() == b"pre-existing blocker\n", "the blocker file was clobbered"
+        assert os.path.isdir(blocker) and not os.path.islink(blocker), \
+            "the pre-existing blocker was not replaced by the incoming directory"
         assert os.path.isfile(os.path.join(received, "keep.txt")), "regular file missing"
 
 

tests/integration/test_iconv.py

@@ -1,10 +1,12 @@
 """--iconv=CONVERT_SPEC file-NAME charset conversion integration tests.
 
-The client converts every source file name from LOCAL to REMOTE before it goes
-on the wire, and the receiver converts it back from REMOTE to LOCAL, so a
-source tree using one charset can be written into a destination tree using
-another (rsync compatibility; content bytes are never touched).
+rsync's spec is ``--iconv=LOCAL,REMOTE`` (the order is the same push or pull).
+The sender converts each source name from LOCAL to REMOTE for the wire, and on
+a PUSH the receiver's charset is the spec's REMOTE half, so it writes the wire
+bytes verbatim (only a server with its own ``--iconv`` declares a different
+destination charset and re-converts).  Content bytes are never touched.
 """
+import codecs
 import os
 import shutil
 
@@ -16,6 +18,11 @@ LATIN1_NAME = b"caf\xe9.txt"
 UTF8_NAME = "caf\u00e9.txt".encode("utf-8")
 
 
+def _to_utf8(name_bytes):
+    """The UTF-8 encoding of a name that is stored as ISO-8859-1 bytes."""
+    return codecs.encode(codecs.decode(name_bytes, "iso-8859-1"), "utf-8")
+
+
 def _make(tag):
     source = os.path.join(TEST_DATA_DIR, f"iconv_{tag}_src")
     dest = os.path.join(TEST_DATA_DIR, f"iconv_{tag}_dst")
@@ -41,10 +48,10 @@ def _dest_file(source, dest, name):
 
 
 @pytest.mark.ci
-def test_iconv_latin1_roundtrip(shared_server):
-    """A source file whose name is ISO-8859-1 bytes is transferred with
-    --iconv=iso-8859-1,utf-8 and lands on the destination with the ORIGINAL
-    latin1 name (the wire carried it as UTF-8)."""
+def test_iconv_latin1_to_utf8_dest(shared_server):
+    """rsync push parity: --iconv=iso-8859-1,utf-8 converts a latin1 source name
+    to the spec's REMOTE (UTF-8) on the wire and the default receiver writes it
+    verbatim, so the destination name is UTF-8 (not the source's latin1)."""
     source, dest = _make("latin1")
     _place_bytes(source, LATIN1_NAME)
 
@@ -53,8 +60,10 @@ def test_iconv_latin1_roundtrip(shared_server):
     )
     assert result.returncode == 0, (result.stderr or result.stdout)[:400]
 
-    dst = _dest_file(source, dest, LATIN1_NAME)
-    assert os.path.exists(dst), f"dest latin1-named file not found under {dest}"
+    dst = _dest_file(source, dest, UTF8_NAME)
+    assert os.path.exists(dst), f"dest UTF-8-named file not found under {dest}"
+    assert not os.path.exists(_dest_file(source, dest, LATIN1_NAME)), \
+        "destination kept the latin1 name instead of the wire (UTF-8) charset"
 
 
 @pytest.mark.ci
@@ -153,7 +162,7 @@ def test_iconv_expanding_name_growth(shared_server):
     )
     assert result.returncode == 0, (result.stderr or result.stdout)[:400]
 
-    assert os.path.exists(_dest_file(source, dest, name_bytes))
+    assert os.path.exists(_dest_file(source, dest, _to_utf8(name_bytes)))
 
 
 def test_iconv_symlink_path_and_target(shared_server):
@@ -170,11 +179,13 @@ def test_iconv_symlink_path_and_target(shared_server):
     )
     assert result.returncode == 0, (result.stderr or result.stdout)[:400]
 
-    dst_target = _dest_file(source, dest, target)
-    dst_link = _dest_file(source, dest, b"link\xe9")
-    assert os.path.exists(dst_target), "dest latin1 target file missing"
-    assert os.path.islink(dst_link), "dest latin1 symlink missing"
-    assert os.readlink(dst_link) == target, "symlink target not preserved/decoded"
+    utf8_target = _to_utf8(target)
+    utf8_link = _to_utf8(b"link\xe9")
+    dst_target = _dest_file(source, dest, utf8_target)
+    dst_link = _dest_file(source, dest, utf8_link)
+    assert os.path.exists(dst_target), "dest UTF-8 target file missing"
+    assert os.path.islink(dst_link), "dest UTF-8 symlink missing"
+    assert os.readlink(dst_link) == utf8_target, "symlink target not wire-converted"
     with open(dst_link, "rb") as fh:
         assert fh.read() == b"t\n"
 
@@ -198,8 +209,8 @@ def test_iconv_hardlink_path_and_target(shared_server):
     )
     assert result.returncode == 0, (result.stderr or result.stdout)[:400]
 
-    dst_a = _dest_file(source, dest, a)
-    dst_b = _dest_file(source, dest, b)
+    dst_a = _dest_file(source, dest, _to_utf8(a))
+    dst_b = _dest_file(source, dest, _to_utf8(b))
     assert os.path.exists(dst_a) and os.path.exists(dst_b)
     assert os.stat(dst_a).st_ino == os.stat(dst_b).st_ino, \
         "hard-link relationship not preserved across the transfer"
@@ -221,16 +232,16 @@ def test_iconv_delete_manifest_consistent(shared_server):
         flags = ["--iconv=iso-8859-1,utf-8"]
         result, _ = run_client(source, dest, flags=flags, port=server.port)
         assert result.returncode == 0, (result.stderr or result.stdout)[:400]
-        assert os.path.exists(_dest_file(source, dest, keep))
-        assert os.path.exists(_dest_file(source, dest, gone))
+        assert os.path.exists(_dest_file(source, dest, _to_utf8(keep)))
+        assert os.path.exists(_dest_file(source, dest, _to_utf8(gone)))
 
         os.remove(os.path.join(os.fsencode(source), gone))
         result, _ = run_client(
             source, dest, flags=flags + ["--delete"], port=server.port
         )
         assert result.returncode == 0, (result.stderr or result.stdout)[:400]
-        assert os.path.exists(_dest_file(source, dest, keep)), "kept file deleted"
-        assert not os.path.exists(_dest_file(source, dest, gone)), \
+        assert os.path.exists(_dest_file(source, dest, _to_utf8(keep))), "kept file deleted"
+        assert not os.path.exists(_dest_file(source, dest, _to_utf8(gone))), \
             "missing file was not deleted"
 
 
@@ -247,4 +258,4 @@ def test_iconv_chunk_serialization_blob(shared_server):
     )
     assert result.returncode == 0, (result.stderr or result.stdout)[:400]
 
-    assert os.path.exists(_dest_file(source, dest, name))
+    assert os.path.exists(_dest_file(source, dest, _to_utf8(name)))

tests/integration/test_parity_quickwins.py

@@ -769,6 +769,47 @@ class TestVerifyAndFlip:
         assert os.stat(dest_file).st_ino == os.stat(basis_file).st_ino, \
             "--link-dest must hard-link to the basis file"
 
+    @requires_rsync
+    def test_basis_dir_size_only_content_residual(self, shared_server):
+        """Documented residual (RSYNC_COMPAT.md basis-dir rows): FastSync
+        xxHash-verifies a basis hit, while rsync's `--size-only` quick check
+        trusts the size alone.  With a same-size, different-content basis,
+        rsync links/copies the wrong basis content while FastSync transfers the
+        source.  This test pins both observed behaviors (FastSync is stricter,
+        so the rows are reclassified Divergent)."""
+        source = self._src("basissz")
+        rdest = self._dst("basissz_r")
+        fdest = self._dst("basissz_f")
+        with open(os.path.join(source, "f.txt"), "wb") as fh:
+            fh.write(b"AAAA\n")
+        OLD = 1_400_000_000
+        # rsync basis at the transfer-relative path (relative to the dest dir).
+        os.makedirs(os.path.join(rdest, "basis"), exist_ok=True)
+        with open(os.path.join(rdest, "basis", "f.txt"), "wb") as fh:
+            fh.write(b"BBBB\n")
+        os.utime(os.path.join(rdest, "basis", "f.txt"), (OLD, OLD))
+        rs = _rsync(["-a", "--size-only", "--link-dest=basis", source + "/", rdest + "/"])
+        assert rs.returncode == 0, rs.stderr
+        with open(os.path.join(rdest, "f.txt"), "rb") as fh:
+            assert fh.read() == b"BBBB\n", "rsync --size-only did not trust the basis size"
+
+        # FastSync basis is relative to the receive root; the file mirrors the
+        # source path.
+        rel = os.path.abspath(source).lstrip(os.sep)
+        basis = os.path.join(fdest, "basis", rel)
+        os.makedirs(basis, exist_ok=True)
+        with open(os.path.join(basis, "f.txt"), "wb") as fh:
+            fh.write(b"BBBB\n")
+        os.utime(os.path.join(basis, "f.txt"), (OLD, OLD))
+        received = get_dest_received_dir(fdest, source)
+        result, _ = run_client(source, fdest,
+                               flags=["-a", "--size-only", "--link-dest=basis", "--incremental"],
+                               port=shared_server.port)
+        assert result.returncode == 0, result.stderr[:300]
+        with open(os.path.join(received, "f.txt"), "rb") as fh:
+            assert fh.read() == b"AAAA\n", \
+                "FastSync must verify the basis content and transfer the source"
+
 
 class TestIgnoreExistingShortCircuit:
     """#9: --ignore-existing is decided by the receiver during the per-file

tests/integration/test_parity_selection.py

@@ -111,6 +111,45 @@ class TestRelativeGeneral:
                     assert int(rs.st_mtime) == int(fs.st_mtime), \
                         f"mtime mismatch for {rel} with {extra}"
 
+    @requires_rsync
+    @pytest.mark.ci
+    def test_no_implied_dirs_files_from_matches_rsync(self, shared_server):
+        """-R --no-implied-dirs --files-from: a listed file whose parent is not
+        itself listed still transfers; the implied parent is created with
+        default attributes (rsync 3.4.1 parity)."""
+        source = _make_tree(os.path.join(TEST_DATA_DIR, "sel_nidff_src"))
+        # Make the implied parent unmistakably non-default on the source so a
+        # wrongly-applied attribute would be observable.
+        os.chmod(os.path.join(source, "foo"), 0o700)
+        os.chmod(os.path.join(source, "foo", "bar"), 0o711)
+        os.utime(os.path.join(source, "foo"), (978307200, 978307200))
+        os.utime(os.path.join(source, "foo", "bar"), (978307200, 978307200))
+        lst = os.path.join(TEST_DATA_DIR, "sel_nidff_list")
+        with open(lst, "w") as fh:
+            fh.write("foo/bar/baz/f.txt\n")
+        dest = os.path.join(TEST_DATA_DIR, "sel_nidff_dst")
+        rdst = os.path.join(TEST_DATA_DIR, "sel_nidff_rdst")
+        clean_dir(dest)
+        clean_dir(rdst)
+        r = _rsync(["-rlpt", "-R", "--no-implied-dirs", "--files-from=" + lst,
+                    source + "/", rdst + "/"])
+        assert r.returncode == 0, r.stderr
+        result, _ = run_client(source, dest, flags=[
+            "-rlpt", "-R", "--no-implied-dirs", "--files-from", lst],
+            port=shared_server.port)
+        assert result.returncode == 0, result.stderr[:300]
+        assert _tree(rdst) == _tree(dest), "implied-parent layout mismatch"
+        # The implied parents exist on both sides and carry the run-time default
+        # attributes, not the source's (non-default) ones.
+        for rel in ("foo", "foo/bar", "foo/bar/baz"):
+            rs = os.stat(os.path.join(rdst, rel))
+            fs = os.stat(os.path.join(dest, rel))
+            assert (rs.st_mode & 0o7777) == (fs.st_mode & 0o7777), \
+                f"mode mismatch for implied {rel}"
+        # The listed file is transferred with its content.
+        with open(os.path.join(dest, "foo", "bar", "baz", "f.txt"), "rb") as fh:
+            assert fh.read() == b"deep\n"
+
 
 class TestDirsOneLevel:
     """#13: -d with a trailing slash (or '.') lists the source's immediate

tests/test_iconv.c

@@ -148,10 +148,23 @@ static void test_iconv_wire_sender_converts_local_to_remote() {
   charset_wire_free();
 }
 
-static void test_iconv_wire_receiver_converts_remote_to_local() {
+/* rsync push parity: with no server --iconv the destination charset is the
+ * client spec's REMOTE half, so the receiver writes the wire bytes verbatim. */
+static void test_iconv_wire_receiver_default_writes_remote() {
   EXPECT_TRUE(charset_wire_init_receiver("utf-8,iso-8859-1", NULL));
   char* local = charset_wire_apply("caf\xe9");
   EXPECT_NOT_NULL(local);
+  EXPECT_EQ_INT(strcmp(local, "caf\xe9"), 0);
+  free(local);
+  charset_wire_free();
+}
+
+/* A server that declares its own --iconv LOCAL converts wire(REMOTE) into that
+ * declared charset (the daemon "charset" analog). */
+static void test_iconv_wire_receiver_server_local_override() {
+  EXPECT_TRUE(charset_wire_init_receiver("utf-8,iso-8859-1", "utf-8"));
+  char* local = charset_wire_apply("caf\xe9");
+  EXPECT_NOT_NULL(local);
   EXPECT_EQ_INT(strcmp(local, "caf\xc3\xa9"), 0);
   free(local);
   charset_wire_free();
@@ -179,7 +192,7 @@ static void test_iconv_wire_str_roundtrip() {
     close(p[1]);
     io_set_fds(p[0], p[0]);
     charset_wire_free();
-    charset_wire_init_receiver("utf-8,iso-8859-1", NULL);
+    charset_wire_init_receiver("utf-8,iso-8859-1", "utf-8");
     char* got = receive_wire_str(p[0]);
     bool ok = got != NULL && strcmp(got, "caf\xc3\xa9") == 0;
     free(got);
@@ -211,7 +224,8 @@ void test_iconv() {
   test_iconv_exact_fill_no_overflow();
   test_iconv_growth_expanding_name();
   test_iconv_wire_sender_converts_local_to_remote();
-  test_iconv_wire_receiver_converts_remote_to_local();
+  test_iconv_wire_receiver_default_writes_remote();
+  test_iconv_wire_receiver_server_local_override();
   test_iconv_wire_disabled_passthrough();
   // This subtest forks to exercise the wire string handshake; the instrumented
   // parent is too slow under valgrind for the child's blocking reads.