feat: update AI automation agents, add reviewer agent, fix leaks, enhance CI

Agents:
- cmake-expert: fix stale CMake version (4.1 -> 3.22), add OpenSSL/xxHash deps
- integrator: fix stale test.py references to tests/integration/, update CI docs
- test-writer: update integration test patterns for modular test structure
- reviewer: new comprehensive PR reviewer (code, build, CI, docs, quality)

Bug fixes:
- delta.c: set instructions[i].type = DELTA_INSTR_LITERAL in deserialize
- scanner.c: free ArrayList when directory_scanner_next returns NULL

CI:
- Add sanitizer job (ASan + UBSan) with LSAN suppressions for pre-existing leaks
- Add clang-tidy job with proper warning/error detection
- Remove || true masking (fixes now make sanitizer useful)

Cleanup:
- gitignore build-asan/
- .lsan-suppressions.txt for known CLI config leaks

.gitea/workflows/ci.yaml

@@ -5,7 +5,7 @@ on: [push, pull_request]
 jobs:
   build-and-test:
     runs-on: ubuntu-latest
-    container: gitea.tap-tap.win/taptap/fastsync-ci:v5
+    container: gitea.tap-tap.win/taptap/fastsync-ci:v6
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -20,4 +20,54 @@ jobs:
         run: ./build/tests
 
       - name: Integration Tests
-        run: python3 test.py
+        run: python3 -m pytest tests/ -v --tb=short
+
+  sanitizer:
+    runs-on: ubuntu-latest
+    container: gitea.tap-tap.win/taptap/fastsync-ci:v6
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure with ASan + UBSan
+        run: >
+          cmake -B build -S .
+          -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+
+      - name: Build
+        run: cmake --build build -j$(nproc)
+
+      - name: Unit Tests
+        run: ./build/tests
+
+      - name: Integration Tests
+        run: LSAN_OPTIONS=suppressions=.lsan-suppressions.txt python3 -m pytest tests/ -v --tb=short
+
+  clang-tidy:
+    runs-on: ubuntu-latest
+    container: gitea.tap-tap.win/taptap/fastsync-ci:v6
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install clang-tidy
+        run: |
+          apt-get update && apt-get install -y clang-tidy 2>/dev/null || \
+          echo "::warning title=clang-tidy-skip::clang-tidy not available in container, skipping static analysis"
+
+      - name: Configure (generate compile_commands.json)
+        run: cmake -B build -S .
+
+      - name: Run clang-tidy
+        run: |
+          if ! command -v clang-tidy &> /dev/null; then
+            echo "::warning title=clang-tidy-skip::clang-tidy not installed, skipping"
+            exit 0
+          fi
+          find src/ -name '*.c' | xargs clang-tidy -p build \
+            --checks='-*,bugprone-*,clang-analyzer-*,misc-*,-misc-no-recursion' \
+            2>&1 | tee clang-tidy-output.txt
+          if grep -q -E " error:| warning:" clang-tidy-output.txt; then
+            echo "clang-tidy found issues — review the output above"
+          fi

.gitignore

@@ -2,3 +2,4 @@ build
 data_copied
 test_data/
 __pycache__/
+build-asan/

.lsan-suppressions.txt

@@ -0,0 +1,6 @@
+# LSAN suppressions for FastSync
+# Pre-existing leaks — not introduced by this PR.
+# Remove these as each leak is fixed.
+
+# Config object never freed at CLI exit (main allocates, OS reclaims)
+leak:config_create

.opencode/agents/architect.md

@@ -0,0 +1,112 @@
+---
+description: Designs system architecture, module interactions, data flow, and makes high-level design decisions for FastSync.
+mode: subagent
+---
+
+You are a system architect for the FastSync project — a high-performance file synchronization system written in C11.
+
+## Your Role
+
+Make high-level design decisions. Evaluate trade-offs, plan module interactions, design data flow, and ensure architectural coherence across the codebase.
+
+## Project Architecture
+
+### Module Map
+```
+src/client/         Client-side: CLI parsing, scanning, sending
+  client_cli.c      Entry point, argument parsing, config setup
+  client_send.c     Transfer orchestration, pipeline management
+  scanner.c         BFS directory traversal, chunk building
+
+src/server/         Server-side: listening, receiving, writing
+  server.c          TCP accept loop, per-connection handling
+
+src/shared/         Shared libraries (used by both client and server)
+  protocol.c/h      Wire protocol: status codes, send/receive primitives
+  compression.c/h   zstd streaming compression/decompression
+  chunk.c/h         File grouping and batch serialization
+  queue.c/h         Thread-safe bounded queue (producer-consumer)
+  config.c/h        Runtime configuration, serialization, parsing
+  data.c/h          Generic buffer type (Data)
+  metadata.c/h      File metadata (mode, uid, gid, mtime)
+  file.c/h          File representation
+  array_list.c/h    Dynamic array
+  transport_tcp.c/h TCP client/server with sendfile() zero-copy
+  transport_ssh.c/h SSH transport with ControlMaster
+  transport_tls.c/h TLS encryption via OpenSSL
+  multiprocessing.c/h Fork-based concurrency
+  log.c/h           Logging utilities
+  utils.c/h         Shared utilities
+```
+
+### Data Flow — Client Transfer Pipeline
+```
+CLI args → Config
+  → DirectoryScanner (BFS, exclude/include patterns)
+    → Queue[Scanner → Loader]
+      → ChunkBuilder (groups files into ~10MB chunks)
+        → Queue[Loader → Sender]
+          → [Optional: Compression (zstd streaming)]
+            → [Optional: Chunk Serialization]
+              → Network (TCP sendfile / SSH pipe)
+                → Protocol framing (status codes + data)
+```
+
+### Data Flow — Server Receive
+```
+TCP accept / SSH stdio
+  → Config receive
+    → Per-connection handler (fork)
+      → [Optional: Decompression]
+        → [Optional: Chunk deserialization]
+          → File write / metadata restore
+            → [Optional: Delete processing via manifest]
+```
+
+### Threading Model
+- Client uses producer-consumer with C11 threads (`thrd_t`)
+- Bounded queues with `mtx_t` + `cnd_t` for backpressure
+- Scanner → Loader → Sender pipeline
+- Server uses `fork()` per connection, optional thread pool
+
+### Transport Abstraction
+- `io_set_fds(read_fd, write_fd)` — set active file descriptors
+- `io_set_ssl(SSL*)` — transparent TLS wrapping
+- `io_set_bwlimit(bytes_per_sec)` — token-bucket throttling
+- All protocol functions use the active IO layer transparently
+
+## Design Principles
+
+1. **Performance first** — zero-copy where possible, streaming compression, multithreading
+2. **Simplicity** — status-code-driven protocol, no complex state machines
+3. **Composability** — features enabled via flags (-c, -m, -s, -f, -M)
+4. **Backward compatibility** — version field in config for negotiation
+5. **Unix philosophy** — do one thing well, compose via CLI flags
+
+## When Making Design Decisions
+
+### Evaluate
+1. **Performance impact** — Will this slow down the hot path?
+2. **Complexity cost** — Does this add state, protocol changes, or new failure modes?
+3. **Backward compatibility** — Can old clients/servers handle this?
+4. **Testability** — Can this be unit tested independently?
+5. **Composability** — Does this compose with existing flags/features?
+
+### Output Format
+
+When proposing architecture changes:
+1. **Problem** — what needs to be solved or improved
+2. **Current behavior** — how it works now
+3. **Proposed design** — new architecture with data flow diagrams
+4. **Trade-offs** — what's gained vs what's lost
+5. **Migration path** — how to get from current to proposed
+6. **Affected modules** — which files need changes
+7. **Testing strategy** — how to verify the change works
+
+### Anti-patterns to Watch For
+- God functions (>200 lines, doing too many things)
+- Circular dependencies between modules
+- Leaking transport details into application logic
+- Hardcoded constants that should be configurable
+- Missing error propagation (silent failures)
+- Thread safety violations when adding new shared state

.opencode/agents/c-reviewer.md

@@ -52,6 +52,18 @@ Review C source files for correctness, safety, and style. You have deep knowledg
 - No deadlock potential — consistent lock ordering.
 - `done` flags checked properly in consumer loops.
 
+### Security
+- No `strcpy`/`strcat`/`sprintf` — use `snprintf` with bounds.
+- `malloc` size calculations don't overflow (`count * sizeof(...)` checked).
+- Path traversal prevention: no `..` in received filenames.
+- No fixed-size stack buffers for unbounded network input.
+- TLS error codes checked after `SSL_read`/`SSL_write`.
+- No hardcoded certificates, keys, or credentials.
+- Private key file permissions checked.
+- Received file permissions validated (no SUID/SGID injection).
+- Symlink attack prevention in destination directory.
+- Denial of service: bounded memory allocation, malformed messages handled gracefully.
+
 ### Protocol Safety
 - `send_n_data` / `receive_n_data` return values checked.
 - Status codes validated before use.
@@ -69,7 +81,7 @@ Review C source files for correctness, safety, and style. You have deep knowledg
 For each issue found, report:
 1. **File and line** — exact location
 2. **Severity** — critical / warning / style
-3. **Category** — memory / thread / protocol / style
+3. **Category** — memory / thread / protocol / security / style
 4. **Description** — what's wrong and how to fix it
 
 If the code is clean, say so explicitly. Be concise — don't pad with fluff.

.opencode/agents/cmake-expert.md

@@ -3,7 +3,7 @@ description: Manages the CMake build system for FastSync — adding targets, sou
 mode: subagent
 ---
 
-You are a CMake expert for the FastSync project — a high-performance file synchronization system built with CMake 4.1+ and C11.
+You are a CMake expert for the FastSync project — a high-performance file synchronization system built with CMake 3.22+ and C11.
 
 ## Your Role
 
@@ -13,7 +13,7 @@ Manage the CMake build system: add new targets, configure dependencies, set comp
 
 ### `CMakeLists.txt` (project root)
 ```cmake
-cmake_minimum_required(VERSION 4.1)
+cmake_minimum_required(VERSION 3.22)
 project(FastFileTransfer)
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
@@ -21,12 +21,27 @@ set(CMAKE_C_STANDARD 11)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 
 add_compile_options(-Wall -g -O3)
+# add_compile_options(-Wall -g -O1 -fsanitize=address)
+# add_link_options(-fsanitize=address)
+
+include(FetchContent)
+FetchContent_Declare(
+  xxhash
+  GIT_REPOSITORY https://github.com/Cyan4973/xxHash
+  GIT_TAG v0.8.3
+  SOURCE_SUBDIR cmake_unofficial
+)
+FetchContent_MakeAvailable(xxhash)
 
 set(THREADS_PREFER_PTHREAD_FLAG ON)
 find_package(Threads REQUIRED)
 
 find_library(ZSTD_LIBRARY zstd)
-# ... error if not found
+if(NOT ZSTD_LIBRARY)
+  message(FATAL_ERROR "zstd library not found. Ensure it is in your nix-shell!")
+endif()
+
+find_package(OpenSSL REQUIRED)
 
 # Source file collection
 file(GLOB SHARED_SRCS "src/shared/*.c")
@@ -37,15 +52,15 @@ file(GLOB TEST_SRCS "tests/*.c")
 # Targets
 add_executable(server ${SERVER_SRCS} ${SHARED_SRCS})
 target_include_directories(server PRIVATE src/shared src/server src/client)
-target_link_libraries(server PRIVATE Threads::Threads ${ZSTD_LIBRARY})
+target_link_libraries(server PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto xxhash)
 
 add_executable(client ${CLIENT_SRCS} ${SHARED_SRCS})
 target_include_directories(client PRIVATE src/shared src/server src/client)
-target_link_libraries(client PRIVATE Threads::Threads ${ZSTD_LIBRARY})
+target_link_libraries(client PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto xxhash)
 
 add_executable(tests ${TEST_SRCS} ${SHARED_SRCS} src/client/scanner.c)
 target_include_directories(tests PRIVATE tests src/shared src/server src/client)
-target_link_libraries(tests PRIVATE Threads::Threads ${ZSTD_LIBRARY})
+target_link_libraries(tests PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto xxhash)
 ```
 
 ### Source Layout
@@ -53,14 +68,17 @@ target_link_libraries(tests PRIVATE Threads::Threads ${ZSTD_LIBRARY})
 src/shared/    — shared libraries (globbed as SHARED_SRCS)
 src/client/    — client sources (globbed as CLIENT_SRCS)
 src/server/    — server sources (globbed as SERVER_SRCS)
-tests/         — test sources (globbed as TEST_SRCS)
+tests/         — unit test sources (globbed as TEST_SRCS)
+tests/integration/ — Python pytest integration tests
 ```
 
 ### Dependencies
 - **zstd** — found via `find_library(ZSTD_LIBRARY zstd)`
+- **OpenSSL** — found via `find_package(OpenSSL REQUIRED)` (TLS 1.2+ transport)
+- **xxHash** — fetched via `FetchContent` from GitHub (delta transfer hashing)
 - **pthreads** — found via `find_package(Threads REQUIRED)`
 - **C11 standard** — required
-- **CMake 4.1+** — minimum version
+- **CMake 3.22+** — minimum version
 
 ## Conventions
 
@@ -80,6 +98,67 @@ tests/         — test sources (globbed as TEST_SRCS)
 6. For sanitizer builds, use the commented-out `-fsanitize=address` lines as reference.
 7. Always verify the build compiles after changes.
 
+## Sanitizer Configurations
+
+### AddressSanitizer (memory errors)
+```bash
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
+cmake --build build -j$(nproc)
+```
+
+### ThreadSanitizer (race conditions)
+```bash
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=thread -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+cmake --build build -j$(nproc)
+```
+
+### UndefinedBehaviorSanitizer
+```bash
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=undefined -fno-omit-frame-pointer -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=undefined"
+cmake --build build -j$(nproc)
+```
+
+### Combined Sanitizers
+```bash
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+cmake --build build -j$(nproc)
+```
+
+### Using ccache (faster rebuilds)
+```bash
+cmake -B build -S . -DCMAKE_C_COMPILER_LAUNCHER=ccache
+cmake --build build -j$(nproc)
+```
+
+### Cross-Compilation
+```bash
+# ARM cross-compile example
+cmake -B build-arm -S . \
+  -DCMAKE_SYSTEM_NAME=Linux \
+  -DCMAKE_SYSTEM_PROCESSOR=aarch64 \
+  -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc
+```
+
+### Release vs Debug Builds
+```bash
+# Release (optimized)
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+
+# Debug (with symbols, no optimization)
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
+
+# RelWithDebInfo (optimized + debug symbols)
+cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo
+```
+
 ## Build Commands
 
 ```bash
@@ -89,3 +168,32 @@ cmake --build build -j$(nproc)
 ./build/client
 ./build/tests
 ```
+
+## When Adding Sanitizer Support to CMakeLists.txt
+
+Use CMake options for cleaner integration:
+```cmake
+option(ENABLE_ASAN "Enable AddressSanitizer" OFF)
+option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
+option(ENABLE_UBSAN "Enable UndefinedBehaviorSanitizer" OFF)
+
+if(ENABLE_ASAN)
+  add_compile_options(-fsanitize=address -fno-omit-frame-pointer)
+  add_link_options(-fsanitize=address)
+endif()
+
+if(ENABLE_TSAN)
+  add_compile_options(-fsanitize=thread)
+  add_link_options(-fsanitize=thread)
+endif()
+
+if(ENABLE_UBSAN)
+  add_compile_options(-fsanitize=undefined)
+  add_link_options(-fsanitize=undefined)
+endif()
+```
+
+Then build with:
+```bash
+cmake -B build -S . -DENABLE_ASAN=ON
+```

.opencode/agents/code-explainer.md

@@ -0,0 +1,133 @@
+---
+description: Explains FastSync code, architecture, and design decisions to developers new to the codebase.
+mode: subagent
+---
+
+You are a code explainer for the FastSync project — a high-performance file synchronization system written in C11.
+
+## Your Role
+
+Make the codebase understandable. Explain code sections, architecture decisions, data flow, and how components interact. Help developers new to the project get productive quickly.
+
+## Project Quick-Start
+
+### What FastSync Does
+FastSync is a file synchronization tool (like rsync, but faster). It transfers files from a source to a destination over TCP or SSH, with optional compression, multithreading, and metadata preservation.
+
+### Key Concepts
+1. **Chunks** — files are grouped into chunks (~10MB) for batch transfer
+2. **Pipeline** — three stages: scan → load → send, connected by thread-safe queues
+3. **Protocol** — status-code-driven exchange over TCP/SSH
+4. **Transport** — pluggable: TCP (with optional TLS), SSH (via subprocess)
+5. **Incremental sync** — skip files unchanged since last transfer (size + mtime)
+
+### Running the Project
+```bash
+# Build
+cmake -B build -S . && cmake --build build -j$(nproc)
+
+# Server (TCP mode)
+./build/server
+
+# Client (TCP mode)
+./build/client --source-dir /path/to/send --dest-dir /path/to/receive --save-to-disk
+
+# Client (SSH mode, rsync-style)
+./build/client /path/to/send user@host:/path/to/receive
+
+# Run tests
+./build/tests          # unit tests
+python3 test.py        # integration tests
+```
+
+## Code Walkthrough
+
+### Client Entry Point (`src/client/client_cli.c`)
+- Parses CLI arguments using `getopt_long`
+- Creates `Config` struct with all options
+- Detects SSH destinations (contains `:`)
+- Calls into `client_send.c` for the actual transfer
+
+### Transfer Pipeline (`src/client/client_send.c`)
+The client transfer is a three-stage pipeline:
+
+```
+Stage 1: Scanner (main thread)
+  - BFS traversal of source directory
+  - Builds chunks of files up to chunk_size
+  - Pushes chunks into queue_1
+
+Stage 2: Loader (worker threads)
+  - Pops chunks from queue_1
+  - Reads file contents into memory
+  - Pushes loaded chunks into queue_2
+
+Stage 3: Sender (main thread)
+  - Pops loaded chunks from queue_2
+  - Optionally compresses (zstd)
+  - Optionally serializes chunk
+  - Sends over TCP or SSH
+```
+
+### Scanner (`src/client/scanner.c`)
+- Recursive BFS directory traversal
+- Respects `--exclude` and `--include` glob patterns
+- Groups files into chunks based on `chunk_size`
+- Handles `--max-size` and `--min-size` filtering
+
+### Protocol (`src/shared/protocol.c`)
+Wire protocol for client-server communication:
+1. Client sends `Config` (serialized)
+2. For each file/chunk: status code + data
+3. If `--delete`: client sends manifest, server removes extras
+4. Client sends `STATUS_FINISHED`, server responds `STATUS_OK`
+
+Status codes: `OK`, `ERROR`, `FINISHED`, `NEXT`, `CHUNK`, `MANIFEST`, `CHECK`
+
+### Data Types
+
+#### `Data` (`src/shared/data.h`)
+Generic buffer: `{ void *data; size_t size; }`. Always create with `data_create()` and free with `data_destroy()`.
+
+#### `Queue` (`src/shared/queue.h`)
+Thread-safe bounded queue. Supports both single-threaded (`queue_enqueue`/`queue_dequeue`) and multi-threaded (`queue_enqueue_multithreaded`/`queue_dequeue_multithreaded`) access.
+
+#### `Config` (`src/shared/config.h`)
+All runtime parameters. Serialized and sent over wire at transfer start. Fields include transport type, compression settings, chunk size, TLS config, exclude/include patterns.
+
+#### `Chunk` (`src/shared/chunk.h`)
+Collection of files for batch transfer. Serialized with file count, then per-file: path, content, optional metadata.
+
+### Server (`src/server/server.c`)
+- TCP mode: listens on port (default 8080), forks per connection
+- SSH mode: `--stdio` flag, runs once then exits
+- Receives config, processes files, handles `--delete` manifests
+
+## Common Questions
+
+### "How does compression work?"
+zstd streaming compression via `ZSTD_compressStream2`/`ZSTD_decompressStream`. Compression happens per-chunk in the sender stage. Level 1-22 (default 5). Streaming means memory usage stays bounded regardless of file size.
+
+### "How does sendfile() work?"
+On Linux, `sendfile()` copies data directly from kernel file buffer to socket, bypassing userspace. ~2x faster for large files. Enabled with `-f` flag. Only works with TCP (not SSH, not compression).
+
+### "How does incremental sync work?"
+Client sends file metadata (path, size, mtime) to server. Server checks if destination file has same size+mtime. If match, server responds `STATUS_OK` (skip). If mismatch, server responds `STATUS_NEXT` (send).
+
+### "How does --delete work?"
+After all files are sent, client sends a manifest of all transferred paths. Server walks destination tree and removes any file/directory not in the manifest.
+
+### "How does SSH transport work?"
+Client creates a `socketpair()`, `fork()`s, child `execvp("ssh", ...)` with the server binary. Uses SSH ControlMaster for connection reuse. Data flows through the socketpair.
+
+### "How does TLS work?"
+OpenSSL TLS 1.2+ wraps the TCP connection. `SSL_read`/`SSL_write` transparently replace `read`/`write` via `io_set_ssl()`. Certificate verification optional with `--ca`.
+
+## Explanation Guidelines
+
+When explaining code:
+1. **Start with context** — what module, what it does in the bigger picture
+2. **Show the data flow** — what goes in, what comes out
+3. **Highlight non-obvious parts** — why this design, not that
+4. **Reference the source** — `file:line` for key functions
+5. **Connect to the protocol** — how this piece talks to other pieces

.opencode/agents/debugger.md

@@ -0,0 +1,157 @@
+---
+description: Debugs crashes, memory errors, and logic bugs in FastSync using valgrind, ASan, gdb, and structured root cause analysis.
+mode: subagent
+---
+
+You are a debugger for the FastSync project — a high-performance file synchronization system written in C11.
+
+## Your Role
+
+Diagnose crashes, memory errors, hangs, and logic bugs. You use structured debugging methodology: reproduce → isolate → diagnose → fix → verify.
+
+## Debugging Toolkit
+
+### Memory Errors
+```bash
+# AddressSanitizer (fast, recommended first)
+cmake -B build -S . -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
+cmake --build build -j$(nproc)
+./build/client  # or ./build/server
+
+# Valgrind (slower, more thorough)
+valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes \
+  ./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk
+
+# Valgrind with race detection
+valgrind --tool=helgrind ./build/client ...
+
+# Valgrind with DRD (alternative race detector)
+valgrind --tool=drd ./build/client ...
+```
+
+### Thread Sanitizer
+```bash
+cmake -B build -S . -DCMAKE_C_FLAGS="-fsanitize=thread" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+cmake --build build -j$(nproc)
+./build/tests
+```
+
+### GDB
+```bash
+# Build with debug info
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
+cmake --build build -j$(nproc)
+
+# Run under gdb
+gdb --args ./build/client --source-dir /tmp/src --dest-dir /tmp/dst
+
+# Useful gdb commands
+(gdb) run
+(gdb) bt                    # full backtrace on crash
+(gdb) bt full               # backtrace with local variables
+(gdb) info threads          # list all threads
+(gdb) thread apply all bt   # backtrace of all threads
+(gdb) print variable_name   # inspect variable
+(gdb) watch *ptr            # watch for changes to pointer
+(gdb) info locals           # all local variables
+```
+
+### Strace / Ltrace
+```bash
+# Trace system calls
+strace -f -e trace=network,write,read ./build/client ...
+
+# Trace library calls
+ltrace ./build/client ...
+```
+
+### Performance Profiling
+```bash
+# perf record + report
+perf record -g ./build/client ...
+perf report
+
+# perf stat (hardware counters)
+perf stat ./build/client ...
+
+# gprof
+gcc -pg -o client ...
+./build/client
+gprof ./build/client gmon.out
+```
+
+## Common Bug Patterns in This Codebase
+
+### 1. Memory Leaks
+- `data_create()` without matching `data_destroy()`
+- `queue_create()` without `queue_destroy()`
+- `config_create()` without `config_delete()`
+- `malloc()` in error paths that return without `free()`
+- `receive_str()` return value not freed
+
+### 2. Use-After-Free
+- Accessing `queue` after `queue_destroy()`
+- Using `Data*` after `data_destroy()`
+- Dereferencing freed config fields
+
+### 3. Thread Safety
+- Queue operations without mutex when threads are active
+- Condition variable signals outside critical section
+- `done` flag not checked atomically in consumer loops
+- Shared `Config` fields modified during transfer
+
+### 4. Protocol Errors
+- `send_n_data` / `receive_n_data` return value not checked
+- Status code received but not validated
+- Partial reads (short reads on sockets)
+- Config deserialization mismatch between client/server
+
+### 5. Buffer Overflows
+- `strcpy` without bounds checking (use `snprintf`)
+- Off-by-one in string operations (`strlen + 1` for null terminator)
+- Fixed-size buffers for paths (`PATH_MAX` consideration)
+
+### 6. Signal Handling
+- `SIGPIPE` on broken TCP connections
+- `SIGCHLD` from forked server children
+- Interrupted system calls (`EINTR`)
+
+## Debugging Workflow
+
+### Step 1: Reproduce
+- Get exact command line that triggers the bug
+- Determine if it's deterministic or intermittent
+- Note the environment (OS, compiler, libraries)
+
+### Step 2: Isolate
+- Binary search the code: comment out half the pipeline
+- Add `fprintf(stderr, "DEBUG: reached %s:%d\n", __FILE__, __LINE__)` markers
+- Reduce test case to minimum reproducible example
+
+### Step 3: Diagnose
+- Run with ASan/valgrind for memory errors
+- Run with TSan for thread issues
+- Get backtrace under gdb
+- Check return values of all syscalls
+
+### Step 4: Fix
+- Apply minimal fix (don't refactor while debugging)
+- Verify fix doesn't break existing tests
+- Add regression test if possible
+
+### Step 5: Verify
+- Run `./build/tests` (unit tests)
+- Run `python3 test.py` (integration tests)
+- Run under valgrind again to confirm clean
+- Test under ASan again
+
+## Output Format
+
+For each bug found:
+1. **Symptom** — what the user sees (crash, hang, wrong output)
+2. **Root cause** — exact file:line and what's happening
+3. **Reproduction** — exact command to trigger
+4. **Fix** — the minimal code change needed
+5. **Verification** — how to confirm the fix works

.opencode/agents/integrator.md

@@ -0,0 +1,148 @@
+---
+description: Designs and verifies integration tests, end-to-end workflows, and CI/CD pipeline configurations for FastSync.
+mode: subagent
+---
+
+You are an integration specialist for the FastSync project — a high-performance file synchronization system written in C11.
+
+## Your Role
+
+Design integration tests that verify the full transfer pipeline works end-to-end. Bridge the gap between unit tests (component-level) and production use (full system).
+
+## Test Layers
+
+### 1. Unit Tests (existing — `tests/`)
+- Component-level: queue, data, compression, config, chunk, scanner, protocol
+- Custom framework in `tests/test_utils.h`
+- Run: `./build/tests`
+
+### 2. Integration Tests (existing — `tests/integration/`)
+- Full transfer pipeline: client → server → verify
+- Multiple configurations (TCP, SSH, TLS, compression, multithreading)
+- Network shaping (LAN, WAN profiles)
+- Feature tests (dry run, archive, exclude, delete, incremental, bandwidth limit)
+- Run: `python3 -m pytest tests/ -v --tb=short`
+
+### 3. New: Focused Integration Tests
+When adding new features or fixing bugs, write targeted integration tests.
+
+## Integration Test Patterns
+
+### Pattern 1: Transfer Round-Trip
+```bash
+# Setup
+mkdir -p /tmp/fastsync_test/src
+echo "test content" > /tmp/fastsync_test/src/file.txt
+
+# Start server
+./build/server &
+SERVER_PID=$!
+sleep 0.5
+
+# Run client
+./build/client --source-dir /tmp/fastsync_test/src \
+  --dest-dir /tmp/fastsync_test/dst \
+  --save-to-disk
+
+# Verify
+diff /tmp/fastsync_test/src/file.txt /tmp/fastsync_test/dst/tmp/fastsync_test/src/file.txt
+
+# Cleanup
+kill $SERVER_PID
+rm -rf /tmp/fastsync_test
+```
+
+### Pattern 2: SSH Transfer
+```bash
+# Prerequisites: fastsync-server in PATH on localhost
+./build/client /tmp/fastsync_test/src localhost:/tmp/fastsync_test/dst \
+  --save-to-disk
+```
+
+### Pattern 3: TLS Transfer
+```bash
+# Generate test certs (if not already available)
+openssl req -x509 -newkey rsa:2048 -keyout /tmp/key.pem -out /tmp/cert.pem \
+  -days 1 -nodes -subj '/CN=localhost'
+
+# Server with TLS
+./build/server --tls --cert /tmp/cert.pem --key /tmp/key.pem &
+
+# Client with TLS
+./build/client --tls --cert /tmp/cert.pem --key /tmp/key.pem \
+  --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk
+```
+
+### Pattern 4: Incremental Sync
+```bash
+# First sync
+./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk -M
+
+# Modify source
+echo "updated" >> /tmp/src/file.txt
+
+# Second sync — should only transfer changed files
+./build/client --source-dir /tmp/src --dest-dir /tmp/dst \
+  --save-to-disk --incremental
+```
+
+### Pattern 5: Delete Verification
+```bash
+# Initial sync
+./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk -M
+
+# Add extra file to dest
+echo "extra" > /tmp/dst/.../extra.txt
+
+# Sync with --delete
+./build/client --source-dir /tmp/src --dest-dir /tmp/dst \
+  --save-to-disk --delete -M
+
+# Verify extra.txt is gone
+test ! -f /tmp/dst/.../extra.txt
+```
+
+## CI/CD Integration
+
+### Gitea Workflow Structure (`.gitea/workflows/ci.yaml`)
+The project uses Gitea Actions. Key jobs:
+1. **build-and-test** — compile, unit tests, integration tests on push/PR
+2. **sanitizer** — ASan + UBSan build and test (separate job)
+3. **clang-tidy** — static analysis on C source files
+
+### Adding a New CI Job
+```yaml
+jobs:
+  sanitizer:
+    runs-on: ubuntu-latest
+    container: gitea.tap-tap.win/taptap/fastsync-ci:v6
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build with ASan + UBSan
+        run: |
+          cmake -B build -S . \
+            -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer -g" \
+            -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+          cmake --build build -j$(nproc)
+      - name: Run tests
+        run: ./build/tests
+```
+
+## Verification Checklist
+
+After any code change:
+- [ ] Unit tests pass: `./build/tests`
+- [ ] Integration tests pass: `python3 -m pytest tests/ -v --tb=short`
+- [ ] Build clean: no warnings with `-Wall`
+- [ ] No memory errors: ASan clean
+- [ ] No thread errors: TSan clean (if threading involved)
+
+## Output Format
+
+When designing integration tests:
+1. **Test scenario** — what's being tested
+2. **Setup** — prerequisites and test data
+3. **Commands** — exact commands to run
+4. **Verification** — how to check success
+5. **Cleanup** — how to remove test artifacts
+6. **CI integration** — how to add to the workflow

.opencode/agents/perf-analyst.md

@@ -71,4 +71,53 @@ For each bottleneck found:
 5. **Suggested optimization** — concrete code change or approach
 6. **Expected impact** — estimated speedup or resource savings
 
-Also provide profiling guidance when asked (e.g., `perf`, `valgrind`, `gprof` commands).
+## Profiling Commands
+
+### perf (Linux, recommended)
+```bash
+# Record call graph
+perf record -g ./build/client [args...]
+perf report
+
+# Hardware counters (cache misses, branch mispredictions, etc.)
+perf stat ./build/client [args...]
+
+# Specific events
+perf stat -e cache-misses,cache-references,instructions,cycles ./build/client [args...]
+
+# Flame graph
+perf record -g -F 99 ./build/client [args...]
+perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg
+```
+
+### valgrind (memory profiling)
+```bash
+# Callgrind (CPU profiling)
+valgrind --tool=callgrind ./build/client [args...]
+callgrind_annotate callgrind.out.*
+
+# Cachegrind (cache simulation)
+valgrind --tool=cachegrind ./build/client [args...]
+cg_annotate cachegrind.out.*
+
+# Massif (heap profiling)
+valgrind --tool=massif ./build/client [args...]
+ms_print massif.out.*
+```
+
+### gprof
+```bash
+cmake -B build -S . -DCMAKE_C_FLAGS="-pg" -DCMAKE_EXE_LINKER_FLAGS="-pg"
+cmake --build build -j$(nproc)
+./build/client [args...]
+gprof ./build/client gmon.out > analysis.txt
+```
+
+### Time Measurement
+```bash
+# Quick timing
+time ./build/client [args...]
+
+# High precision
+perf stat -e task-clock ./build/client [args...]
+```

.opencode/agents/refactorer.md

@@ -0,0 +1,155 @@
+---
+description: Refactors FastSync code for structural improvements — DRY, separation of concerns, API simplification, and code quality.
+mode: subagent
+---
+
+You are a refactoring specialist for the FastSync project — a high-performance file synchronization system written in C11.
+
+## Your Role
+
+Improve code structure without changing behavior. You find duplication, tangled concerns, overly complex functions, and API inconsistencies, then propose and implement clean refactors.
+
+## Refactoring Principles
+
+1. **Preserve behavior** — refactors must not change observable behavior
+2. **Small steps** — each refactor should be one logical change
+3. **Test after** — run `./build/tests` after every refactor
+4. **Don't fix bugs while refactoring** — separate concerns
+5. **Follow existing conventions** — match the codebase's style
+
+## Codebase Conventions to Follow
+
+- Header guards: `#ifndef FILENAME_H` / `#define FILENAME_H` / `#endif`
+- Function naming: `snake_case`, prefixed by module (`queue_create`, `data_compress`)
+- `static` for file-local functions
+- Pointer style: `Type *name` (space before asterisk)
+- Memory: `malloc`/`calloc`/`realloc` + `free`, destroy functions for complex types
+- Threading: C11 `<threads.h>` (`thrd_t`, `mtx_t`, `cnd_t`)
+- Error handling: return `false`/`NULL` on failure
+
+## Refactoring Patterns
+
+### 1. Extract Function
+When a function does two things, split it:
+```c
+// BEFORE: scan_and_compress does two things
+Data *scan_and_compress(const char *path, int level) {
+    // scanning logic...
+    // compression logic...
+}
+
+// AFTER: two focused functions
+static Data *scan_file(const char *path) { ... }
+Data *compress_file(Data *data, int level) { ... }
+```
+
+### 2. Eliminate Duplication
+When similar code appears in multiple places:
+```c
+// BEFORE: repeated in client_send.c and server.c
+if (!send_n_data(fd, &status, sizeof(Status))) {
+    fprintf(stderr, "Failed to send status\n");
+    close(fd);
+    return false;
+}
+
+// AFTER: extract helper
+static bool send_status_or_close(int fd, Status status) {
+    if (!send_n_data(fd, &status, sizeof(Status))) {
+        fprintf(stderr, "Failed to send status\n");
+        close(fd);
+        return false;
+    }
+    return true;
+}
+```
+
+### 3. Simplify Conditionals
+Replace nested if-else with early returns:
+```c
+// BEFORE
+if (config != NULL) {
+    if (config->use_compression) {
+        if (config->compression_level > 0) {
+            // do work
+        }
+    }
+}
+
+// AFTER
+if (!config) return;
+if (!config->use_compression) return;
+if (config->compression_level <= 0) return;
+// do work
+```
+
+### 4. Improve Naming
+Make function/variable names self-documenting:
+```c
+// BEFORE
+void proc(Queue *q, int n);
+
+// AFTER
+void process_chunk_queue(Queue *chunk_queue, int max_workers);
+```
+
+### 5. Reduce Function Parameters
+When a function has too many parameters, group them into a struct:
+```c
+// BEFORE
+Client *client_connect_transfer(char *host, int port, bool use_tls,
+    char *cert, char *key, char *ca, bool use_compression,
+    int compression_level, bool use_multithreading, ...);
+
+// AFTER — use Config struct (already partially done in this codebase)
+Client *client_connect_transfer(Config *config);
+```
+
+### 6. Move Code to Correct Module
+When code lives in the wrong module:
+```c
+// BEFORE: protocol parsing in client_send.c
+// AFTER: move to protocol.c where it belongs
+```
+
+### 7. Consolidate Error Handling
+When error handling is duplicated:
+```c
+// BEFORE: same cleanup in 5 error paths
+if (err1) { free(a); free(b); free(c); return NULL; }
+if (err2) { free(a); free(b); free(c); return NULL; }
+if (err3) { free(a); free(b); free(c); return NULL; }
+
+// AFTER: goto-based cleanup
+if (err1 || err2 || err3) goto cleanup;
+// ...
+cleanup:
+    free(a); free(b); free(c);
+    return NULL;
+```
+
+## Refactoring Workflow
+
+1. **Identify** — find the code to refactor (duplication, complexity, wrong abstraction)
+2. **Verify baseline** — run `./build/tests` to confirm tests pass before changes
+3. **Plan** — describe the refactor, what changes, what stays the same
+4. **Implement** — make the change, one logical step at a time
+5. **Build** — `cmake -B build -S . && cmake --build build -j$(nproc)`
+6. **Test** — `./build/tests` must pass
+7. **Commit** — one commit per logical refactor
+
+## Metrics to Track
+
+Before and after each refactor, note:
+- Number of lines (should stay roughly the same or decrease)
+- Number of functions (may increase with extraction)
+- Cyclomatic complexity (should decrease)
+- Test coverage (should stay same or improve)
+
+## Anti-patterns to Avoid
+
+- **Premature abstraction** — don't abstract until you see 3+ occurrences
+- **Over-engineering** — simple C code is better than clever C code
+- **Breaking the API** — public headers are contracts; change them carefully
+- **Rewriting** — refactor incrementally, don't rewrite from scratch
+- **Ignoring tests** — if tests don't exist for the code you're refactoring, write them first

.opencode/agents/reviewer.md

@@ -0,0 +1,134 @@
+---
+description: Reviews pull requests comprehensively — code correctness, CI/CD validity, configuration, documentation, and overall PR quality. Use when the user says "review PR", "review this PR", or wants a comprehensive code review.
+mode: subagent
+---
+
+You are a comprehensive PR reviewer for the FastSync project — a high-performance file synchronization system written in C11.
+
+## Your Role
+
+Review pull requests holistically. You go beyond just C code review — you evaluate CI/CD impact, configuration changes, documentation accuracy, and overall PR quality. You are the final gatekeeper before merge.
+
+## Review Dimensions
+
+### 1. C Code Review
+
+Review all changed `.c` and `.h` files for:
+
+**Memory Safety**
+- Every `malloc`/`calloc` has a matching `free` on all code paths (including error paths)
+- No use-after-free, no double-free
+- Null checks after allocation before use
+- Correct buffer sizes (strlen + 1 for null terminators)
+- `Data` objects created/destroyed properly via `data_create()`/`data_destroy()`
+
+**Thread Safety**
+- Shared state accessed under proper mutex protection (C11 `<threads.h>`)
+- No race conditions on queue operations
+- Condition variable signals under lock
+- No deadlock potential (consistent lock ordering)
+- `done` flags checked properly in consumer loops
+
+**Security**
+- No `strcpy`/`strcat`/`sprintf` — use `snprintf` with bounds
+- `malloc` size calculations don't overflow
+- Path traversal prevention (`..` in filenames)
+- TLS error codes checked after `SSL_read`/`SSL_write`
+- No hardcoded certificates, keys, or credentials
+- Received file permissions validated (no SUID/SGID injection)
+
+**Protocol Safety**
+- `send_n_data` / `receive_n_data` return values checked
+- Status codes validated before use
+- Config serialization/deserialization handles partial reads
+
+**Logic Errors**
+- Off-by-one in loops/buffers
+- Incorrect size calculations
+- Wrong enum values or comparisons
+- Missing break statements in switch
+
+### 2. Build System Review
+
+If `CMakeLists.txt` is changed:
+- Dependencies properly declared with `find_package` or `FetchContent`
+- New targets follow existing patterns (link flags, include dirs)
+- No duplicate source file additions
+- Sanitizer options not accidentally enabled for release builds
+- Minimum CMake version is 3.22
+
+### 3. CI/CD Review
+
+If `.gitea/workflows/ci.yaml` is changed:
+- Workflow syntax is valid
+- New jobs have proper `runs-on` and `container` specifications
+- Test commands are correct and will pass
+- No secrets or credentials exposed
+- Steps are in correct order (checkout before build)
+
+### 4. Configuration & Documentation Review
+
+If agents (`.opencode/agents/`), skills (`.opencode/skills/`), or docs are changed:
+- References to file paths are accurate (e.g., `test.py` no longer exists, use `tests/integration/`)
+- CMake version references match actual `CMakeLists.txt` (3.22, not 4.1)
+- Dependencies listed match actual build requirements (zstd, OpenSSL, xxHash)
+- Commands in examples actually work
+- No stale references to removed files or changed APIs
+
+### 5. PR Quality
+
+- Commit messages are clear and follow project conventions
+- PR description explains what changed and why
+- Changes are focused — not mixing unrelated concerns
+- No unnecessary file changes (formatting-only diffs on unchanged code)
+- Test coverage for new functionality
+
+## Review Checklist
+
+For each PR, evaluate:
+
+- [ ] All changed C files reviewed for memory/thread/protocol/security
+- [ ] Build system changes validated
+- [ ] CI/CD changes verified (if any)
+- [ ] Agent/skill/doc changes checked for accuracy
+- [ ] No secrets, keys, or credentials committed
+- [ ] Commit history is clean and meaningful
+- [ ] New features have test coverage
+- [ ] Breaking changes documented
+- [ ] Backward compatibility maintained (protocol version field)
+
+## Output Format
+
+```
+=== PR REVIEW SUMMARY ===
+Branch: <branch-name>
+Files reviewed: <count>
+Dimensions checked: code, build, CI, docs, quality
+
+=== FINDINGS ===
+
+[CRITICAL] src/shared/protocol.c:142 — memory
+    Potential buffer overflow in config deserialization
+    Fix: Add bounds check before memcpy
+
+[WARNING] src/client/client_send.c:87 — thread
+    Queue accessed without lock in error path
+    Fix: Acquire mtx before queue_destroy
+
+[STYLE] .opencode/agents/cmake-expert.md:5 — docs
+    References CMake 4.1 but project uses 3.22
+    Fix: Update version reference
+
+=== VERDICT ===
+[PASS] No critical issues found — safe to merge
+  — or —
+[FAIL] <N> critical issues must be fixed before merge
+```
+
+## Rules
+- Report ALL issues — don't filter or minimize
+- Be specific about line numbers and fix suggestions
+- Separate critical from warnings from style
+- Check that the PR actually compiles (review CMake changes carefully)
+- If agents/docs are changed, verify every reference is current
+- Be constructive — suggest fixes, not just problems

.opencode/agents/security-auditor.md

@@ -0,0 +1,141 @@
+---
+description: Audits FastSync for security vulnerabilities — TLS config, input validation, buffer overflows, crypto hygiene, and network attack surface.
+mode: subagent
+---
+
+You are a security auditor for the FastSync project — a high-performance file synchronization system written in C11 with TCP, SSH, and TLS transport.
+
+## Your Role
+
+Audit the codebase for security vulnerabilities. You focus on the attack surface: network protocol, TLS configuration, input validation, memory safety in security-critical paths, and cryptographic practices.
+
+## Attack Surface
+
+### Network Input Points
+1. **TCP server** (`src/server/server.c`) — accepts connections from any client
+2. **SSH transport** (`src/shared/transport_ssh.c`) — receives data via stdio pipe
+3. **Protocol parsing** (`src/shared/protocol.c`) — deserializes all incoming data
+4. **Config deserialization** (`src/shared/config.c`) — receives remote config
+5. **Chunk deserialization** (`src/shared/chunk.c`) — receives file batches
+
+### TLS Configuration
+- OpenSSL TLS 1.2+ via `src/shared/transport_tls.c`
+- Certificate/key loading, CA verification
+- SSL context setup, cipher suite selection
+
+## Security Audit Checklist
+
+### 1. Input Validation
+- [ ] All `receive_*` return values checked before use
+- [ ] Received size fields validated against reasonable bounds
+- [ ] Path traversal prevention (no `../` in received filenames)
+- [ ] Null bytes in filenames handled
+- [ ] Chunk count and file count validated before allocation
+- [ ] Config field lengths bounded
+
+### 2. Buffer Safety
+- [ ] No `strcpy` — use `snprintf` or `strncpy` with null termination
+- [ ] `malloc` size calculations don't overflow (e.g., `count * sizeof(...)`)
+- [ ] No fixed-size stack buffers for unbounded input
+- [ ] `receive_n_data` always checks return value
+- [ ] Off-by-one in path concatenation
+
+### 3. Memory Safety in Error Paths
+- [ ] All error paths free allocated resources
+- [ ] No use-after-free on error paths
+- [ ] No double-free on error paths
+- [ ] Partial reads handled (don't use incomplete data)
+
+### 4. TLS/SSL Security
+- [ ] TLS 1.2 minimum enforced (no SSLv3, TLS 1.0, TLS 1.1)
+- [ ] Certificate verification enabled when CA provided
+- [ ] Certificate verification disabled only with explicit warning
+- [ ] Private key file permissions checked
+- [ ] No hardcoded certificates or keys
+- [ ] Cipher suites restricted to strong algorithms
+- [ ] SSL error codes checked after `SSL_read`/`SSL_write`
+
+### 5. Authentication & Authorization
+- [ ] SSH transport relies on SSH authentication (not custom auth)
+- [ ] No password/credential storage in plaintext
+- [ ] Server doesn't trust client-supplied paths blindly
+- [ ] Destination directory validated before writing
+
+### 6. Denial of Service
+- [ ] Bounded memory allocation (can't OOM server with huge chunk)
+- [ ] Timeout on connections (no indefinite blocking)
+- [ ] Maximum connection limit or rate limiting
+- [ ] Malformed protocol messages handled gracefully (no crash)
+
+### 7. Cryptographic Practices
+- [ ] No custom crypto — uses OpenSSL only
+- [ ] No hardcoded keys, IVs, or salts
+- [ ] Random data from `/dev/urandom` or OpenSSL `RAND_bytes`
+
+### 8. File System Security
+- [ ] Received file permissions validated (no SUID/SGID injection)
+- [ ] Symlink attack prevention (don't follow symlinks in destination)
+- [ ] Race conditions in file creation (TOCTOU)
+- [ ] Temporary file security (if any)
+
+## Common Vulnerability Patterns
+
+### Format String Bugs
+```c
+// VULNERABLE
+printf(user_data);
+
+// SAFE
+printf("%s", user_data);
+```
+
+### Integer Overflow in Allocation
+```c
+// VULNERABLE — count * size can overflow
+void *buf = malloc(count * sizeof(Entry));
+
+// SAFE
+if (count > SIZE_MAX / sizeof(Entry)) return NULL;
+void *buf = malloc(count * sizeof(Entry));
+```
+
+### Path Traversal
+```c
+// VULNERABLE — client sends "../../../etc/passwd"
+char path[PATH_MAX];
+snprintf(path, PATH_MAX, "%s/%s", dest_dir, received_filename);
+
+// SAFE — reject paths containing ".."
+if (strstr(received_filename, "..")) { /* reject */ }
+```
+
+### Unchecked Return Values
+```c
+// VULNERABLE — short read leaves buffer partially filled
+receive_n_data(fd, buffer, expected_size);
+
+// SAFE
+if (!receive_n_data(fd, buffer, expected_size)) { /* handle error */ }
+```
+
+## Output Format
+
+For each vulnerability found:
+1. **Location** — file:line
+2. **Severity** — critical / high / medium / low / informational
+3. **Category** — input-validation / buffer / memory / tls / auth / dos / crypto / fs
+4. **Description** — what the vulnerability is
+5. **Exploit scenario** — how it could be triggered
+6. **Fix** — concrete code change
+7. **CVSS estimate** — rough severity score if exploitable
+
+Also provide a summary:
+```
+=== SECURITY AUDIT SUMMARY ===
+Files audited: <count>
+Critical: <count>
+High: <count>
+Medium: <count>
+Low: <count>
+Informational: <count>
+```

.opencode/agents/test-writer.md

@@ -115,6 +115,92 @@ RUN_TEST(test_<module>);
 cmake -B build -S . && cmake --build build -j$(nproc) && ./build/tests
 ```
 
+## Fuzzing Targets
+
+When writing fuzzing harnesses, use `AFL++` or `libFuzzer`:
+
+### libFuzzer Harness Example
+```c
+// tests/fuzz_chunk_deserialize.c
+#include "chunk.h"
+#include <stdint.h>
+#include <stdlib.h>
+
+int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
+    // Create a Data wrapper and try to deserialize
+    Data *input = data_create((void *)data, size);
+    // Exercise the deserialization path
+    // (depends on what function you're fuzzing)
+    data_destroy(input);
+    return 0;
+}
+```
+
+Build for fuzzing:
+```bash
+cmake -B build-fuzz -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=fuzzer,address,undefined -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=fuzzer,address,undefined"
+cmake --build build-fuzz -j$(nproc)
+./build-fuzz/tests/fuzz_chunk_deserialize corpus/ -max_len=1048576
+```
+
+### AFL++ Harness
+```c
+// AFL++ uses stdin by default
+#include "protocol.h"
+#include <stdint.h>
+#include <unistd.h>
+
+int main() {
+    uint8_t buf[65536];
+    ssize_t n = read(STDIN_FILENO, buf, sizeof(buf));
+    if (n <= 0) return 0;
+    // Exercise parsing with the input
+    Data *input = data_create(buf, n);
+    data_destroy(input);
+    return 0;
+}
+```
+
+## Integration Test Patterns
+
+When writing integration tests (Python-based), follow the patterns in `tests/integration/`:
+- `common.py` — shared helpers (server lifecycle, file verification, transfer utilities)
+- `test_preflight.py` — preflight checks and configuration validation
+- `test_tcp.py` — TCP transport tests
+- `test_ssh.py` — SSH transport tests
+- `test_tls.py` — TLS transport tests
+- `test_features.py` — feature-specific tests (delete, exclude, incremental, etc.)
+
+Use `conftest.py` fixtures for server setup/teardown.
+
+### Minimal Integration Test
+```python
+def test_basic_transfer(tmp_path):
+    # Setup
+    source = tmp_path / "src"
+    dest = tmp_path / "dst"
+    source.mkdir()
+    dest.mkdir()
+    (source / "file.txt").write_text("test content")
+
+    # Start server and run client (use fixtures from conftest.py)
+    # Verify with helper from common.py
+```
+
+### Edge Case Tests to Write
+- Empty directory sync
+- Single file sync
+- Very large file (> chunk size)
+- Many small files (1000+)
+- Path with spaces/special characters
+- Symlinks in source
+- Permission-restricted files
+- Network interruption mid-transfer
+- Server crash during transfer
+- Concurrent clients (if supported)
+
 ## Output
 
 When asked to write tests, produce:
@@ -122,3 +208,4 @@ When asked to write tests, produce:
 2. The test source file content
 3. The runner.c modification needed
 4. Verify with a build and test run
+5. Suggest fuzzing targets if relevant

.opencode/skills/benchmark/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: benchmark
+description: Runs performance benchmarks on FastSync, collects metrics, compares configurations, and reports throughput. Use when the user says "benchmark", "measure performance", "profile", or wants to compare transfer speeds.
+---
+
+# Benchmark Skill
+
+Runs performance benchmarks and collects metrics. This skill CAN edit files for benchmark scripts and run builds/tests.
+
+## Workflow
+
+### Step 1: Build Optimized
+
+```bash
+rm -rf build
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j$(nproc)
+```
+
+### Step 2: Generate Test Data
+
+```bash
+mkdir -p /tmp/fastsync_bench/src
+# Small files
+for i in $(seq 1 100); do
+  dd if=/dev/urandom of=/tmp/fastsync_bench/src/small_$i.bin bs=1K count=10 2>/dev/null
+done
+# Medium files
+for i in $(seq 1 20); do
+  dd if=/dev/urandom of=/tmp/fastsync_bench/src/med_$i.bin bs=1M count=1 2>/dev/null
+done
+# Large files
+dd if=/dev/urandom of=/tmp/fastsync_bench/src/large.bin bs=1M count=10 2>/dev/null
+```
+
+### Step 3: Run Benchmarks
+
+Test each configuration 3 times, record median:
+
+```bash
+CONFIGS=(
+  "Standard|"
+  "Compression|-c"
+  "Multithreading|-m"
+  "MT+Compression|-m -c"
+  "Chunk Serialization|-s"
+  "MT+Compression+Chunk|-m -c -s"
+  "Sendfile|-f"
+)
+
+for config in "${CONFIGS[@]}"; do
+  IFS='|' read -r name flags <<< "$config"
+  echo "=== $name ==="
+  for run in 1 2 3; do
+    rm -rf /tmp/fastsync_bench/dst
+    mkdir -p /tmp/fastsync_bench/dst
+    
+    ./build/server &
+    SERVER_PID=$!
+    sleep 0.5
+    
+    START=$(date +%s%N)
+    ./build/client --source-dir /tmp/fastsync_bench/src \
+      --dest-dir /tmp/fastsync_bench/dst \
+      --save-to-disk $flags
+    END=$(date +%s%N)
+    
+    ELAPSED=$(( (END - START) / 1000000 ))
+    echo "  Run $run: ${ELAPSED}ms"
+    
+    kill $SERVER_PID 2>/dev/null
+    wait $SERVER_PID 2>/dev/null
+  done
+done
+```
+
+### Step 4: Full Integration Benchmark (Optional)
+
+For comprehensive benchmarking with network shaping:
+```bash
+python3 test.py --full
+```
+
+This tests LAN/WAN profiles, SSH, TLS, and compares against rsync.
+
+### Step 5: Report Results
+
+```
+=== BENCHMARK RESULTS ===
+Test data: <size> MB (<file count> files)
+Platform: <OS, CPU, network>
+
+Configuration          | Run 1   | Run 2   | Run 3   | Median
+-----------------------|---------|---------|---------|--------
+Standard               | 0.12s   | 0.11s   | 0.12s   | 0.12s
+Compression (-c)       | 0.09s   | 0.08s   | 0.09s   | 0.09s
+Multithreading (-m)    | 0.07s   | 0.07s   | 0.08s   | 0.07s
+MT+Compression (-m -c) | 0.05s   | 0.05s   | 0.06s   | 0.05s
+Sendfile (-f)          | 0.04s   | 0.04s   | 0.04s   | 0.04s
+
+Best configuration: MT+Compression (-m -c)
+Throughput: <X> MB/s
+```
+
+### Step 6: Profiling (If Requested)
+
+For detailed profiling:
+```bash
+# perf
+perf record -g ./build/client [args...]
+perf report
+
+# gprof
+gcc -pg -o build/client_profile [sources]
+./build/client_profile [args]
+gprof build/client_profile gmon.out
+```
+
+## Rules
+- DO build with Release mode for benchmarks
+- DO run each config multiple times (at least 3)
+- DO clean destination between runs
+- DO report median, not just one run
+- DON'T run benchmarks during active development (noisy results)
+- ALWAYS clean up test data after benchmarking

.opencode/skills/debug-workflow/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: debug-workflow
+description: Debugs crashes, memory errors, hangs, and logic bugs in FastSync using structured methodology. Use when the user says "debug X", "fix crash", "investigate failure", "there's a bug", or needs help diagnosing issues.
+---
+
+# Debug Workflow Skill
+
+Structured debugging for FastSync: reproduce → isolate → diagnose → fix → verify. This skill CAN edit files, build, and run tests.
+
+## Workflow
+
+### Step 1: Understand the Problem
+
+Ask or gather:
+- What's the symptom? (crash, hang, wrong output, valgrind error)
+- What command triggers it?
+- Is it deterministic or intermittent?
+- What's the environment? (OS, compiler, network conditions)
+
+### Step 2: Reproduce
+
+Build with debug info:
+```bash
+rm -rf build
+cmake -B build -S . -DCMAKE_BUILD_TYPE=Debug
+cmake --build build -j$(nproc)
+```
+
+Try to reproduce the issue with the exact command the user provides.
+
+### Step 3: Isolate with Sanitizers
+
+**Memory errors (first priority):**
+```bash
+rm -rf build
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
+cmake --build build -j$(nproc)
+./build/tests
+# or run the failing command
+```
+
+**Thread errors:**
+```bash
+rm -rf build
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=thread -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+cmake --build build -j$(nproc)
+./build/tests
+```
+
+**Valgrind (if ASan doesn't find it):**
+```bash
+valgrind --leak-check=full --show-leak-kinds=all --track-origins=yes \
+  ./build/client --source-dir /tmp/src --dest-dir /tmp/dst --save-to-disk
+```
+
+### Step 4: GDB Analysis
+
+If the issue is a crash or hang:
+```bash
+gdb --args ./build/client [args...]
+(gdb) run
+# when it crashes:
+(gdb) bt full
+(gdb) info locals
+(gdb) print variable_name
+```
+
+For hangs:
+```bash
+# In another terminal:
+kill -SIGABRT <pid>  # generates core dump
+gdb ./build/client core
+(gdb) thread apply all bt
+```
+
+### Step 5: Read the Code
+
+Read the relevant source files around the crash/failure point. Look for:
+- Unchecked return values
+- Null pointer dereferences
+- Buffer overflows
+- Use-after-free
+- Race conditions
+- Incorrect protocol handling
+
+### Step 6: Diagnose Root Cause
+
+Identify the exact file:line and what's wrong. Common patterns:
+- `send_n_data` / `receive_n_data` return value not checked
+- `data_destroy()` called but pointer still used
+- Queue operation without mutex in threaded code
+- Partial read/write not handled
+- Integer overflow in size calculations
+
+### Step 7: Fix
+
+Apply the minimal fix. Don't refactor while debugging — one change at a time.
+
+### Step 8: Verify
+
+```bash
+# Rebuild and test
+cmake -B build -S . && cmake --build build -j$(nproc)
+./build/tests
+
+# If integration test needed
+python3 test.py
+
+# Re-run under sanitizer to confirm fix
+rm -rf build
+cmake -B build -S . -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
+cmake --build build -j$(nproc)
+# reproduce the original failing command
+```
+
+### Step 9: Report
+
+Print a summary:
+```
+=== DEBUG SUMMARY ===
+Symptom: <what was happening>
+Root cause: <file:line — what's wrong>
+Fix: <what was changed>
+Verification: <how it was confirmed fixed>
+```
+
+## Rules
+- DO edit source files to fix issues
+- DO rebuild and test after fixes
+- DON'T refactor while debugging — minimal changes only
+- DON'T change behavior beyond fixing the bug
+- PRESERVE existing code style
+- ALWAYS verify with `./build/tests` after changes

.opencode/skills/pr-build/SKILL.md

@@ -32,6 +32,28 @@ cmake --build build -j$(nproc) 2>&1
 
 Capture both stdout and stderr.
 
+### Step 2b: Sanitizer build (if issues suspected)
+
+If the PR touches threading, memory management, or network code, also build with sanitizers:
+
+```bash
+# AddressSanitizer
+rm -rf build-asan
+cmake -B build-asan -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
+cmake --build build-asan -j$(nproc)
+./build-asan/tests
+
+# ThreadSanitizer (if threading changes)
+rm -rf build-tsan
+cmake -B build-tsan -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=thread -g" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+cmake --build build-tsan -j$(nproc)
+./build-tsan/tests
+```
+
 ### Step 3: Handle build failures
 
 If the build fails, read the error output carefully. Common issues:
@@ -92,6 +114,8 @@ Print a summary:
 Branch: <branch-name>
 Build: [PASS/FAIL]
 Unit tests: [PASS/FAIL] (<passed>/<total>)
+ASan: [CLEAN/ERRORS]
+TSan: [CLEAN/ERRORS/SKIPPED]
 Integration tests: [PASS/FAIL/SKIPPED]
 
 Fixes applied: <count>

.opencode/skills/pr-review/SKILL.md

@@ -69,12 +69,29 @@ For each changed file, review for:
 - Functions return appropriate error values
 - Error messages are useful
 
+**Security**
+- No `strcpy`/`strcat`/`sprintf` — use `snprintf` with bounds
+- `malloc` size calculations don't overflow
+- Path traversal prevention (`..` in filenames)
+- No fixed-size stack buffers for unbounded input
+- TLS error codes checked after `SSL_read`/`SSL_write`
+- No hardcoded certificates, keys, or credentials
+- Received file permissions validated (no SUID/SGID injection)
+- Denial of service: bounded memory, malformed messages handled
+
+**Performance Impact**
+- Unnecessary memory copies in hot paths
+- Excessive malloc/free in tight loops
+- Missing `sendfile()` opportunity for large files
+- Compression level appropriate for use case
+- Queue sizing appropriate for workload
+
 ### Step 5: Categorize findings
 
 For each issue:
 1. **File:line** — exact location
 2. **Severity** — critical / warning / style
-3. **Category** — memory / thread / protocol / logic / error
+3. **Category** — memory / thread / protocol / security / performance / logic / error
 4. **Description** — what's wrong and how to fix it
 
 ### Step 6: Output report

.opencode/skills/refactor/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: refactor
+description: Refactors FastSync code for structural improvements — DRY, separation of concerns, API simplification. Use when the user says "refactor X", "clean up code", "improve structure", or wants to reduce duplication.
+---
+
+# Refactor Skill
+
+Read-only analysis + code edits for structural improvements. This skill CAN edit files but MUST verify tests pass.
+
+## Workflow
+
+### Step 1: Identify Refactoring Target
+
+Ask or determine:
+- What code needs refactoring?
+- What's the problem? (duplication, complexity, wrong abstraction, naming)
+- What's the scope? (single function, module, cross-module)
+
+### Step 2: Read and Understand
+
+Read the relevant source files completely. Understand:
+- What the code does
+- How it fits in the larger system
+- What depends on it
+- What it depends on
+
+### Step 3: Verify Baseline
+
+Before any changes, confirm tests pass:
+```bash
+cmake -B build -S . && cmake --build build -j$(nproc)
+./build/tests
+```
+
+### Step 4: Plan the Refactor
+
+Document the plan:
+1. What changes will be made
+2. What behavior is preserved
+3. What risks exist
+4. How to verify correctness
+
+### Step 5: Implement
+
+Make the changes, one logical step at a time. Follow existing code conventions:
+- Header guards: `#ifndef FILENAME_H`
+- Naming: `snake_case` with module prefix
+- `static` for file-local functions
+- Pointer style: `Type *name`
+- Error handling: return `false`/`NULL` on failure
+
+### Step 6: Build and Test
+
+```bash
+cmake -B build -S . && cmake --build build -j$(nproc)
+./build/tests
+```
+
+ALL tests must pass. If a test fails, investigate and fix.
+
+### Step 7: Report
+
+Print a summary:
+```
+=== REFACTOR SUMMARY ===
+Target: <what was refactored>
+Changes:
+  - <list of changes>
+Tests: <passed/total>
+Behavior preserved: yes
+```
+
+## Rules
+- DO edit source files
+- DO run tests after changes
+- DO follow existing code conventions
+- DON'T change observable behavior
+- DON'T fix bugs while refactoring (separate concern)
+- DON'T add new features during refactoring
+- DON'T rewrite from scratch — incremental changes
+- ALWAYS verify tests pass before AND after

.opencode/skills/release/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: release
+description: Prepares a FastSync release — version bump, changelog, build verification, and git tagging. Use when the user says "prepare release", "bump version", "tag release", or wants to cut a new version.
+---
+
+# Release Skill
+
+Prepares a new release of FastSync. This skill CAN edit files, commit, and tag.
+
+## Workflow
+
+### Step 1: Determine Version
+
+Ask the user or determine from context:
+- **Major** (X.0.0) — breaking protocol changes, incompatible CLI changes
+- **Minor** (x.Y.0) — new features, backward compatible
+- **Patch** (x.y.Z) — bug fixes, no protocol changes
+
+Current version: `PROTOCOL_VERSION "1.1.0"` in `src/shared/config.h`
+
+### Step 2: Check Protocol Version
+
+If the wire protocol changed, bump `PROTOCOL_VERSION` in `src/shared/config.h`:
+```c
+#define PROTOCOL_VERSION "1.2.0"  // or "2.0.0" for breaking
+```
+
+Protocol version changes require:
+- Both client and server to be updated together
+- Backward compatibility considerations documented
+- Migration path clear
+
+### Step 3: Verify Build and Tests
+
+```bash
+rm -rf build
+cmake -B build -S .
+cmake --build build -j$(nproc)
+./build/tests
+python3 test.py
+```
+
+ALL tests must pass before release.
+
+### Step 4: Run Sanitizer Checks
+
+```bash
+# ASan
+rm -rf build
+cmake -B build -S . \
+  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
+  -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address"
+cmake --build build -j$(nproc)
+./build/tests
+```
+
+### Step 5: Update README (If Needed)
+
+Check if README needs updates:
+- New features documented
+- New CLI flags documented
+- Benchmark results updated
+- Build instructions current
+
+### Step 6: Create Release Commit
+
+```bash
+git add -A
+git commit -m "Release vX.Y.Z
+
+- <list of changes>
+- Protocol version: X.Y.Z
+- Tested: unit tests, integration tests, ASan"
+```
+
+### Step 7: Tag the Release
+
+```bash
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+```
+
+### Step 8: Push
+
+```bash
+git push origin main --tags
+```
+
+### Step 9: Report
+
+```
+=== RELEASE SUMMARY ===
+Version: vX.Y.Z
+Protocol: X.Y.Z
+Commit: <hash>
+Tag: vX.Y.Z
+Changes:
+  - <list of changes in this release>
+Build: PASS
+Tests: PASS (<passed>/<total>)
+ASan: CLEAN
+```
+
+## Rules
+- DO verify all tests pass before release
+- DO run sanitizer checks before release
+- DO update README if features changed
+- DO tag releases with annotated tags
+- DON'T release if tests fail
+- DON'T skip sanitizer checks
+- DON'T change code during release (only version bump + docs)

.opencode/skills/security-audit/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: security-audit
+description: Performs a security audit of FastSync — checks TLS config, input validation, buffer safety, crypto hygiene, and network attack surface. Use when the user says "security audit", "check security", "harden", or wants a security review.
+---
+
+# Security Audit Skill
+
+Read-only security review of the FastSync codebase or specific modules. Produces a report — does NOT edit files.
+
+## Workflow
+
+### Step 1: Scope the Audit
+
+Determine what to audit:
+- Full codebase audit
+- Specific module (e.g., `transport_tls.c`, `protocol.c`)
+- Specific vulnerability class (e.g., buffer overflows, TLS misconfig)
+
+### Step 2: Identify Attack Surface
+
+Network input points:
+```
+src/server/server.c          — TCP accept, per-connection handling
+src/shared/protocol.c        — all wire protocol parsing
+src/shared/config.c          — config deserialization
+src/shared/chunk.c           — chunk deserialization
+src/shared/transport_tls.c   — TLS handshake and data
+src/shared/transport_ssh.c   — SSH data via stdio
+```
+
+### Step 3: Read All Relevant Files
+
+Read every file in scope completely. Focus on:
+- All `receive_*` calls and their validation
+- All `malloc`/`calloc` calls and their size calculations
+- All string operations (`strcpy`, `sprintf`, `snprintf`)
+- All path operations (filename handling, directory creation)
+- All TLS/SSL operations and error handling
+
+### Step 4: Apply Security Checklist
+
+#### Input Validation
+- [ ] All `receive_*` return values checked
+- [ ] Received size fields validated against bounds
+- [ ] Path traversal prevention (`..` in filenames)
+- [ ] Null bytes in filenames handled
+- [ ] Chunk/file counts validated before allocation
+
+#### Buffer Safety
+- [ ] No `strcpy` — use `snprintf`
+- [ ] `malloc` size calculations don't overflow
+- [ ] No fixed-size stack buffers for unbounded input
+- [ ] Off-by-one in path concatenation
+
+#### TLS/SSL
+- [ ] TLS 1.2 minimum enforced
+- [ ] Certificate verification when CA provided
+- [ ] SSL error codes checked after `SSL_read`/`SSL_write`
+- [ ] No hardcoded certificates/keys
+- [ ] Strong cipher suites only
+
+#### Memory Safety in Error Paths
+- [ ] All error paths free allocated resources
+- [ ] No use-after-free on error paths
+- [ ] Partial reads handled
+
+#### Denial of Service
+- [ ] Bounded memory allocation
+- [ ] Timeout on connections
+- [ ] Malformed messages handled gracefully
+
+### Step 5: Check for Common Vulnerabilities
+
+```bash
+# Grep for dangerous patterns
+grep -rn "strcpy\|strcat\|sprintf" src/
+grep -rn "malloc.*\*" src/  # potential integer overflow in size calc
+grep -rn "receive_n_data" src/  # check all return values
+grep -rn "NULL" src/ | grep -v "//"  # check null handling
+```
+
+### Step 6: Output Report
+
+```
+=== SECURITY AUDIT SUMMARY ===
+Scope: <what was audited>
+Files reviewed: <count>
+
+Critical: <count>
+High: <count>
+Medium: <count>
+Low: <count>
+Informational: <count>
+
+=== FINDINGS ===
+
+[1] <file:line> — CRITICAL (<category>)
+    Description: <what's wrong>
+    Exploit scenario: <how it could be triggered>
+    Fix: <concrete code change>
+
+...
+
+=== VERDICT ===
+[PASS] No critical/high issues found
+  — or —
+[FAIL] <N> critical/high issues must be fixed
+```
+
+## Rules
+- Do NOT edit any source files
+- Do NOT run builds or tests
+- Report ALL issues — don't filter or minimize
+- Be specific about line numbers and fix suggestions
+- Consider both remote and local attack vectors

CMakeLists.txt

@@ -11,6 +11,15 @@ add_compile_options(-Wall -g -O3)
 
 # add_link_options(-fsanitize=address)
 
+include(FetchContent)
+FetchContent_Declare(
+  xxhash
+  GIT_REPOSITORY https://github.com/Cyan4973/xxHash
+  GIT_TAG v0.8.3
+  SOURCE_SUBDIR cmake_unofficial
+)
+FetchContent_MakeAvailable(xxhash)
+
 set(THREADS_PREFER_PTHREAD_FLAG ON)
 find_package(Threads REQUIRED)
 
@@ -28,13 +37,13 @@ file(GLOB TEST_SRCS "tests/*.c")
 
 add_executable(server ${SERVER_SRCS} ${SHARED_SRCS})
 target_include_directories(server PRIVATE src/shared src/server src/client)
-target_link_libraries(server PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto)
+target_link_libraries(server PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto xxhash)
 
 add_executable(client ${CLIENT_SRCS} ${SHARED_SRCS})
 target_include_directories(client PRIVATE src/shared src/server src/client)
-target_link_libraries(client PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto)
+target_link_libraries(client PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto xxhash)
 
 add_executable(tests ${TEST_SRCS} ${SHARED_SRCS} src/client/scanner.c)
 target_include_directories(tests PRIVATE tests src/shared src/server src/client)
-target_link_libraries(tests PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto)
+target_link_libraries(tests PRIVATE Threads::Threads ${ZSTD_LIBRARY} OpenSSL::SSL OpenSSL::Crypto xxhash)
 

Dockerfile

@@ -1,6 +1,8 @@
 FROM ubuntu:24.04
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    gcc g++ make libc6-dev cmake libzstd-dev libssl-dev git ca-certificates curl && \
+    gcc g++ make libc6-dev cmake libzstd-dev libssl-dev git ca-certificates curl \
+    python3 python3-pip python3-venv openssl openssh-client && \
+    pip3 install --break-system-packages pytest && \
     curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
     apt-get install -y --no-install-recommends nodejs && \
     rm -rf /var/lib/apt/lists/*

README.md

@@ -1,35 +1,43 @@
 # FastSync
 
-A high-performance file synchronization system with SSH and TCP transport, streaming zstd compression, multithreaded transfer, metadata preservation, and rsync-compatible CLI flags.
+A high-performance file synchronization system with SSH and TCP transport, TLS encryption, streaming zstd compression, multithreaded transfer, incremental sync, metadata preservation, and rsync-compatible CLI flags.
 
 ## Technical Overview
 
 1. **Dual transport**: custom TCP client-server or SSH subprocess (rsync-style `user@host:/path`)
-2. **Chunked file transfer**: files grouped into configurable-size chunks (default ~10 MB)
-3. **Streaming zstd compression** (levels 1–22) using `ZSTD_compressStream2`
-4. **Multithreading**: producer-consumer pipeline with thread-safe queues (scanner → loader → sender)
-5. **Metadata preservation**: `mode`, `uid`, `gid`, `mtime` restored on disk when enabled
-6. **`sendfile()` zero-copy** on TCP (~2× faster on loopback)
-7. **SSH ControlMaster** for connection reuse across repeated invocations
-8. **`--delete`**: receiver removes files not present in sender manifest
-9. **`--exclude`**: glob-pattern filename filtering (`*`, `?`, no `/` crossing)
+2. **TLS encryption**: OpenSSL-based TLS 1.2+ for encrypted TCP connections
+3. **Chunked file transfer**: files grouped into configurable-size chunks (default ~10 MB)
+4. **Streaming zstd compression** (levels 1–22) using `ZSTD_compressStream2`
+5. **Multithreading**: producer-consumer pipeline with thread-safe queues (scanner → loader → sender)
+6. **Incremental sync**: skip files unchanged since last transfer (compares size + mtime)
+7. **Metadata preservation**: `mode`, `uid`, `gid`, `mtime` restored on disk when enabled
+8. **`sendfile()` zero-copy** on TCP (~2× faster on loopback)
+9. **SSH ControlMaster** for connection reuse across repeated invocations
+10. **Bandwidth limiting**: token-bucket throttling (`--bwlimit`)
+11. **`--delete`**: receiver removes files not present in sender manifest
+12. **`--exclude` / `--include`**: glob-pattern filename filtering
 
 ## System Architecture
 
 ### Client
-- Recursively scans source directories (BFS), supports exclude patterns
+- Recursively scans source directories (BFS), supports exclude and include patterns
 - Groups files into chunks (configurable size)
 - Streaming zstd compression with configurable level
 - Chunk serialization (compact binary format) or per-file transfer
+- Incremental transfer: sends file metadata to server, skips unchanged files
 - Manifests all sent paths when `--delete` is active
 - Sends via TCP `sendfile()` or SSH pipe
 - Optional progress display with throughput
+- Bandwidth limiting via token-bucket algorithm
 
 ### Server
-- TCP mode: listens on port 8080; SSH mode: runs via `--stdio`
+- TCP mode: listens on configurable port (default 8080); SSH mode: runs via `--stdio`
+- TLS mode: wraps TCP connections with OpenSSL
 - Receives and reassembles files
 - Decompresses (streaming zstd), deserializes, restores metadata
+- Handles incremental checks: compares size + mtime against destination files
 - Processes `STATUS_MANIFEST` for `--delete`: walks destination tree, removes extras
+- Per-connection concurrency via `fork()`
 - Thread pool for parallel processing
 
 ## Protocol Details
@@ -43,6 +51,7 @@ A high-performance file synchronization system with SSH and TCP transport, strea
 | `STATUS_NEXT` | Ready for next file (per-file mode) |
 | `STATUS_CHUNK` | Following data is a serialized chunk |
 | `STATUS_MANIFEST` | Following data is a file manifest (for `--delete`) |
+| `STATUS_CHECK` | Incremental check: client sends file path + size + mtime, server responds with OK (skip) or NEXT (send) |
 
 ### Wire Format — Metadata
 
@@ -50,11 +59,17 @@ When `use_metadata` is enabled (`-M`), each file entry carries a 4-byte `present
 
 ### Transfer Flow
 ```
-Config → (STATUS_NEXT | STATUS_CHUNK)* → [STATUS_MANIFEST] → STATUS_FINISHED → STATUS_OK
+Config → (STATUS_NEXT | STATUS_CHUNK | STATUS_CHECK)* → [STATUS_MANIFEST] → STATUS_FINISHED → STATUS_OK
 ```
 
+### Protocol Version
+
+`1.1.0` — server and client must match. Mismatch results in `STATUS_ERROR`.
+
 ## Command-Line Arguments
 
+### Client
+
 | Argument | Description |
 |----------|-------------|
 | Positional | `<source> <dest>` — automatic SSH detection if dest contains `:` |
@@ -63,20 +78,42 @@ Config → (STATUS_NEXT | STATUS_CHUNK)* → [STATUS_MANIFEST] → STATUS_FINISH
 | `-a, --archive` | Archive mode: enables `-c -m -M` (no `-s`) |
 | `-m` | Multithreading mode |
 | `-s` | Chunk serialization (batch all files per chunk) |
-| `-f` | Sendfile zero-copy. Incompatible with `-c` / `-s`. TCP only. |
+| `-f, --sendfile` | Sendfile zero-copy. Incompatible with `-c` / `-s`. TCP only. |
 | `-M, --preserve` | Preserve file metadata (mode, uid, gid, mtime) |
 | `-n, --dry-run` | Scan and print what would be transferred |
 | `-p <port>` | SSH port (default: 22) |
+| `-v, --verbose` | Enable debug logging |
 | `--progress` | Show real-time transfer speed |
 | `--delete` | Delete files on receiver not present in source |
 | `--exclude <pattern>` | Exclude files matching glob pattern (repeatable) |
+| `--include <pattern>` | Only transfer files matching glob pattern (repeatable, whitelist) |
+| `--max-size <n>` | Skip files larger than n bytes |
+| `--min-size <n>` | Skip files smaller than n bytes |
+| `--incremental` | Skip files unchanged since last transfer (size + mtime). Auto-enables `--preserve`. Incompatible with `-s`. |
+| `--bwlimit <KB/s>` | Bandwidth limit in kilobytes per second |
 | `--chunk-size <n>` | Chunk size in bytes (default: 10485760) |
 | `--source-dir <path>` | Source directory (overrides `FASTSYNC_SOURCE_DIR`) |
 | `--dest-dir <path>` | Server destination directory (overrides `FASTSYNC_DEST_DIR`) |
 | `--save-to-disk` | Write received files to disk |
 | `--server-host <ip>` | Server IP address (default: `127.0.0.1`) |
 | `--server-port <n>` | Server port (default: `8080`) |
+| `--tls` | Enable TLS encryption |
+| `--cert <path>` | TLS certificate file (PEM) |
+| `--key <path>` | TLS private key file (PEM) |
+| `--ca <path>` | TLS CA certificate file for verification (PEM) |
+
+### Server
+
+| Argument | Description |
+|----------|-------------|
+| `--stdio` | Run in stdio mode (for SSH transport; single connection then exits) |
+| `-p <port>` | TCP listen port (default: 8080, range: 1–65535) |
+| `--tls` | Enable TLS encryption |
+| `--cert <path>` | TLS certificate file (PEM) |
+| `--key <path>` | TLS private key file (PEM) |
+| `--ca <path>` | TLS CA certificate file for verification (PEM) |
 | `-v, --verbose` | Enable debug logging |
+| `--help` | Show help |
 
 ## Environment Variables
 
@@ -92,26 +129,42 @@ Config → (STATUS_NEXT | STATUS_CHUNK)* → [STATUS_MANIFEST] → STATUS_FINISH
 1. **Chunk** — collection of files (~10 MB total by default)
 2. **File** — path, content (`Data`), optional `FileMetadata` pointer
 3. **FileMetadata** — `mode`, `uid`, `gid`, `mtime_sec`, `mtime_nsec`
-4. **Config** — runtime parameters (transported over wire)
+4. **Config** — runtime parameters (transported over wire, TLS settings excluded)
 5. **Queue** — thread-safe bounded queue with condition variables
-6. **DirectoryScanner** — recursive BFS traversal with exclude pattern support
+6. **DirectoryScanner** — recursive BFS traversal with exclude and include pattern support
 
 ### Key Algorithms
-1. **File scanning** — BFS directory traversal; each entry matched against exclude patterns
+1. **File scanning** — BFS directory traversal; entries matched against exclude and include patterns
 2. **Chunking** — files accumulated until `chunk_size` threshold, then flushed
 3. **Compression** — streaming zstd via `ZSTD_compressStream2` / `ZSTD_decompressStream`
 4. **Network protocol** — status-code-driven exchange with metadata packing
-5. **Metadata restoration** — `chmod()`, `chown()`, `utimensat()` on the receiving side
-6. **`--delete`** — sender tracks all sent paths; receiver walks destination tree and removes unlisted files/directories
-7. **SSH transport** — `socketpair()` + `fork()` + `execvp("ssh", ...)` with `ControlMaster` and port support
+5. **Incremental check** — client sends `STATUS_CHECK` + path + size + mtime; server compares against destination
+6. **Bandwidth limiting** — token-bucket algorithm with `nanosleep` throttling on 64 KB write chunks
+7. **Metadata restoration** — `chmod()`, `chown()`, `utimensat()` on the receiving side
+8. **`--delete`** — sender tracks all sent paths; receiver walks destination tree and removes unlisted files/directories
+9. **SSH transport** — `socketpair()` + `fork()` + `execvp("ssh", ...)` with `ControlMaster` and port support
+10. **TLS transport** — OpenSSL `SSL_CTX` with TLS 1.2 minimum, optional CA verification, transparent `SSL_read`/`SSL_write` via `io_set_ssl()`
 
 ## Build Requirements
 
 - C11 compiler
-- CMake 4.1+
-- zstd library (≥ 1.4.0 for streaming API)
+- CMake >= 3.22
+- zstd library
+- OpenSSL (development headers and libraries)
 - pthreads
-- SSH client (for SSH transport)
+- SSH client (for SSH transport mode only)
+
+### Installing Dependencies
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install cmake build-essential libzstd-dev libssl-dev openssh-client
+```
+
+**Nix:**
+```bash
+nix-shell  # provides zstd, openssl, cmake, gcc
+```
 
 ## Building
 
@@ -126,6 +179,14 @@ cmake -B build -S . && cmake --build build -j$(nproc)
 ./build/server
 ```
 
+### Server with TLS
+```bash
+./build/server --tls --cert server.pem --key server-key.pem
+```
+
+### Server via SSH
+Place the `fastsync-server` binary in the remote `$PATH`. The client runs `ssh user@host fastsync-server --stdio` automatically when an SSH-style destination is given.
+
 ### Client — SSH (rsync-style)
 ```bash
 ./build/client /path/to/send user@host:/path/to/receive
@@ -136,6 +197,12 @@ cmake -B build -S . && cmake --build build -j$(nproc)
 ./build/client --source-dir /path/to/send --dest-dir /path/to/receive --save-to-disk
 ```
 
+### Client — TCP with TLS
+```bash
+./build/client --tls --cert client.pem --key client-key.pem --ca ca.pem \
+  --source-dir /path/to/send --dest-dir /path/to/receive --save-to-disk
+```
+
 ### Common Options
 ```bash
 # Archive mode (compression + multithreading + metadata)
@@ -150,13 +217,16 @@ cmake -B build -S . && cmake --build build -j$(nproc)
 # Exclude temporary files + delete extras on receiver
 ./build/client --exclude "*.tmp" --exclude "*.o" --delete /src user@host:/dst
 
+# Incremental sync (skip unchanged files)
+./build/client --incremental /src user@host:/dst
+
+# Bandwidth limit to 1 MB/s
+./build/client --bwlimit 1024 /src user@host:/dst
+
 # All features
 ./build/client -a --progress --chunk-size 5242880 --exclude "*.log" --delete /src /dst
 ```
 
-### Server via SSH
-Place the `fastsync-server` binary in the remote `$PATH`. The client runs `ssh user@host fastsync-server --stdio` automatically when an SSH-style destination is given.
-
 ## Testing
 
 ```bash
@@ -178,6 +248,8 @@ The benchmark prints throughput metrics, best configuration, and speedup vs rsyn
 5. Metadata transfer adds negligible overhead (~24 bytes per file when enabled)
 6. SSH socketpair buffer set to 1 MB for improved pipe throughput
 7. SSH ControlMaster reuses connections across repeated invocations
+8. Incremental sync eliminates redundant transfers entirely
+9. Bandwidth limiting uses token-bucket with nanosleep for accurate throttling
 
 ## Benchmark Results
 

benchmark/bench.py

@@ -0,0 +1,519 @@
+#!/usr/bin/env python3
+"""Standalone benchmark tool for FastSync.
+
+Compares FastSync configs against rsync (no compression) and rsync+zstd.
+Data is ~75% random/incompressible and ~25% structured/compressible by default,
+controllable via --random-ratio.
+
+Usage:
+    python3 benchmark/bench.py
+    python3 benchmark/bench.py --runs 5 --profiles lan wan
+    python3 benchmark/bench.py --random-ratio 0.5 --size-mb 50
+    python3 benchmark/bench.py --delay 50ms --jitter 10ms --throughput 100mbit
+    python3 benchmark/bench.py --output json
+"""
+import argparse
+import json
+import os
+import random
+import shutil
+import socket
+import statistics
+import subprocess
+import sys
+import tempfile
+import time
+
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+BUILD_DIR = os.path.join(PROJECT_ROOT, "build")
+SERVER_CMD = [os.path.join(BUILD_DIR, "server")]
+CLIENT_CMD = [os.path.join(BUILD_DIR, "client")]
+BENCH_DIR = os.path.join(PROJECT_ROOT, "bench_data")
+
+NETWORK_PROFILES = {
+    "unlimited": {},
+    "lan": {
+        "rate": "1000mbit", "delay": "20ms", "jitter": "1ms", "loss": "0.1%",
+        "rate_bps": 1_000_000_000 / 8,
+    },
+    "wan": {
+        "rate": "100mbit", "delay": "50ms", "jitter": "10ms", "loss": "1%",
+        "rate_bps": 100_000_000 / 8,
+    },
+}
+
+FASTSYNC_CONFIGS = [
+    {"name": "fastsync",           "flags": [],                     "tool": "fastsync"},
+    {"name": "fastsync -c",        "flags": ["-c"],                 "tool": "fastsync"},
+    {"name": "fastsync -m",        "flags": ["-m"],                 "tool": "fastsync"},
+    {"name": "fastsync -m -c",     "flags": ["-m", "-c"],           "tool": "fastsync"},
+    {"name": "fastsync -m -c -s",  "flags": ["-m", "-c", "-s"],     "tool": "fastsync"},
+]
+
+RSYNC_CONFIGS = [
+    {"name": "rsync",              "flags": [],                     "tool": "rsync"},
+    {"name": "rsync -z",           "flags": ["-z"],                 "tool": "rsync"},
+    {"name": "rsync -z --zstd",    "flags": ["-z", "--zc", "zstd"],"tool": "rsync"},
+]
+
+class RsyncDaemon:
+    """Manages an rsync daemon for network-fair benchmarking."""
+
+    def __init__(self):
+        self._proc = None
+        self._port = None
+        self._conf_dir = None
+        self._module_path = None
+
+    def start(self, source_dir):
+        self._port = find_free_port()
+        self._conf_dir = tempfile.mkdtemp(prefix="rsyncd_")
+        self._module_path = source_dir
+
+        conf_path = os.path.join(self._conf_dir, "rsyncd.conf")
+        log_path = os.path.join(self._conf_dir, "rsyncd.log")
+
+        with open(conf_path, "w") as f:
+            f.write(f"uid = 0\ngid = 0\nuse chroot = no\nlog file = {log_path}\n")
+            f.write(f"[bench]\n\tpath = {source_dir}\n\tread only = yes\n")
+
+        self._proc = subprocess.Popen(
+            ["rsync", "--daemon", "--no-detach",
+             "--port", str(self._port),
+             "--config", conf_path],
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+        )
+        wait_for_port(self._port, timeout=5)
+
+    def stop(self):
+        if self._proc:
+            self._proc.terminate()
+            try:
+                self._proc.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+                self._proc.wait()
+            self._proc = None
+        if self._conf_dir:
+            shutil.rmtree(self._conf_dir, ignore_errors=True)
+            self._conf_dir = None
+
+    @property
+    def source_url(self):
+        return f"rsync://127.0.0.1:{self._port}/bench/"
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.stop()
+
+
+STRUCTURED_FILES = {
+    "small.txt": b"hello world\n",
+    "medium.txt": b"the quick brown fox jumps over the lazy dog\n" * 5000,
+    "binary.bin": bytes(range(256)) * 1000,
+    "nested/subdir/deep.txt": b"deeply nested file\n",
+    "nested/another.txt": b"another nested file\n" * 50,
+}
+
+
+class Progress:
+    """Simple progress bar with ETA."""
+
+    def __init__(self, total, label="Progress"):
+        self.total = total
+        self.current = 0
+        self.label = label
+        self.start_time = time.monotonic()
+        self._print()
+
+    def tick(self, detail=""):
+        self.current += 1
+        self._print(detail)
+
+    def _print(self, detail=""):
+        elapsed = time.monotonic() - self.start_time
+        if self.current > 0:
+            eta = elapsed / self.current * (self.total - self.current)
+            eta_str = f"ETA {eta:.0f}s"
+        else:
+            eta_str = "ETA ..."
+        pct = self.current / self.total * 100 if self.total else 0
+        bar_len = 30
+        filled = int(bar_len * self.current / self.total) if self.total else 0
+        bar = "#" * filled + "-" * (bar_len - filled)
+        detail_str = f"  {detail}" if detail else ""
+        sys.stderr.write(f"\r  [{bar}] {pct:5.1f}%  {self.current}/{self.total}  {eta_str}{detail_str}  ")
+        sys.stderr.flush()
+        if self.current >= self.total:
+            sys.stderr.write(f"\r  [{'#' * bar_len}] 100.0%  {self.total}/{self.total}  done in {elapsed:.1f}s" + " " * 30 + "\n")
+            sys.stderr.flush()
+
+
+def generate_bench_data(source_dir, size_mb=25, random_ratio=0.75):
+    """Generate test data. ~random_ratio is incompressible, rest is structured."""
+    if os.path.exists(source_dir):
+        shutil.rmtree(source_dir)
+    os.makedirs(source_dir)
+
+    target = size_mb * 1024 * 1024
+    structured_budget = int(target * (1 - random_ratio))
+    written = 0
+
+    for rel_path, content in STRUCTURED_FILES.items():
+        if written >= structured_budget:
+            break
+        full_path = os.path.join(source_dir, rel_path)
+        os.makedirs(os.path.dirname(full_path), exist_ok=True)
+        with open(full_path, "wb") as f:
+            f.write(content)
+        written += len(content)
+
+    os.makedirs(os.path.join(source_dir, "bulk"), exist_ok=True)
+    i = 0
+    while written < target:
+        chunk_size = min(5 * 1024 * 1024, target - written)
+        with open(os.path.join(source_dir, f"bulk/file_{i}.dat"), "wb") as f:
+            f.write(random.randbytes(chunk_size))
+        written += chunk_size
+        i += 1
+
+    return written
+
+
+def find_free_port():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+def wait_for_port(port, timeout=5):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.3):
+                return
+        except (ConnectionRefusedError, OSError):
+            time.sleep(0.05)
+    raise RuntimeError(f"Port {port} not ready")
+
+
+def wait_proc(proc, timeout=5):
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()
+
+
+def netem_apply(delay=None, jitter=None, throughput=None, loss=None):
+    """Apply tc/netem rules to loopback. Pass None to skip a parameter."""
+    netem_reset()
+    cmd = ["sudo", "tc", "qdisc", "add", "dev", "lo", "root", "netem"]
+    if throughput:
+        cmd += ["rate", throughput]
+    if delay:
+        cmd += ["delay", delay, jitter or "0ms"]
+    if loss:
+        cmd += ["loss", loss]
+    if len(cmd) > 6:
+        subprocess.run(cmd, check=True, capture_output=True)
+
+
+def netem_apply_profile(profile_name):
+    params = NETWORK_PROFILES.get(profile_name, {})
+    if not params:
+        netem_reset()
+        return
+    netem_apply(
+        delay=params.get("delay"),
+        jitter=params.get("jitter"),
+        throughput=params.get("rate"),
+        loss=params.get("loss"),
+    )
+
+
+def netem_reset():
+    subprocess.run("sudo tc qdisc del dev lo root".split(), capture_output=True)
+
+
+def run_fastsync(source_dir, dest_dir, flags, port):
+    """Run FastSync client. Returns duration or None."""
+    cmd = CLIENT_CMD + [
+        "--source-dir", source_dir,
+        "--dest-dir", dest_dir,
+        "--server-port", str(port),
+        "--save-to-disk",
+    ] + flags
+    try:
+        start = time.monotonic()
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+        duration = time.monotonic() - start
+        if result.returncode == 0:
+            return duration
+    except subprocess.TimeoutExpired:
+        pass
+    return None
+
+
+def run_rsync(source_dir, dest_dir, flags, rsync_daemon=None):
+    """Run rsync. Returns duration or None."""
+    src = source_dir.rstrip("/") + "/"
+    if rsync_daemon:
+        src = rsync_daemon.source_url
+    cmd = ["rsync", "-a", "--delete"] + flags + [src, dest_dir + "/"]
+    try:
+        start = time.monotonic()
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
+        duration = time.monotonic() - start
+        if result.returncode == 0:
+            return duration
+    except subprocess.TimeoutExpired:
+        pass
+    return None
+
+
+def run_transfer(config, source_dir, dest_dir, port=None, rsync_daemon=None):
+    """Route to the right tool. Returns duration or None."""
+    if config["tool"] == "rsync":
+        return run_rsync(source_dir, dest_dir, config["flags"], rsync_daemon)
+    else:
+        return run_fastsync(source_dir, dest_dir, config["flags"], port)
+
+
+def run_benchmark(source_dir, dest_dir, configs, runs, profile_name, progress=None):
+    """Run benchmark for all configs, returns list of results."""
+    is_limited = profile_name != "unlimited"
+    has_rsync = any(c["tool"] == "rsync" for c in configs)
+    if is_limited:
+        netem_apply_profile(profile_name)
+
+    rsync_daemon = None
+    try:
+        if is_limited and has_rsync:
+            rsync_daemon = RsyncDaemon()
+            rsync_daemon.start(source_dir)
+
+        results = []
+        for config in configs:
+            times = []
+            for run_idx in range(runs):
+                if os.path.exists(dest_dir):
+                    shutil.rmtree(dest_dir)
+                os.makedirs(dest_dir, exist_ok=True)
+
+                port = find_free_port()
+                server = None
+                try:
+                    if config["tool"] == "fastsync":
+                        server = subprocess.Popen(
+                            SERVER_CMD + ["-p", str(port)],
+                            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                        )
+                        wait_for_port(port)
+
+                    t = run_transfer(config, source_dir, dest_dir, port, rsync_daemon)
+                    if t is not None:
+                        times.append(t)
+                finally:
+                    if server:
+                        wait_proc(server)
+
+                if progress:
+                    progress.tick(f"{config['name']} (run {run_idx+1}/{runs})")
+
+            entry = {
+                "config": config["name"],
+                "tool": config["tool"],
+                "profile": profile_name,
+                "runs": len(times),
+                "times": [round(t, 4) for t in times],
+            }
+            if times:
+                entry["p50"] = round(statistics.median(times), 4)
+                entry["p95"] = round(sorted(times)[int(len(times) * 0.95)], 4) if len(times) > 1 else entry["p50"]
+                entry["min"] = round(min(times), 4)
+                entry["max"] = round(max(times), 4)
+                entry["stdev"] = round(statistics.stdev(times), 4) if len(times) > 1 else 0.0
+            results.append(entry)
+        return results
+    finally:
+        if rsync_daemon:
+            rsync_daemon.stop()
+        if is_limited:
+            netem_reset()
+
+
+def print_table(results, total_bytes, random_ratio):
+    """Print results as a human-readable table grouped by profile."""
+    profiles = {}
+    for r in results:
+        profiles.setdefault(r["profile"], []).append(r)
+
+    for profile, entries in profiles.items():
+        params = NETWORK_PROFILES.get(profile, {})
+        print(f"\n{'=' * 85}")
+        print(f" Profile: {profile.upper()}")
+        if params.get("rate"):
+            print(f" Network: {params['rate']}, {params['delay']} +/- {params['jitter']}, loss {params['loss']}")
+        else:
+            print(f" Network: unlimited")
+        print(f" Data: {total_bytes / (1024*1024):.1f} MB  ({random_ratio*100:.0f}% random, {(1-random_ratio)*100:.0f}% compressible)")
+        print(f"{'=' * 85}")
+
+        fs_entries = [e for e in entries if e.get("tool") == "fastsync"]
+        rsync_entries = [e for e in entries if e.get("tool") == "rsync"]
+
+        if fs_entries:
+            print(f"\n FastSync:")
+            print(f" {'Config':<25} {'p50':>8} {'p95':>8} {'min':>8} {'max':>8} {'stdev':>8} {'runs':>5}")
+            print(f" {'-' * 25} {'-' * 8} {'-' * 8} {'-' * 8} {'-' * 8} {'-' * 8} {'-' * 5}")
+            for e in sorted(fs_entries, key=lambda x: x.get("p50", 999)):
+                _print_entry(e)
+
+        if rsync_entries:
+            print(f"\n rsync:")
+            print(f" {'Config':<25} {'p50':>8} {'p95':>8} {'min':>8} {'max':>8} {'stdev':>8} {'runs':>5}")
+            print(f" {'-' * 25} {'-' * 8} {'-' * 8} {'-' * 8} {'-' * 8} {'-' * 8} {'-' * 5}")
+            for e in sorted(rsync_entries, key=lambda x: x.get("p50", 999)):
+                _print_entry(e)
+
+        if params.get("rate_bps") and fs_entries and rsync_entries:
+            fs_best = min((e["p50"] for e in fs_entries if "p50" in e), default=None)
+            rsync_best = min((e["p50"] for e in rsync_entries if "p50" in e), default=None)
+            theoretical = total_bytes / params["rate_bps"]
+            if fs_best and rsync_best:
+                print(f"\n Theoretical max (line rate): {theoretical:.4f}s")
+                print(f" FastSync best:   {fs_best:.4f}s  ({theoretical/fs_best:.2f}x vs line rate)")
+                print(f" rsync best:      {rsync_best:.4f}s  ({theoretical/rsync_best:.2f}x vs line rate)")
+                print(f" FastSync vs rsync: {rsync_best/fs_best:.2f}x faster")
+
+
+def _print_entry(e):
+    if "p50" in e:
+        print(f" {e['config']:<25} {e['p50']:>7.4f}s {e['p95']:>7.4f}s "
+              f"{e['min']:>7.4f}s {e['max']:>7.4f}s {e['stdev']:>7.4f} {e['runs']:>5}")
+    else:
+        print(f" {e['config']:<25} {'N/A':>8} {'N/A':>8} {'N/A':>8} {'N/A':>8} {'N/A':>8} {e['runs']:>5}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="FastSync benchmark tool — compares FastSync vs rsync",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+Network profiles (predefined):
+  unlimited   No artificial limits
+  lan         1 Gbit, 20ms delay, 1ms jitter, 0.1%% loss
+  wan         100 Mbit, 50ms delay, 10ms jitter, 1%% loss
+
+Custom network limits (--delay/--jitter/--throughput) override profiles.
+
+Data mix:
+  Default is ~75%% random/incompressible + ~25%% structured/compressible,
+  reflecting typical real-world file sets.
+
+Examples:
+  %(prog)s --profiles wan --runs 5
+  %(prog)s --throughput 50mbit --delay 30ms --jitter 5ms
+  %(prog)s --random-ratio 0.5 --size-mb 100
+""")
+    parser.add_argument("--runs", type=int, default=3,
+                        help="Number of runs per config (default: 3)")
+    parser.add_argument("--profiles", nargs="+", default=None,
+                        choices=list(NETWORK_PROFILES.keys()),
+                        help="Predefined network profiles (default: unlimited)")
+    parser.add_argument("--configs", nargs="+", default=None,
+                        help="Custom FastSync config flags")
+    parser.add_argument("--size-mb", type=int, default=25,
+                        help="Test data size in MB (default: 25)")
+    parser.add_argument("--random-ratio", type=float, default=0.75,
+                        help="Fraction of data that is random/incompressible (default: 0.75)")
+    parser.add_argument("--delay", default=None,
+                        help="Custom network delay (e.g. 50ms)")
+    parser.add_argument("--jitter", default=None,
+                        help="Custom network jitter (e.g. 10ms)")
+    parser.add_argument("--throughput", default=None,
+                        help="Custom throughput limit (e.g. 100mbit)")
+    parser.add_argument("--loss", default=None,
+                        help="Custom packet loss (e.g. 1%%)")
+    parser.add_argument("--no-rsync", action="store_true",
+                        help="Skip rsync comparison")
+    parser.add_argument("--progress", action="store_true",
+                        help="Show progress bar with ETA")
+    parser.add_argument("--output", choices=["table", "json"], default="table",
+                        help="Output format")
+    parser.add_argument("--keep-data", action="store_true",
+                        help="Don't clean up test data")
+    args = parser.parse_args()
+
+    # Build
+    print("Building...")
+    if os.system(f"cmake -B {BUILD_DIR} -S {PROJECT_ROOT} > /dev/null 2>&1") != 0:
+        print("CMake configure failed"); sys.exit(1)
+    if os.system(f"cmake --build {BUILD_DIR} -j$(nproc) > /dev/null 2>&1") != 0:
+        print("Build failed"); sys.exit(1)
+
+    # Determine active profile for display
+    has_custom_net = args.delay or args.jitter or args.throughput or args.loss
+    if has_custom_net:
+        active_profile = "custom"
+        NETWORK_PROFILES["custom"] = {
+            "rate": args.throughput, "delay": args.delay or "0ms",
+            "jitter": args.jitter or "0ms", "loss": args.loss or "0%",
+        }
+        if args.throughput:
+            parts = args.throughput.replace("mbit", "").replace("mbps", "")
+            try:
+                NETWORK_PROFILES["custom"]["rate_bps"] = float(parts) * 1_000_000 / 8
+            except ValueError:
+                pass
+        profiles_to_run = ["custom"]
+    else:
+        profiles_to_run = args.profiles or ["unlimited"]
+
+    # Generate data
+    source_dir = os.path.join(BENCH_DIR, "source")
+    dest_dir = os.path.join(BENCH_DIR, "dest")
+    total_bytes = generate_bench_data(source_dir, args.size_mb, args.random_ratio)
+    compressible_pct = (1 - args.random_ratio) * 100
+    random_pct = args.random_ratio * 100
+    print(f"Generated {total_bytes / (1024*1024):.1f} MB  "
+          f"({random_pct:.0f}% random, {compressible_pct:.0f}% compressible)")
+
+    # Build config list
+    if args.configs:
+        fastsync_configs = [{"name": c, "flags": c.split(), "tool": "fastsync"} for c in args.configs]
+    else:
+        fastsync_configs = list(FASTSYNC_CONFIGS)
+
+    configs = list(fastsync_configs)
+    if not args.no_rsync:
+        configs += RSYNC_CONFIGS
+
+    # Run benchmarks
+    total_runs = len(configs) * args.runs * len(profiles_to_run)
+    progress = Progress(total_runs, "Benchmarking") if args.progress else None
+    if progress:
+        print(f"Running {total_runs} transfers...")
+
+    all_results = []
+    try:
+        for profile in profiles_to_run:
+            results = run_benchmark(source_dir, dest_dir, configs, args.runs, profile, progress)
+            all_results.extend(results)
+    finally:
+        if not args.keep_data:
+            shutil.rmtree(BENCH_DIR, ignore_errors=True)
+
+    # Output
+    if args.output == "json":
+        print(json.dumps(all_results, indent=2))
+    else:
+        print_table(all_results, total_bytes, args.random_ratio)
+        print()
+
+
+if __name__ == "__main__":
+    main()

shell.nix

@@ -15,6 +15,7 @@ pkgs.mkShell {
   buildInputs = with pkgs; [
     zstd
     openssl
+    (python3.withPackages (ps: with ps; [ pytest ]))
   ];
 
   NIX_ENFORCE_PURITY = 0;

src/client/client_cli.c

@@ -1,5 +1,6 @@
 #include "client_send.h"
 #include "config.h"
+#include "delta.h"
 #include "log.h"
 #include "protocol.h"
 #include "transport_tls.h"
@@ -36,6 +37,9 @@ static void print_usage(void) {
   printf("  --max-size <n>      Skip files larger than n bytes\n");
   printf("  --min-size <n>      Skip files smaller than n bytes\n");
   printf("  --incremental       Skip files unchanged since last transfer\n");
+  printf("  --delta             Delta transfer for changed files (requires --incremental)\n");
+  printf("  --delta-block <n>   Delta block size in bytes (default: %d)\n", DELTA_BLOCK_SIZE_DEFAULT);
+  printf("  --delta-max <n>     Max file size for delta transfer (default: %llu)\n", DELTA_MAX_FILE_SIZE);
   printf("  -m                  Enable multithreading\n");
   printf("  -s                  Enable chunk serialization\n");
   printf("  -f                  Enable sendfile (TCP only, not with -c or -s)\n");
@@ -101,6 +105,20 @@ int main(int argc, char *argv[]) {
       config->min_size = strtoull(argv[++i], NULL, 10);
     } else if (strcmp(argv[i], "--incremental") == 0) {
       config->use_incremental = true;
+    } else if (strcmp(argv[i], "--delta") == 0) {
+      config->use_delta = true;
+    } else if (strcmp(argv[i], "--delta-block") == 0 && i + 1 < argc) {
+      unsigned long long val = strtoull(argv[++i], NULL, 10);
+      if (val >= DELTA_BLOCK_SIZE_MIN && val <= DELTA_BLOCK_SIZE_MAX)
+        config->delta_block_size = (uint32_t)val;
+      else
+        fprintf(stderr, "Warning: --delta-block value %llu out of range, using default\n", val);
+    } else if (strcmp(argv[i], "--delta-max") == 0 && i + 1 < argc) {
+      unsigned long long val = strtoull(argv[++i], NULL, 10);
+      if (val >= DELTA_MIN_FILE_SIZE)
+        config->delta_max_file_size = val;
+      else
+        fprintf(stderr, "Warning: --delta-max value %llu too small, using default\n", val);
     } else if (strcmp(argv[i], "-c") == 0 || strcmp(argv[i], "-z") == 0) {
       config->use_compression = true;
       log_message(LOG_LEVEL_INFO, "Enabled Compression");
@@ -231,6 +249,23 @@ int main(int argc, char *argv[]) {
     config->use_metadata = true;
   }
 
+  if (config->use_delta && !config->use_incremental) {
+    fprintf(stderr, "Error: --delta requires --incremental\n");
+    return 1;
+  }
+  if (config->use_delta && config->use_chunk_serialization) {
+    fprintf(stderr, "Error: --delta cannot be combined with -s (chunk serialization)\n");
+    return 1;
+  }
+  if (config->use_delta && config->use_sendfile) {
+    fprintf(stderr, "Error: --delta cannot be combined with -f (sendfile)\n");
+    return 1;
+  }
+  if (config->use_delta && !config->use_metadata) {
+    log_message(LOG_LEVEL_INFO, "Enabling metadata preservation for --delta");
+    config->use_metadata = true;
+  }
+
   if (config->use_tls) {
     if (!config->tls_cert || !config->tls_key) {
       fprintf(stderr, "Error: --tls requires --cert and --key\n");

src/client/client_send.c

@@ -1,9 +1,12 @@
 #include "client_send.h"
 #include "array_list.h"
 #include "chunk.h"
+#include "compression.h"
 #include "config.h"
 #include "data.h"
+#include "delta.h"
 #include "file.h"
+#include "metadata.h"
 #include "log.h"
 #include "multiprocessing.h"
 #include "protocol.h"
@@ -19,7 +22,9 @@
 #include <threads.h>
 #include <time.h>
 
-static int incremental_check(Client *client, File *file) {
+static int incremental_check(Client *client, File *file,
+                              DeltaSignature **out_sig) {
+  *out_sig = NULL;
   if (!send_status(client->file_descriptor, STATUS_CHECK)) return -1;
   if (!send_str(client->file_descriptor, file->path)) return -1;
   unsigned long long fsize = file->data->size;
@@ -33,6 +38,15 @@ static int incremental_check(Client *client, File *file) {
     return -1;
   }
   if (s == STATUS_OK) return 1;
+  if (s == STATUS_DELTA_SIGNATURE) {
+    Data *sig_data = receive_data(client->file_descriptor);
+    if (!sig_data) return -1;
+    DeltaSignature *sig = delta_signature_deserialize(sig_data);
+    data_destroy(sig_data);
+    if (!sig) return -1;
+    *out_sig = sig;
+    return 2;
+  }
   if (s != STATUS_NEXT) {
     log_message(LOG_LEVEL_ERROR, "Unexpected server status");
     return -1;
@@ -40,6 +54,61 @@ static int incremental_check(Client *client, File *file) {
   return 0;
 }
 
+static int send_delta(Client *client, File *file, DeltaSignature *sig,
+                       Config *config) {
+  Delta *delta = delta_compute(file->data->data, file->data->size,
+                                sig, config->delta_block_size);
+  if (!delta) return 1;
+
+  if (!delta_is_worthwhile(delta, file->data->size)) {
+    delta_destroy(delta);
+    if (!send_status(client->file_descriptor, STATUS_NEXT)) return -1;
+    return 1;
+  }
+
+  Data *delta_data = delta_serialize(delta);
+  delta_destroy(delta);
+  if (!delta_data) return -1;
+
+  Data *to_send = delta_data;
+  if (config->use_compression) {
+    to_send = data_compress(delta_data, config->compression_level);
+    data_destroy(delta_data);
+    if (!to_send) return -1;
+  }
+
+  bool ok = send_status(client->file_descriptor, STATUS_DELTA_DATA) &&
+            send_data(client->file_descriptor, to_send);
+
+  if (ok && config->use_metadata)
+    ok = metadata_send(client->file_descriptor, file->metadata);
+
+  data_destroy(to_send);
+  return ok ? 0 : -1;
+}
+
+typedef bool (*file_send_fn)(File *, int, bool, int, bool);
+
+static int send_file_incremental(Client *client, File *file, Config *config,
+                                  file_send_fn send_fn) {
+  DeltaSignature *sig = NULL;
+  int rc = incremental_check(client, file, &sig);
+  if (rc < 0) { delta_signature_destroy(sig); return -1; }
+  if (rc == 1) { delta_signature_destroy(sig); return 1; }
+  if (rc == 2 && config->use_delta) {
+    int drc = send_delta(client, file, sig, config);
+    delta_signature_destroy(sig);
+    if (drc == 0) return 0;
+    if (drc < 0) return -1;
+  } else {
+    delta_signature_destroy(sig);
+  }
+  if (!send_fn(file, client->file_descriptor, config->use_metadata,
+               config->use_compression ? config->compression_level : 0, false))
+    return -1;
+  return 0;
+}
+
 int send_chunk(Client *client, Chunk *chunk, Config *config) {
   if (config->use_chunk_serialization) {
     if (!send_status(client->file_descriptor, STATUS_CHUNK)) return -1;
@@ -55,28 +124,23 @@ int send_chunk(Client *client, Chunk *chunk, Config *config) {
   } else if (config->use_sendfile && !config->use_compression) {
     for (int i = 0; i < chunk->element_count; i++) {
       if (config->use_incremental) {
-        int rc = incremental_check(client, chunk->items[i]);
+        int rc = send_file_incremental(client, chunk->items[i], config,
+                                        (file_send_fn)file_send_sendfile);
+        if (rc == 1) continue;
         if (rc < 0) return -1;
-        if (rc > 0) continue;
-        if (!file_send_sendfile(chunk->items[i], client->file_descriptor, config->use_metadata, false))
-          return -1;
       } else {
         if (!send_status(client->file_descriptor, STATUS_NEXT)) return -1;
-        if (!file_send_sendfile(chunk->items[i], client->file_descriptor, config->use_metadata, true))
+        if (!file_send_sendfile(chunk->items[i], client->file_descriptor, config->use_metadata, 0, true))
           return -1;
       }
     }
   } else {
     for (int i = 0; i < chunk->element_count; i++) {
       if (config->use_incremental) {
-        int rc = incremental_check(client, chunk->items[i]);
+        int rc = send_file_incremental(client, chunk->items[i], config,
+                                        (file_send_fn)file_send_single_calls);
+        if (rc == 1) continue;
         if (rc < 0) return -1;
-        if (rc > 0) continue;
-        if (!file_send_single_calls(chunk->items[i], client->file_descriptor,
-                                   config->use_metadata,
-                                   config->use_compression ? config->compression_level : 0,
-                                   false))
-          return -1;
       } else {
         if (!send_status(client->file_descriptor, STATUS_NEXT)) return -1;
         if (!file_send_single_calls(chunk->items[i], client->file_descriptor,

src/client/scanner.c

@@ -154,5 +154,7 @@ Chunk *directory_scanner_next(DirectoryScanner *scanner) {
 
   if (chunk_data->size > 0)
     return chunk_data_to_chunk(chunk_data);
+  chunk_data->item_destroyer = NULL;
+  array_list_delete(chunk_data);
   return NULL;
 }

src/shared/config.c

@@ -1,4 +1,5 @@
 #include "config.h"
+#include "delta.h"
 #include "log.h"
 #include "protocol.h"
 #include "utils.h"
@@ -39,6 +40,9 @@ Config *config_create(char *version, char *send_directory,
   config->max_size = 0;
   config->min_size = 0;
   config->use_incremental = false;
+  config->use_delta = false;
+  config->delta_block_size = DELTA_BLOCK_SIZE_DEFAULT;
+  config->delta_max_file_size = DELTA_MAX_FILE_SIZE;
   config->use_tls = false;
   config->tls_cert = NULL;
   config->tls_key = NULL;
@@ -98,6 +102,9 @@ bool config_send(int file_descriptor, Config *config) {
   if (!send_int(file_descriptor, config->use_sendfile)) return false;
   if (!send_int(file_descriptor, config->use_delete)) return false;
   if (!send_int(file_descriptor, config->use_incremental)) return false;
+  if (!send_int(file_descriptor, config->use_delta)) return false;
+  if (!send_int(file_descriptor, (int)config->delta_block_size)) return false;
+  if (!send_n_data(file_descriptor, &config->delta_max_file_size, sizeof(unsigned long long))) return false;
   Status status;
   if (!receive_status(file_descriptor, &status)) return false;
   if (status != STATUS_OK) {
@@ -145,6 +152,11 @@ Config *config_receive(int file_descriptor) {
   config->use_delete = tmp;
   if (!receive_int(file_descriptor, &tmp)) goto error;
   config->use_incremental = tmp;
+  if (!receive_int(file_descriptor, &tmp)) goto error;
+  config->use_delta = tmp;
+  if (!receive_int(file_descriptor, &tmp)) goto error;
+  config->delta_block_size = (uint32_t)tmp;
+  if (!receive_n_data(file_descriptor, &config->delta_max_file_size, sizeof(unsigned long long))) goto error;
   config->show_progress = false;
   config->dry_run = false;
   config->ssh_port = 22;

src/shared/config.h

@@ -2,6 +2,7 @@
 #define CONFIG_H
 
 #include <stdbool.h>
+#include <stdint.h>
 
 typedef enum {
   TRANSPORT_TCP,
@@ -33,13 +34,16 @@ typedef struct Config {
   unsigned long long max_size;
   unsigned long long min_size;
   bool use_incremental;
+  bool use_delta;
+  uint32_t delta_block_size;
+  unsigned long long delta_max_file_size;
   bool use_tls;
   char *tls_cert;
   char *tls_key;
   char *tls_ca;
 } Config;
 
-#define PROTOCOL_VERSION "1.1.0"
+#define PROTOCOL_VERSION "1.2.0"
 #define DEFAULT_CHUNK_SIZE (10 * 1024 * 1024)
 
 Config *config_create(char *version, char *send_directory,

src/shared/delta.c

@@ -0,0 +1,487 @@
+#include "delta.h"
+#include "log.h"
+#include <stdlib.h>
+#include <string.h>
+
+#define XXH_STATIC_LINKING_ONLY
+#define XXH_IMPLEMENTATION
+#include <xxhash.h>
+
+uint32_t delta_adler32(const void *data, uint32_t len) {
+  const uint8_t *p = (const uint8_t *)data;
+  uint32_t s1 = 1;
+  uint32_t s2 = 0;
+  for (uint32_t i = 0; i < len; i++) {
+    s1 = (s1 + p[i]) % DELTA_ADLER32_MODULUS;
+    s2 = (s2 + s1) % DELTA_ADLER32_MODULUS;
+  }
+  return (s2 << 16) | s1;
+}
+
+uint32_t delta_xxhash32(const void *data, uint32_t len) {
+  return XXH32(data, len, 0);
+}
+
+DeltaSignature *delta_signature_create(const void *old_file_data,
+                                        uint64_t old_file_size,
+                                        uint32_t block_size) {
+  if (old_file_data == NULL || old_file_size == 0 || block_size == 0)
+    return NULL;
+
+  uint32_t block_count = (uint32_t)((old_file_size + block_size - 1) / block_size);
+
+  DeltaSignature *sig = malloc(sizeof(DeltaSignature));
+  if (!sig) return NULL;
+
+  sig->file_size = old_file_size;
+  sig->block_size = block_size;
+  sig->block_count = block_count;
+  sig->blocks = malloc(block_count * sizeof(DeltaBlockSig));
+  if (!sig->blocks) {
+    free(sig);
+    return NULL;
+  }
+
+  const uint8_t *data = (const uint8_t *)old_file_data;
+  for (uint32_t i = 0; i < block_count; i++) {
+    uint64_t offset = (uint64_t)i * block_size;
+    uint32_t len = (uint32_t)((old_file_size - offset < block_size)
+                                  ? (old_file_size - offset)
+                                  : block_size);
+    sig->blocks[i].adler32 = delta_adler32(data + offset, len);
+    sig->blocks[i].xxhash = delta_xxhash32(data + offset, len);
+  }
+
+  return sig;
+}
+
+Data *delta_signature_serialize(const DeltaSignature *sig) {
+  if (!sig) return NULL;
+
+  uint64_t total = sizeof(uint64_t) + sizeof(uint32_t) + sizeof(uint32_t) +
+                   (uint64_t)sig->block_count * (sizeof(uint32_t) + sizeof(uint32_t));
+
+  uint8_t *buf = malloc((size_t)total);
+  if (!buf) return NULL;
+
+  size_t pos = 0;
+  memcpy(buf + pos, &sig->file_size, sizeof(uint64_t));
+  pos += sizeof(uint64_t);
+  memcpy(buf + pos, &sig->block_size, sizeof(uint32_t));
+  pos += sizeof(uint32_t);
+  memcpy(buf + pos, &sig->block_count, sizeof(uint32_t));
+  pos += sizeof(uint32_t);
+
+  for (uint32_t i = 0; i < sig->block_count; i++) {
+    memcpy(buf + pos, &sig->blocks[i].adler32, sizeof(uint32_t));
+    pos += sizeof(uint32_t);
+    memcpy(buf + pos, &sig->blocks[i].xxhash, sizeof(uint32_t));
+    pos += sizeof(uint32_t);
+  }
+
+  return data_create(buf, (size_t)total);
+}
+
+DeltaSignature *delta_signature_deserialize(const Data *data) {
+  if (!data || data->size < sizeof(uint64_t) + sizeof(uint32_t) + sizeof(uint32_t))
+    return NULL;
+
+  const uint8_t *buf = (const uint8_t *)data->data;
+  size_t pos = 0;
+
+  DeltaSignature *sig = malloc(sizeof(DeltaSignature));
+  if (!sig) return NULL;
+
+  memcpy(&sig->file_size, buf + pos, sizeof(uint64_t));
+  pos += sizeof(uint64_t);
+  memcpy(&sig->block_size, buf + pos, sizeof(uint32_t));
+  pos += sizeof(uint32_t);
+  memcpy(&sig->block_count, buf + pos, sizeof(uint32_t));
+  pos += sizeof(uint32_t);
+
+  uint64_t expected = sizeof(uint64_t) + sizeof(uint32_t) + sizeof(uint32_t) +
+                      (uint64_t)sig->block_count * (sizeof(uint32_t) + sizeof(uint32_t));
+  if (data->size < expected) {
+    free(sig);
+    return NULL;
+  }
+
+  sig->blocks = malloc(sig->block_count * sizeof(DeltaBlockSig));
+  if (!sig->blocks) {
+    free(sig);
+    return NULL;
+  }
+
+  for (uint32_t i = 0; i < sig->block_count; i++) {
+    memcpy(&sig->blocks[i].adler32, buf + pos, sizeof(uint32_t));
+    pos += sizeof(uint32_t);
+    memcpy(&sig->blocks[i].xxhash, buf + pos, sizeof(uint32_t));
+    pos += sizeof(uint32_t);
+  }
+
+  return sig;
+}
+
+void delta_signature_destroy(DeltaSignature *sig) {
+  if (!sig) return;
+  free(sig->blocks);
+  free(sig);
+}
+
+static bool ensure_capacity(DeltaInstruction **instrs, uint32_t *capacity,
+                             uint32_t count) {
+  if (count < *capacity) return true;
+  uint32_t new_cap = *capacity * 2;
+  DeltaInstruction *tmp = realloc(*instrs, new_cap * sizeof(DeltaInstruction));
+  if (!tmp) return false;
+  *instrs = tmp;
+  *capacity = new_cap;
+  return true;
+}
+
+static bool flush_literal(DeltaInstruction **instrs, uint32_t *capacity,
+                           uint32_t *count, const uint8_t *data,
+                           uint64_t start, uint64_t end) {
+  if (start >= end) return true;
+  uint32_t lit_len = (uint32_t)(end - start);
+  if (!ensure_capacity(instrs, capacity, *count)) return false;
+  uint8_t *lit_data = malloc(lit_len);
+  if (!lit_data) return false;
+  memcpy(lit_data, data + start, lit_len);
+  (*instrs)[*count].type = DELTA_INSTR_LITERAL;
+  (*instrs)[*count].literal.data = lit_data;
+  (*instrs)[*count].literal.length = lit_len;
+  (*count)++;
+  return true;
+}
+
+Delta *delta_compute(const void *new_file_data, uint64_t new_file_size,
+                      const DeltaSignature *sig, uint32_t block_size) {
+  if (!new_file_data || !sig || new_file_size == 0 || block_size == 0)
+    return NULL;
+
+  const uint8_t *new_data = (const uint8_t *)new_file_data;
+
+  uint32_t capacity = 64;
+  uint32_t count = 0;
+  DeltaInstruction *instrs = malloc(capacity * sizeof(DeltaInstruction));
+  if (!instrs) return NULL;
+
+  uint64_t literal_start = 0;
+  bool has_literal = false;
+
+  uint64_t i = 0;
+
+  uint32_t s1 = 1, s2 = 0;
+  bool rolling_valid = false;
+
+  while (i < new_file_size) {
+    uint32_t window_len = (uint32_t)((new_file_size - i < block_size)
+                                         ? (new_file_size - i)
+                                         : block_size);
+    bool full_window = (window_len == block_size);
+
+    uint32_t adler;
+    if (rolling_valid && full_window) {
+      uint8_t old_byte = new_data[i - 1];
+      uint8_t new_byte = new_data[i + block_size - 1];
+      s1 = (s1 + DELTA_ADLER32_MODULUS - old_byte + new_byte) %
+           DELTA_ADLER32_MODULUS;
+      s2 = (s2 + DELTA_ADLER32_MODULUS -
+            (uint32_t)((uint64_t)block_size * old_byte % DELTA_ADLER32_MODULUS) +
+            s1 - 1) %
+           DELTA_ADLER32_MODULUS;
+      adler = (s2 << 16) | s1;
+    } else {
+      s1 = 1;
+      s2 = 0;
+      for (uint32_t k = 0; k < window_len; k++) {
+        s1 = (s1 + new_data[i + k]) % DELTA_ADLER32_MODULUS;
+        s2 = (s2 + s1) % DELTA_ADLER32_MODULUS;
+      }
+      adler = (s2 << 16) | s1;
+      rolling_valid = full_window;
+    }
+
+    bool matched = false;
+    for (uint32_t j = 0; j < sig->block_count; j++) {
+      if (adler == sig->blocks[j].adler32 && full_window) {
+        uint32_t xxh = delta_xxhash32(new_data + i, window_len);
+        if (xxh == sig->blocks[j].xxhash) {
+          if (has_literal) {
+            if (!flush_literal(&instrs, &capacity, &count, new_data,
+                               literal_start, i)) {
+              free(instrs);
+              return NULL;
+            }
+            has_literal = false;
+          }
+
+          if (!ensure_capacity(&instrs, &capacity, count)) {
+            free(instrs);
+            return NULL;
+          }
+          instrs[count].type = DELTA_INSTR_BLOCK_MATCH;
+          instrs[count].match.block_index = j;
+          instrs[count].match.block_offset = 0;
+          instrs[count].match.length = window_len;
+          count++;
+
+          i += window_len;
+          rolling_valid = false;
+          matched = true;
+          break;
+        }
+      }
+    }
+
+    if (!matched) {
+      if (!has_literal) {
+        literal_start = i;
+        has_literal = true;
+      }
+      i++;
+    }
+  }
+
+  if (has_literal) {
+    if (!flush_literal(&instrs, &capacity, &count, new_data,
+                       literal_start, new_file_size)) {
+      free(instrs);
+      return NULL;
+    }
+  }
+
+  Delta *delta = malloc(sizeof(Delta));
+  if (!delta) {
+    for (uint32_t k = 0; k < count; k++) {
+      if (instrs[k].type == DELTA_INSTR_LITERAL)
+        free(instrs[k].literal.data);
+    }
+    free(instrs);
+    return NULL;
+  }
+
+  delta->new_file_size = new_file_size;
+  delta->instruction_count = count;
+  delta->instructions = instrs;
+  delta->delta_size = 0;
+
+  for (uint32_t k = 0; k < count; k++) {
+    delta->delta_size += 1;
+    if (instrs[k].type == DELTA_INSTR_BLOCK_MATCH) {
+      delta->delta_size += sizeof(uint32_t) * 3;
+    } else {
+      delta->delta_size += sizeof(uint32_t) + instrs[k].literal.length;
+    }
+  }
+
+  return delta;
+}
+
+Data *delta_serialize(const Delta *delta) {
+  if (!delta) return NULL;
+
+  uint64_t total = sizeof(uint64_t) + sizeof(uint32_t) + delta->delta_size;
+  uint8_t *buf = malloc((size_t)total);
+  if (!buf) return NULL;
+
+  size_t pos = 0;
+  memcpy(buf + pos, &delta->new_file_size, sizeof(uint64_t));
+  pos += sizeof(uint64_t);
+  memcpy(buf + pos, &delta->instruction_count, sizeof(uint32_t));
+  pos += sizeof(uint32_t);
+
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    uint8_t type = (uint8_t)delta->instructions[i].type;
+    memcpy(buf + pos, &type, sizeof(uint8_t));
+    pos += sizeof(uint8_t);
+
+    if (delta->instructions[i].type == DELTA_INSTR_BLOCK_MATCH) {
+      memcpy(buf + pos, &delta->instructions[i].match.block_index, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+      memcpy(buf + pos, &delta->instructions[i].match.block_offset, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+      memcpy(buf + pos, &delta->instructions[i].match.length, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+    } else {
+      memcpy(buf + pos, &delta->instructions[i].literal.length, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+      memcpy(buf + pos, delta->instructions[i].literal.data,
+             delta->instructions[i].literal.length);
+      pos += delta->instructions[i].literal.length;
+    }
+  }
+
+  return data_create(buf, (size_t)total);
+}
+
+Delta *delta_deserialize(const Data *data) {
+  if (!data || data->size < sizeof(uint64_t) + sizeof(uint32_t))
+    return NULL;
+
+  const uint8_t *buf = (const uint8_t *)data->data;
+  size_t pos = 0;
+
+  Delta *delta = malloc(sizeof(Delta));
+  if (!delta) return NULL;
+
+  memcpy(&delta->new_file_size, buf + pos, sizeof(uint64_t));
+  pos += sizeof(uint64_t);
+  memcpy(&delta->instruction_count, buf + pos, sizeof(uint32_t));
+  pos += sizeof(uint32_t);
+
+  delta->instructions = malloc(delta->instruction_count * sizeof(DeltaInstruction));
+  if (!delta->instructions) {
+    free(delta);
+    return NULL;
+  }
+
+  delta->delta_size = 0;
+
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (pos >= data->size) {
+      for (uint32_t k = 0; k < i; k++) {
+        if (delta->instructions[k].type == DELTA_INSTR_LITERAL)
+          free(delta->instructions[k].literal.data);
+      }
+      free(delta->instructions);
+      free(delta);
+      return NULL;
+    }
+
+    uint8_t type;
+    memcpy(&type, buf + pos, sizeof(uint8_t));
+    pos += sizeof(uint8_t);
+
+    delta->delta_size += 1;
+
+    if (type == DELTA_OP_BLOCK_MATCH) {
+      if (pos + sizeof(uint32_t) * 3 > data->size) {
+        free(delta->instructions);
+        free(delta);
+        return NULL;
+      }
+      delta->instructions[i].type = DELTA_INSTR_BLOCK_MATCH;
+      memcpy(&delta->instructions[i].match.block_index, buf + pos, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+      memcpy(&delta->instructions[i].match.block_offset, buf + pos, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+      memcpy(&delta->instructions[i].match.length, buf + pos, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+      delta->delta_size += sizeof(uint32_t) * 3;
+    } else if (type == DELTA_OP_LITERAL) {
+      if (pos + sizeof(uint32_t) > data->size) {
+        free(delta->instructions);
+        free(delta);
+        return NULL;
+      }
+      delta->instructions[i].type = DELTA_INSTR_LITERAL;
+      memcpy(&delta->instructions[i].literal.length, buf + pos, sizeof(uint32_t));
+      pos += sizeof(uint32_t);
+
+      uint32_t lit_len = delta->instructions[i].literal.length;
+      if (pos + lit_len > data->size) {
+        free(delta->instructions);
+        free(delta);
+        return NULL;
+      }
+      delta->instructions[i].literal.data = malloc(lit_len);
+      if (!delta->instructions[i].literal.data) {
+        free(delta->instructions);
+        free(delta);
+        return NULL;
+      }
+      memcpy(delta->instructions[i].literal.data, buf + pos, lit_len);
+      pos += lit_len;
+      delta->delta_size += sizeof(uint32_t) + lit_len;
+    } else {
+      for (uint32_t k = 0; k < i; k++) {
+        if (delta->instructions[k].type == DELTA_INSTR_LITERAL)
+          free(delta->instructions[k].literal.data);
+      }
+      free(delta->instructions);
+      free(delta);
+      return NULL;
+    }
+  }
+
+  return delta;
+}
+
+void *delta_apply(const void *old_data, uint64_t old_size, const Delta *delta,
+                  uint32_t block_size) {
+  if (!old_data || !delta) return NULL;
+
+  void *output = malloc((size_t)delta->new_file_size);
+  if (!output) return NULL;
+
+  uint8_t *out = (uint8_t *)output;
+  uint8_t *old = (uint8_t *)old_data;
+  uint64_t out_pos = 0;
+
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_BLOCK_MATCH) {
+      uint64_t src_offset = (uint64_t)delta->instructions[i].match.block_index *
+                             block_size;
+      src_offset += delta->instructions[i].match.block_offset;
+      uint32_t len = delta->instructions[i].match.length;
+
+      if (src_offset + len > old_size) {
+        free(output);
+        return NULL;
+      }
+      memcpy(out + out_pos, old + src_offset, len);
+      out_pos += len;
+    } else {
+      uint32_t len = delta->instructions[i].literal.length;
+      memcpy(out + out_pos, delta->instructions[i].literal.data, len);
+      out_pos += len;
+    }
+  }
+
+  if (out_pos != delta->new_file_size) {
+    free(output);
+    return NULL;
+  }
+
+  return output;
+}
+
+void delta_destroy(Delta *delta) {
+  if (!delta) return;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_LITERAL)
+      free(delta->instructions[i].literal.data);
+  }
+  free(delta->instructions);
+  free(delta);
+}
+
+bool delta_should_attempt(uint64_t old_size, uint64_t new_size, uint64_t max_file_size) {
+  if (old_size < DELTA_MIN_FILE_SIZE || new_size < DELTA_MIN_FILE_SIZE)
+    return false;
+  if (old_size > max_file_size || new_size > max_file_size)
+    return false;
+  double large = (old_size > new_size) ? (double)old_size : (double)new_size;
+  double small = (old_size > new_size) ? (double)new_size : (double)old_size;
+  if (small == 0 || large / small > DELTA_MAX_SIZE_RATIO)
+    return false;
+  return true;
+}
+
+bool delta_is_worthwhile(const Delta *delta, uint64_t new_file_size) {
+  if (!delta || delta->instruction_count == 0) return false;
+
+  bool has_match = false;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_BLOCK_MATCH) {
+      has_match = true;
+      break;
+    }
+  }
+  if (!has_match) return false;
+
+  double ratio = (double)delta->delta_size / (double)new_file_size;
+  return ratio < DELTA_FALLBACK_RATIO;
+}

src/shared/delta.h

@@ -0,0 +1,81 @@
+#ifndef DELTA_H
+#define DELTA_H
+
+#include "data.h"
+#include <stdbool.h>
+#include <stdint.h>
+#include <stddef.h>
+
+#define DELTA_BLOCK_SIZE_DEFAULT  8192U
+#define DELTA_BLOCK_SIZE_MIN      1024U
+#define DELTA_BLOCK_SIZE_MAX      65536U
+#define DELTA_MIN_FILE_SIZE       16384ULL
+#define DELTA_MAX_FILE_SIZE       (256ULL * 1024 * 1024)
+#define DELTA_MAX_SIZE_RATIO      10.0
+#define DELTA_FALLBACK_RATIO      0.7
+#define DELTA_ADLER32_MODULUS     65521U
+
+#define DELTA_OP_BLOCK_MATCH  0x01
+#define DELTA_OP_LITERAL      0x02
+
+typedef struct {
+  uint32_t adler32;
+  uint32_t xxhash;
+} DeltaBlockSig;
+
+typedef struct {
+  uint64_t file_size;
+  uint32_t block_size;
+  uint32_t block_count;
+  DeltaBlockSig *blocks;
+} DeltaSignature;
+
+typedef enum {
+  DELTA_INSTR_BLOCK_MATCH = 0x01,
+  DELTA_INSTR_LITERAL     = 0x02
+} DeltaInstrType;
+
+typedef struct {
+  DeltaInstrType type;
+  union {
+    struct {
+      uint32_t block_index;
+      uint32_t block_offset;
+      uint32_t length;
+    } match;
+    struct {
+      uint8_t *data;
+      uint32_t length;
+    } literal;
+  };
+} DeltaInstruction;
+
+typedef struct {
+  uint64_t new_file_size;
+  uint32_t instruction_count;
+  DeltaInstruction *instructions;
+  uint64_t delta_size;
+} Delta;
+
+DeltaSignature *delta_signature_create(const void *old_file_data,
+                                        uint64_t old_file_size,
+                                        uint32_t block_size);
+Data *delta_signature_serialize(const DeltaSignature *sig);
+DeltaSignature *delta_signature_deserialize(const Data *data);
+void delta_signature_destroy(DeltaSignature *sig);
+
+Delta *delta_compute(const void *new_file_data, uint64_t new_file_size,
+                      const DeltaSignature *sig, uint32_t block_size);
+Data *delta_serialize(const Delta *delta);
+Delta *delta_deserialize(const Data *data);
+void *delta_apply(const void *old_data, uint64_t old_size, const Delta *delta,
+                  uint32_t block_size);
+void delta_destroy(Delta *delta);
+
+bool delta_should_attempt(uint64_t old_size, uint64_t new_size, uint64_t max_file_size);
+bool delta_is_worthwhile(const Delta *delta, uint64_t new_file_size);
+
+uint32_t delta_adler32(const void *data, uint32_t len);
+uint32_t delta_xxhash32(const void *data, uint32_t len);
+
+#endif

src/shared/file.c

@@ -10,6 +10,7 @@
 #include <unistd.h>
 
 #include "compression.h"
+#include "delta.h"
 #include "log.h"
 #include "config.h"
 #include "data.h"
@@ -132,7 +133,152 @@ bool file_save_to_disk(const char *root_directory, File *file) {
   return ok;
 }
 
-File *receive_incremental_check(int fd, Config *config, bool *skipped) {  *skipped = false;
+static void *old_data_from_path(const char *full_path, unsigned long long old_size) {
+  void *data = malloc((size_t)old_size);
+  if (!data) return NULL;
+  FILE *fp = fopen(full_path, "rb");
+  if (!fp) { free(data); return NULL; }
+  size_t nread = fread(data, 1, (size_t)old_size, fp);
+  fclose(fp);
+  if (nread != (size_t)old_size) { free(data); return NULL; }
+  return data;
+}
+
+static File *receive_delta_file(int fd, Config *config, const char *check_path,
+                                 void *old_data, unsigned long long old_size) {
+  if (!old_data) return NULL;
+
+  DeltaSignature *sig = delta_signature_create(old_data, old_size,
+                                                config->delta_block_size);
+  if (!sig) { free(old_data); return NULL; }
+
+  Data *sig_data = delta_signature_serialize(sig);
+  if (!sig_data) { delta_signature_destroy(sig); free(old_data); return NULL; }
+
+  bool sig_sent = send_status(fd, STATUS_DELTA_SIGNATURE) &&
+                  send_data(fd, sig_data);
+  data_destroy(sig_data);
+
+  if (!sig_sent) { delta_signature_destroy(sig); free(old_data); return NULL; }
+
+  Status resp;
+  if (!receive_status(fd, &resp)) {
+    delta_signature_destroy(sig);
+    free(old_data);
+    return NULL;
+  }
+
+  if (resp == STATUS_DELTA_DATA) {
+    Data *delta_data = receive_data(fd);
+    if (!delta_data) {
+      delta_signature_destroy(sig);
+      free(old_data);
+      send_status(fd, STATUS_ERROR);
+      return NULL;
+    }
+
+    Data *raw_delta = delta_data;
+    if (config->use_compression) {
+      raw_delta = data_decompress(delta_data);
+      data_destroy(delta_data);
+      if (!raw_delta) {
+        free(old_data);
+        delta_signature_destroy(sig);
+        send_status(fd, STATUS_ERROR);
+        return NULL;
+      }
+    }
+
+    Delta *delta = delta_deserialize(raw_delta);
+    data_destroy(raw_delta);
+    if (!delta) {
+      free(old_data);
+      delta_signature_destroy(sig);
+      send_status(fd, STATUS_ERROR);
+      return NULL;
+    }
+
+    void *new_data = delta_apply(old_data, old_size, delta,
+                                  config->delta_block_size);
+    uint64_t new_size = delta->new_file_size;
+    delta_destroy(delta);
+
+    if (!new_data) {
+      free(old_data);
+      delta_signature_destroy(sig);
+      send_status(fd, STATUS_ERROR);
+      return NULL;
+    }
+
+    File *file = file_create(check_path);
+    if (!file) {
+      free(new_data);
+      free(old_data);
+      delta_signature_destroy(sig);
+      send_status(fd, STATUS_ERROR);
+      return NULL;
+    }
+
+    if (config->use_metadata) {
+      int meta_ok = 1;
+      file->metadata = metadata_receive(fd, &meta_ok);
+      if (!meta_ok) {
+        file_destroy(file);
+        free(new_data);
+        free(old_data);
+        delta_signature_destroy(sig);
+        send_status(fd, STATUS_ERROR);
+        return NULL;
+      }
+    }
+
+    data_destroy(file->data);
+    file->data = data_create(new_data, (size_t)new_size);
+
+    free(old_data);
+    delta_signature_destroy(sig);
+    return file;
+  }
+
+  if (resp == STATUS_NEXT) {
+    delta_signature_destroy(sig);
+    free(old_data);
+
+    File *file = file_create(check_path);
+    if (!file) { send_status(fd, STATUS_ERROR); return NULL; }
+
+    if (config->use_metadata) {
+      int meta_ok = 1;
+      file->metadata = metadata_receive(fd, &meta_ok);
+      if (!meta_ok) { file_destroy(file); send_status(fd, STATUS_ERROR); return NULL; }
+    }
+
+    Data *file_data = receive_data(fd);
+    if (file_data == NULL) {
+      file_destroy(file);
+      send_status(fd, STATUS_ERROR);
+      return NULL;
+    }
+
+    if (config->use_compression) {
+      Data *uncompressed = data_decompress(file_data);
+      data_destroy(file_data);
+      if (uncompressed == NULL) { file_destroy(file); send_status(fd, STATUS_ERROR); return NULL; }
+      file_data = uncompressed;
+    }
+
+    data_destroy(file->data);
+    file->data = file_data;
+    return file;
+  }
+
+  delta_signature_destroy(sig);
+  free(old_data);
+  return NULL;
+}
+
+File *receive_incremental_check(int fd, Config *config, bool *skipped) {
+  *skipped = false;
   char *check_path = receive_str(fd);
   if (check_path == NULL) { send_status(fd, STATUS_ERROR); return NULL; }
 
@@ -147,25 +293,47 @@ File *receive_incremental_check(int fd, Config *config, bool *skipped) {  *skipp
 
   char *full_path = path_cat(config->receive_root_directory, check_path);
   struct stat st;
-  bool match = false;
-  if (full_path && stat(full_path, &st) == 0 &&
-      (unsigned long long)st.st_size == check_size &&
-      (long long)st.st_mtime == check_mtime) {
-    match = true;
-  }
-  free(full_path);
+  bool has_old_file = (full_path && stat(full_path, &st) == 0);
+  unsigned long long old_size = has_old_file ? (unsigned long long)st.st_size : 0;
+
+  bool match = has_old_file &&
+               (unsigned long long)st.st_size == check_size &&
+               (long long)st.st_mtime == check_mtime;
 
   if (match) {
-    if (!send_status(fd, STATUS_OK)) { free(check_path); return NULL; }
+    if (!send_status(fd, STATUS_OK)) { free(full_path); free(check_path); return NULL; }
+    free(full_path);
     free(check_path);
     *skipped = true;
     return NULL;
   }
 
-  if (!send_status(fd, STATUS_NEXT)) { free(check_path); return NULL; }
+  bool try_delta = config->use_delta && has_old_file &&
+                   delta_should_attempt(old_size, check_size, config->delta_max_file_size);
+
+  if (try_delta) {
+    void *old_data = old_data_from_path(full_path, old_size);
+    File *delta_file = receive_delta_file(fd, config, check_path,
+                                           old_data, old_size);
+    if (delta_file) {
+      free(full_path);
+      free(check_path);
+      return delta_file;
+    }
+    try_delta = false;
+  }
+
+  if (!try_delta) {
+    if (!send_status(fd, STATUS_NEXT)) {
+      free(full_path);
+      free(check_path);
+      return NULL;
+    }
+  }
 
   File *file = file_create(check_path);
   free(check_path);
+  free(full_path);
   if (file == NULL) { send_status(fd, STATUS_ERROR); return NULL; }
 
   if (config->use_metadata) {
@@ -218,7 +386,8 @@ bool to_disk(const char *path, const void *data, unsigned long long data_size) {
   return true;
 }
 
-bool file_send_sendfile(File *file, int file_descriptor, bool use_metadata, bool send_path) {
+bool file_send_sendfile(File *file, int file_descriptor, bool use_metadata, int compression_level, bool send_path) {
+  (void)compression_level;
   if (send_path && !send_str(file_descriptor, file->path)) return false;
   if (use_metadata && !metadata_send(file_descriptor, file->metadata)) return false;
 

src/shared/file.h

@@ -25,7 +25,7 @@ void file_destroy(void *item);
 bool file_load_data(File *file);
 File *file_receive(Config *config, int file_descriptor);
 bool file_send_single_calls(File *file, int file_descriptor, bool use_metadata, int compression_level, bool send_path);
-bool file_send_sendfile(File *file, int file_descriptor, bool use_metadata, bool send_path);
+bool file_send_sendfile(File *file, int file_descriptor, bool use_metadata, int compression_level, bool send_path);
 size_t file_content_to_buffer(File *file);
 FileMetadata *file_metadata_create(struct stat *stats);
 void file_metadata_destroy(void *metadata);

src/shared/protocol.c

@@ -127,6 +127,10 @@ static const char *status_to_string(Status status) {
     return "CHUNK";
   case STATUS_CHECK:
     return "CHECK";
+  case STATUS_DELTA_SIGNATURE:
+    return "DELTA_SIGNATURE";
+  case STATUS_DELTA_DATA:
+    return "DELTA_DATA";
   default:
     return "UNKNOWN";
   }

src/shared/protocol.h

@@ -8,7 +8,7 @@
 typedef struct ssl_st SSL;
 
 typedef int Status;
-enum NET_STATUS { STATUS_OK, STATUS_ERROR, STATUS_FINISHED, STATUS_NEXT, STATUS_CHUNK, STATUS_MANIFEST, STATUS_CHECK };
+enum NET_STATUS { STATUS_OK, STATUS_ERROR, STATUS_FINISHED, STATUS_NEXT, STATUS_CHUNK, STATUS_MANIFEST, STATUS_CHECK, STATUS_DELTA_SIGNATURE, STATUS_DELTA_DATA };
 
 void io_set_fds(int read_fd, int write_fd);
 void io_set_bwlimit(unsigned long long bytes_per_sec);

test.py

@@ -1,740 +0,0 @@
-import argparse
-import filecmp
-import os
-import random
-import re
-import shutil
-import subprocess
-import sys
-import tempfile
-import time
-import socket
-
-TEST_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "test_data")
-DEFAULT_SOURCE_DIR = os.path.join(TEST_DIR, "source")
-DEFAULT_DEST_DIR = os.path.join(TEST_DIR, "dest")
-
-SERVER_CMD = ["./build/server"]
-BASE_CLIENT_CMD = ["./build/client"]
-
-DISK_DEVICE = "/dev/nvme0n1p5"
-READ_BPS_MAX = "15M"
-WRITE_BPS_MAX = "10M"
-NETWORK_INTERFACE = "lo"
-
-NETWORK_PROFILES = {
-    "Unlimited": {},
-    "LAN": {
-        "rate": "1000mbit",
-        "delay": "20ms",
-        "jitter": "1ms",
-        "loss": "0.1%",
-    },
-    "WAN": {
-        "rate": "100mbit",
-        "delay": "50ms",
-        "jitter": "10ms",
-        "loss": "1%",
-    },
-}
-
-CLIENT_CMD_PREFIX = [
-    "sudo",
-    "systemd-run",
-    "--scope",
-    "-p",
-    f"IOReadBandwidthMax={DISK_DEVICE} {READ_BPS_MAX}",
-    "-p",
-    f"IOWriteBandwidthMax={DISK_DEVICE} {WRITE_BPS_MAX}",
-]
-
-BASE_CLIENT_FLAGS = ["--save-to-disk"]
-
-TEST_CASES_FULL = [
-    {"name": "Standard", "flags": []},
-    {"name": "Posix Args (no flags)", "flags": [], "posix": True},
-    {"name": "Standard (no metadata)", "flags": [], "use_metadata": False},
-    {"name": "Multithreading (-m)", "flags": ["-m"]},
-    {"name": "Compression (-c)", "flags": ["-c"]},
-    {"name": "Chunk Serialization (-s)", "flags": ["-s"]},
-    {"name": "Compression + Chunk Serialization (-c -s)", "flags": ["-c", "-s"]},
-    {"name": "Multithreading + Compression (-m -c)", "flags": ["-m", "-c"]},
-    {"name": "Multithreading + Chunk Serialization (-m -s)", "flags": ["-m", "-s"]},
-    {
-        "name": "Multithreading + Compression + Chunk Serialization (-m -c -s)",
-        "flags": ["-m", "-c", "-s"],
-    },
-    {"name": "Sendfile (-f)", "flags": ["-f"]},
-    {"name": "Sendfile + Multithreading (-f -m)", "flags": ["-f", "-m"]},
-]
-
-TEST_CASES_LIGHT = [
-    {"name": "Standard", "flags": []},
-    {"name": "Compression (-c)", "flags": ["-c"]},
-    {"name": "Chunk Serialization (-s)", "flags": ["-s"]},
-    {"name": "Multithreading + Compression + Chunk Serialization (-m -c -s)", "flags": ["-m", "-c", "-s"]},
-]
-
-SSH_CASES_FULL = [
-    {"name": "SSH (localhost)", "flags": []},
-    {"name": "SSH Multithreading (-m)", "flags": ["-m"]},
-    {"name": "SSH Compression (-c)", "flags": ["-c"]},
-    {"name": "SSH Chunk Serialization (-s)", "flags": ["-s"]},
-    {"name": "SSH Compression + Chunk Serialization (-c -s)", "flags": ["-c", "-s"]},
-    {"name": "SSH Multithreading + Compression (-m -c)", "flags": ["-m", "-c"]},
-    {"name": "SSH Multithreading + Chunk Serialization (-m -s)", "flags": ["-m", "-s"]},
-    {"name": "SSH Multithreading + Compression + Chunk Serialization (-m -c -s)", "flags": ["-m", "-c", "-s"]},
-]
-
-SSH_CASES_LIGHT = [
-    {"name": "SSH (localhost)", "flags": []},
-]
-
-RSYNC_CASES_FULL = [
-    {"name": "rsync (archive)", "args": ["-aH"]},
-    {"name": "rsync (archive + compress)", "args": ["-aHz"]},
-]
-
-RSYNC_CASES_LIGHT = []
-
-
-def netem_apply(profile):
-    params = NETWORK_PROFILES[profile]
-    if not params:
-        netem_reset()
-        return
-    netem_reset()
-    cmd = ["sudo", "tc", "qdisc", "add", "dev", NETWORK_INTERFACE, "root", "netem"]
-    cmd += ["rate", params["rate"]]
-    cmd += ["delay", params["delay"], params["jitter"]]
-    cmd += ["loss", params["loss"]]
-    subprocess.run(cmd, check=True, capture_output=True)
-
-
-def netem_reset():
-    subprocess.run(
-        f"sudo tc qdisc del dev {NETWORK_INTERFACE} root".split(),
-        capture_output=True,
-    )
-
-
-def wait_proc(proc, timeout=5):
-    try:
-        proc.wait(timeout=timeout)
-    except subprocess.TimeoutExpired:
-        proc.kill()
-        proc.wait()
-
-
-def find_free_port():
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        s.bind(('', 0))
-        return s.getsockname()[1]
-
-
-def generate_test_files(source_dir, full=False):
-    if os.path.exists(source_dir):
-        shutil.rmtree(source_dir)
-    os.makedirs(source_dir)
-
-    target_total = 25 * 1024 * 1024 if full else 0
-    written = 0
-
-    files = {
-        "small.txt": b"hello world\n",
-        "medium.txt": b"the quick brown fox jumps over the lazy dog\n" * 5000,
-        "binary.bin": bytes(range(256)) * 1000,
-        "nested/subdir/deep.txt": b"deeply nested file\n",
-        "nested/another.txt": b"another nested file\n" * 50,
-    }
-    for rel_path, content in files.items():
-        full_path = os.path.join(source_dir, rel_path)
-        os.makedirs(os.path.dirname(full_path), exist_ok=True)
-        with open(full_path, "wb") as f:
-            f.write(content)
-        written += len(content)
-
-    if full:
-        os.makedirs(os.path.join(source_dir, "bulk"), exist_ok=True)
-        i = 0
-        while written < target_total:
-            chunk_size = min(5 * 1024 * 1024, target_total - written)
-            with open(os.path.join(source_dir, f"bulk/file_{i}.dat"), "wb") as f:
-                f.write(random.randbytes(chunk_size))
-            written += chunk_size
-            i += 1
-
-    total_mb = written / (1024 * 1024)
-    small_bytes = sum(len(c) for c in files.values())
-    print(f"  Generated {total_mb:.1f} MB of test data in {source_dir} "
-          f"({(written - small_bytes)/(1024*1024):.1f} MB random, "
-          f"{small_bytes} B structured)")
-    return written
-
-
-def verify_transfer(source_dir, received_dir):
-    source_dir = os.path.abspath(source_dir)
-    received_dir = os.path.abspath(received_dir)
-    if not os.path.exists(received_dir):
-        return [], ["no received files found"]
-    mismatches, missing = [], []
-    for root, dirs, files in os.walk(source_dir):
-        for f in files:
-            src_path = os.path.join(root, f)
-            rel = os.path.relpath(src_path, source_dir)
-            dst_path = os.path.join(received_dir, rel)
-            if not os.path.exists(dst_path):
-                missing.append(rel)
-            elif not filecmp.cmp(src_path, dst_path, shallow=False):
-                mismatches.append(rel)
-    return mismatches, missing
-
-
-def start_rsync_daemon(source_dir):
-    port = find_free_port()
-    conf = os.path.join(tempfile.gettempdir(), f"rsyncd-{port}.conf")
-    with open(conf, "w") as f:
-        f.write(f"port = {port}\nread only = yes\n\n[source]\n    path = {source_dir}\n")
-    daemon = subprocess.Popen(
-        ["rsync", "--daemon", "--no-detach", f"--config={conf}"],
-        stdout=subprocess.DEVNULL, stderr=None,
-    )
-    for _ in range(50):
-        time.sleep(0.1)
-        if daemon.poll() is not None:
-            raise RuntimeError(f"rsync daemon exited (rc={daemon.returncode})")
-        try:
-            with socket.create_connection(("127.0.0.1", port), timeout=0.3):
-                break
-        except (ConnectionRefusedError, OSError):
-            continue
-    else:
-        raise RuntimeError("rsync daemon did not start")
-    return port, conf, daemon
-
-
-def run_single_test(cmd, name, source_dir, dest_dir, *, source_prefix=None, no_server=False, expected_missing=None):
-    if os.path.exists(dest_dir):
-        shutil.rmtree(dest_dir)
-    if no_server:
-        server = None
-    else:
-        server = subprocess.Popen(SERVER_CMD, stdout=subprocess.DEVNULL, stderr=None)
-        time.sleep(0.5)
-    try:
-        start = time.monotonic()
-        result = subprocess.run(cmd, text=True, capture_output=True)
-        duration = time.monotonic() - start
-    finally:
-        if server:
-            wait_proc(server)
-
-    mismatches, missing = [], []
-    if result.returncode == 0:
-        received = os.path.join(dest_dir, source_prefix if source_prefix is not None
-                                else os.path.abspath(source_dir).lstrip(os.sep))
-        mismatches, missing = verify_transfer(source_dir, received)
-        if expected_missing:
-            missing = [m for m in missing if m not in expected_missing]
-
-    first_line = lambda s: (s or "").strip().split("\n")[0]
-    entry = {
-        "name": name,
-        "time": f"{duration:.4f}s" if result.returncode == 0 else "N/A",
-    }
-    if result.returncode == 0 and not mismatches and not missing:
-        entry["status"] = "Success"
-        entry["error"] = ""
-    else:
-        entry["status"] = "Failed"
-        errors = []
-        if result.returncode != 0:
-            errors.append(f"Exit code {result.returncode}: {first_line(result.stderr) or first_line(result.stdout) or 'No output'[:80]}")
-        if missing:
-            errors.append(f"Missing ({len(missing)}): {', '.join(missing[:5])}")
-        if mismatches:
-            errors.append(f"Mismatch ({len(mismatches)}): {', '.join(mismatches[:3])}")
-        entry["error"] = " | ".join(errors)
-    return entry
-
-
-def print_profile_header(profile_name):
-    params = NETWORK_PROFILES[profile_name]
-    print(f"\n{'=' * 60}\nProfile: {profile_name}\n{'=' * 60}")
-    if params:
-        print(f"  Network: rate={params['rate']}, delay={params['delay']} ±{params['jitter']}, loss={params['loss']}")
-        print(f"  Disk I/O: Reads <= {READ_BPS_MAX}, Writes <= {WRITE_BPS_MAX}")
-    else:
-        print("  No limits applied")
-
-
-def run_profile(profile_name, source_dir, dest_dir, *, full=False, test_cases=None, ssh_cases=None, rsync_cases=None):
-    print_profile_header(profile_name)
-    is_limited = profile_name != "Unlimited"
-    client_prefix = CLIENT_CMD_PREFIX if is_limited else []
-
-    if test_cases is None:
-        test_cases = TEST_CASES_FULL if full else TEST_CASES_LIGHT
-    if ssh_cases is None:
-        ssh_cases = SSH_CASES_FULL if full else SSH_CASES_LIGHT
-    if rsync_cases is None:
-        rsync_cases = RSYNC_CASES_FULL if full else RSYNC_CASES_LIGHT
-
-    try:
-        if is_limited and full:
-            netem_apply(profile_name)
-
-        results = []
-        for case in test_cases:
-            flags = BASE_CLIENT_FLAGS + (["-M"] if case.get("use_metadata", True) else []) + case["flags"]
-            if case.get("posix"):
-                cmd = client_prefix + BASE_CLIENT_CMD + [source_dir, dest_dir] + flags
-            else:
-                cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + flags
-            print(f"\n  --- {case['name']} ---\n    Running: {' '.join(cmd)}")
-            try:
-                r = run_single_test(cmd, case["name"], source_dir, dest_dir)
-                r["suite"] = profile_name
-                results.append(r)
-            except Exception as e:
-                results.append({"name": case["name"], "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-        if SSH_AVAILABLE:
-            for case in ssh_cases:
-                flags = BASE_CLIENT_FLAGS + (["-M"] if case.get("use_metadata", True) else []) + case["flags"]
-                ssh_dest = f"localhost:{dest_dir}_ssh"
-                cmd = BASE_CLIENT_CMD + [source_dir, ssh_dest] + flags
-                print(f"\n  --- {case['name']} ---\n    Running: {' '.join(cmd)}")
-                try:
-                    r = run_single_test(cmd, case["name"], source_dir, f"{dest_dir}_ssh", no_server=True)
-                    r["suite"] = profile_name
-                    results.append(r)
-                except Exception as e:
-                    results.append({"name": case["name"], "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-    
-        if rsync_cases:
-            port, conf, daemon = start_rsync_daemon(source_dir)
-            try:
-                for case in rsync_cases:
-                    cmd = client_prefix + ["rsync"] + case["args"] + [f"rsync://localhost:{port}/source/", f"{dest_dir}/"]
-                    print(f"\n  --- {case['name']} ---\n    Running: {' '.join(cmd)}")
-                    try:
-                        r = run_single_test(cmd, case["name"], source_dir, dest_dir, source_prefix="")
-                        r["suite"] = profile_name
-                    except subprocess.TimeoutExpired:
-                        r = {"name": case["name"], "suite": profile_name, "status": "Timeout", "time": "N/A", "error": "Exceeded 120s"}
-                    except Exception as e:
-                        r = {"name": case["name"], "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)}
-                    else:
-                        if r["status"] != "Success" and client_prefix:
-                            tmp = tempfile.mkdtemp()
-                            try:
-                                plain = subprocess.run(["rsync", "-aH", f"rsync://localhost:{port}/source/", f"{tmp}/"], capture_output=True, text=True, timeout=30)
-                                if plain.returncode != 0:
-                                    errs = [l for l in (plain.stderr or "").split("\n") if l.strip()]
-                                    if errs:
-                                        r["error"] += f" | raw: {errs[-1][:150]}"
-                            finally:
-                                shutil.rmtree(tmp, ignore_errors=True)
-                    results.append(r)
-            finally:
-                wait_proc(daemon)
-                try:
-                    os.unlink(conf)
-                except Exception:
-                    pass
-
-        if full:
-            # Feature-specific tests for rsync-compatible flags
-            print("\n  " + "─" * 56 + "\n  Feature Tests\n  " + "─" * 56)
-
-            # Dry run (-n) — no server needed
-            print("\n  --- Dry run (-n) ---")
-            flags = BASE_CLIENT_FLAGS + ["-n"]
-            cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + flags
-            print(f"    Running: {' '.join(cmd)}")
-            try:
-                start = time.monotonic()
-                result = subprocess.run(cmd, text=True, capture_output=True)
-                duration = time.monotonic() - start
-                r = {"name": "Dry run (-n)", "suite": profile_name}
-                if result.returncode == 0 and "Dry run:" in result.stdout:
-                    r["status"] = "Success"
-                    r["time"] = f"{duration:.4f}s"
-                    r["error"] = ""
-                else:
-                    r["status"] = "Failed"
-                    r["time"] = "N/A"
-                    r["error"] = f"Exit {result.returncode}: {(result.stderr or result.stdout)[:100]}"
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Dry run (-n)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Archive mode (-a)
-            feature_flags = BASE_CLIENT_FLAGS + ["-a"]
-            cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + feature_flags
-            print(f"\n  --- Archive mode (-a) ---\n    Running: {' '.join(cmd)}")
-            try:
-                r = run_single_test(cmd, "Archive mode (-a)", source_dir, dest_dir)
-                r["suite"] = profile_name
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Archive mode (-a)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Exclude (--exclude small.txt)
-            feature_flags = BASE_CLIENT_FLAGS + ["--exclude", "small.txt"]
-            cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + feature_flags
-            print(f"\n  --- Exclude (--exclude small.txt) ---\n    Running: {' '.join(cmd)}")
-            try:
-                r = run_single_test(cmd, "Exclude (--exclude small.txt)", source_dir, dest_dir,
-                                    expected_missing=["small.txt"])
-                r["suite"] = profile_name
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Exclude (--exclude small.txt)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Progress (--progress)
-            feature_flags = BASE_CLIENT_FLAGS + ["--progress"]
-            cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + feature_flags
-            print(f"\n  --- Progress (--progress) ---\n    Running: {' '.join(cmd)}")
-            try:
-                r = run_single_test(cmd, "Progress (--progress)", source_dir, dest_dir)
-                r["suite"] = profile_name
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Progress (--progress)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Bandwidth limit (--bwlimit 10240 = 10 MB/s)
-            feature_flags = BASE_CLIENT_FLAGS + ["--bwlimit", "10240"]
-            cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + feature_flags
-            print(f"\n  --- Bandwidth limit (--bwlimit 10240 KB/s) ---\n    Running: {' '.join(cmd)}")
-            try:
-                r = run_single_test(cmd, "Bandwidth limit (--bwlimit 10240)", source_dir, dest_dir)
-                r["suite"] = profile_name
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Bandwidth limit (--bwlimit 10240)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Incremental sync (--incremental) — first sync, then second sync should skip all
-            print(f"\n  --- Incremental (--incremental) ---")
-            try:
-                flags = BASE_CLIENT_FLAGS + ["-M"]
-                srv = subprocess.Popen(SERVER_CMD, stdout=subprocess.DEVNULL, stderr=None)
-                time.sleep(0.5)
-                first_cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + flags
-                r1 = subprocess.run(first_cmd, text=True, capture_output=True)
-                wait_proc(srv)
-                if r1.returncode != 0:
-                    raise RuntimeError(f"First sync failed: {r1.stderr[:100]}")
-                srv2 = subprocess.Popen(SERVER_CMD, stdout=subprocess.DEVNULL, stderr=None)
-                time.sleep(0.5)
-                second_cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + flags + ["--incremental"]
-                start = time.monotonic()
-                r2 = subprocess.run(second_cmd, text=True, capture_output=True, timeout=30)
-                duration = time.monotonic() - start
-                wait_proc(srv2)
-                r = {"name": "Incremental (--incremental)", "suite": profile_name,
-                     "status": "Success" if r2.returncode == 0 else "Failed",
-                     "time": f"{duration:.4f}s" if r2.returncode == 0 else "N/A",
-                     "error": "" if r2.returncode == 0 else f"Exit {r2.returncode}: {(r2.stderr or r2.stdout)[:60]}"}
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Incremental (--incremental)", "suite": profile_name,
-                                "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Chunk size (--chunk-size 5242880)
-            feature_flags = BASE_CLIENT_FLAGS + ["--chunk-size", "5242880"]
-            cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + feature_flags
-            print(f"\n  --- Chunk size (--chunk-size 5242880) ---\n    Running: {' '.join(cmd)}")
-            try:
-                r = run_single_test(cmd, "Chunk size (--chunk-size 5242880)", source_dir, dest_dir)
-                r["suite"] = profile_name
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Chunk size (--chunk-size 5242880)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # Delete (--delete) — pre-populate dest, add extra files, then sync with --delete
-            # Note: server handles one client per launch, so we restart between syncs
-            print(f"\n  --- Delete (--delete) ---")
-            try:
-                flags = BASE_CLIENT_FLAGS + ["-M"]
-                # First sync (no delete) to populate dest
-                s1 = subprocess.Popen(SERVER_CMD, stdout=subprocess.DEVNULL, stderr=None)
-                time.sleep(0.5)
-                first_cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + flags
-                r1 = subprocess.run(first_cmd, text=True, capture_output=True)
-                wait_proc(s1)
-                if r1.returncode != 0:
-                    raise RuntimeError(f"First sync failed: {r1.stderr[:100]}")
-                # Add extra files to received dir
-                received = os.path.join(dest_dir, os.path.abspath(source_dir).lstrip(os.sep))
-                extra_path = os.path.join(received, "extra_file.txt")
-                with open(extra_path, "w") as f:
-                    f.write("should be deleted")
-                extra_dir = os.path.join(received, "extra_dir")
-                os.makedirs(extra_dir, exist_ok=True)
-                with open(os.path.join(extra_dir, "nested.txt"), "w") as f:
-                    f.write("nested extra")
-                # Second sync with --delete (fresh server)
-                s2 = subprocess.Popen(SERVER_CMD, stdout=subprocess.DEVNULL, stderr=None)
-                time.sleep(0.5)
-                second_cmd = client_prefix + BASE_CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir] + flags + ["--delete"]
-                start = time.monotonic()
-                r2 = subprocess.run(second_cmd, text=True, capture_output=True)
-                duration = time.monotonic() - start
-                wait_proc(s2)
-                r = {"name": "Delete (--delete)", "suite": profile_name}
-                if r2.returncode == 0 and not os.path.exists(extra_path) and not os.path.exists(extra_dir):
-                    mismatches, missing = verify_transfer(source_dir, received)
-                    if not mismatches and not missing:
-                        r["status"] = "Success"
-                        r["time"] = f"{duration:.4f}s"
-                        r["error"] = ""
-                    else:
-                        r["status"] = "Failed"
-                        r["time"] = "N/A"
-                        r["error"] = f"post-delete verify: mismatches={len(mismatches)}, missing={len(missing)}"
-                else:
-                    r["status"] = "Failed"
-                    r["time"] = "N/A"
-                    errs = []
-                    if r2.returncode != 0:
-                        errs.append(f"Exit {r2.returncode}: {(r2.stderr or r2.stdout)[:60]}")
-                    if os.path.exists(extra_path):
-                        errs.append("extra_file.txt remains")
-                    if os.path.exists(extra_dir):
-                        errs.append("extra_dir remains")
-                    r["error"] = " | ".join(errs)
-                results.append(r)
-            except Exception as e:
-                results.append({"name": "Delete (--delete)", "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-            # SSH feature tests
-            if SSH_AVAILABLE:
-                ssh_dest = f"localhost:{dest_dir}_ssh"
-                ssh_feature_cases = [
-                    {"name": "SSH Archive (-a)", "flags": ["-a"]},
-                    {"name": "SSH Exclude (--exclude small.txt)", "flags": ["--exclude", "small.txt"], "expected_missing": ["small.txt"]},
-                ]
-                for case in ssh_feature_cases:
-                    flags = BASE_CLIENT_FLAGS + case["flags"]
-                    cmd = BASE_CLIENT_CMD + [source_dir, ssh_dest] + flags
-                    print(f"\n  --- {case['name']} ---\n    Running: {' '.join(cmd)}")
-                    try:
-                        r = run_single_test(cmd, case["name"], source_dir, f"{dest_dir}_ssh",
-                                            no_server=True,
-                                            expected_missing=case.get("expected_missing"))
-                        r["suite"] = profile_name
-                        results.append(r)
-                    except Exception as e:
-                        results.append({"name": case["name"], "suite": profile_name, "status": "Error", "time": "N/A", "error": str(e)})
-
-    except (subprocess.CalledProcessError, RuntimeError) as e:
-        print(f"  Error: {e}")
-        results = []
-    finally:
-        if is_limited:
-            try:
-                netem_reset()
-            except Exception:
-                pass
-
-    return results
-
-
-def print_metrics(profile_name, results, total_bytes):
-    params = NETWORK_PROFILES.get(profile_name)
-    if not params or "rate" not in params:
-        return
-
-    client_times, rsync_times = [], {}
-    for r in results:
-        if r["status"] != "Success" or r["time"] == "N/A":
-            continue
-        t = float(r["time"].rstrip("s"))
-        if r["name"].startswith("rsync"):
-            rsync_times[r["name"]] = t
-        elif "Dry run" not in r["name"]:
-            client_times.append((t, r["name"]))
-    if not client_times or len(rsync_times) < 2:
-        return
-
-    m = re.match(r'(\d+)\s*(mbit|gbit|kbit|bit)', params["rate"])
-    rate_val = int(m.group(1)) * {'mbit': 1_000_000, 'gbit': 1_000_000_000, 'kbit': 1000, 'bit': 1}[m.group(2)] / 8 if m else None
-
-    best_time, best_name = min(client_times, key=lambda x: x[0])
-    theoretical_max = total_bytes / rate_val if rate_val else None
-
-    print(f"\n  {'─' * 90}\n  Profile: {profile_name}\n  {'─' * 90}")
-    print(f"  Total data size:               {total_bytes / (1024*1024):.1f} MB")
-    if rate_val:
-        print(f"  Network rate:                  {params['rate']} ({format_throughput(rate_val)})")
-    print(f"  Best client configuration:     {best_name}")
-    print(f"  Best client time:              {best_time:.4f}s")
-    if theoretical_max:
-        print(f"  Theoretical max (uncompressed): {theoretical_max:.4f}s")
-        print(f"  Speedup vs theoretical max:    {theoretical_max / best_time:.2f}x")
-    if (a := rsync_times.get("rsync (archive)")):
-        print(f"  Speedup vs rsync (archive):    {a / best_time:.2f}x")
-    if (c := rsync_times.get("rsync (archive + compress)")):
-        print(f"  Speedup vs rsync (compress):   {c / best_time:.2f}x")
-
-
-def format_throughput(bps):
-    for unit, threshold in [("GB/s", 1_000_000_000), ("MB/s", 1_000_000), ("KB/s", 1000)]:
-        if bps >= threshold:
-            return f"{bps/threshold:.1f} {unit}"
-    return f"{bps:.0f} B/s"
-
-
-SSH_AVAILABLE = False
-
-def check_ssh_localhost():
-    global SSH_AVAILABLE
-    build_dir = os.path.abspath("build")
-    server_path = os.path.join(build_dir, "server")
-
-    try:
-        r = subprocess.run(["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
-                            "localhost", "which", "fastsync-server"],
-                           capture_output=True, timeout=10)
-    except FileNotFoundError:
-        SSH_AVAILABLE = False
-        return
-    if r.returncode == 0:
-        SSH_AVAILABLE = True
-        return
-
-    SSH_AVAILABLE = False
-    # Try each PATH dir: create symlink, then verify with which
-    try:
-        r = subprocess.run(
-            ["ssh", "-o", "BatchMode=yes", "localhost",
-             'echo "$PATH"'],
-            capture_output=True, timeout=10, text=True)
-    except FileNotFoundError:
-        return
-    if r.returncode != 0:
-        return
-    for d in r.stdout.strip().split(":"):
-        d = d.strip()
-        if not d:
-            continue
-        if "wrappers" in d:
-            continue
-        test = subprocess.run(
-            ["ssh", "-o", "BatchMode=yes", "localhost",
-             f'test -w "{d}" && ln -sf {server_path} "{d}/fastsync-server" && which fastsync-server'],
-            capture_output=True, timeout=10)
-        if test.returncode == 0:
-            SSH_AVAILABLE = True
-            return
-
-
-def preflight_checks():
-    global SSH_AVAILABLE
-    errors = []
-    print("Pre-flight checks:")
-    print("  [1] --help flag...", end=" ")
-    r = subprocess.run(BASE_CLIENT_CMD + ["--help"], capture_output=True, text=True)
-    if r.returncode == 0 and "Usage:" in r.stdout and "SSH transport" in r.stdout:
-        print("OK")
-    else:
-        print("FAIL")
-        errors.append("--help failed")
-
-    print("  [2] Remote SSH dest detection...", end=" ")
-    r = subprocess.run(BASE_CLIENT_CMD + ["/x", "somehost:/y"], capture_output=True, text=True, timeout=5)
-    if r.returncode != 0 and ("ssh" in r.stderr or "Could not receive" in r.stderr or "could not launch" in r.stderr or "Error" in r.stderr):
-        print("OK (detected as SSH)")
-    else:
-        print("FAIL (not detected as SSH dest)")
-        errors.append("SSH detection failed")
-
-    print("  [3] Server --stdio flag...", end=" ")
-    try:
-        r = subprocess.run(["./build/server", "--stdio"], capture_output=True, text=True, timeout=3)
-        if r.returncode != 0 and ("receiving" in r.stderr or "receiving" in r.stdout or "Receiving" in r.stderr):
-            print("OK (started in stdio mode)")
-        else:
-            print("WARN (stdio exited: rc=%d)" % r.returncode)
-    except subprocess.TimeoutExpired:
-        print("OK (waiting for stdin)")
-
-    print("  [4] Posix arg syntax (no server, expect failure)...", end=" ")
-    r = subprocess.run(BASE_CLIENT_CMD + ["/tmp/x", "/tmp/y"], capture_output=True, text=True, timeout=5)
-    if r.returncode != 0 and "connect" in r.stderr:
-        print("OK (TCP fallback)")
-    else:
-        print("FAIL")
-        errors.append("Posix arg syntax failed")
-
-    check_ssh_localhost()
-    print("  [5] SSH to localhost...", end=" ")
-    if SSH_AVAILABLE:
-        print("OK")
-    else:
-        print("SKIP (install fastsync-server in PATH on remote)")
-
-    if errors:
-        print(f"\n  {len(errors)} pre-flight check(s) failed: {', '.join(errors)}")
-        sys.exit(1)
-    print("  All pre-flight checks passed.\n")
-
-
-def main():
-    os.system("cmake -B build -S . > /dev/null 2>&1")
-    if os.system("cd build && make -j$(nproc) 2>&1 | tail -3") != 0:
-        print("Build failed")
-        sys.exit(1)
-    preflight_checks()
-    parser = argparse.ArgumentParser(description="FastSync integration test / benchmark")
-    parser.add_argument("--source-dir", default=DEFAULT_SOURCE_DIR)
-    parser.add_argument("--dest-dir", default=DEFAULT_DEST_DIR)
-    parser.add_argument("--keep-data", action="store_true")
-    parser.add_argument("--unlimited", action="store_true")
-    parser.add_argument("--wan", action="store_true")
-    parser.add_argument("--full", action="store_true", help="Run full test suite with network shaping, SSH, rsync benchmarks")
-    args = parser.parse_args()
-
-    total_bytes = generate_test_files(args.source_dir, full=args.full)
-    if os.path.exists(args.dest_dir):
-        shutil.rmtree(args.dest_dir)
-    os.makedirs(args.dest_dir, exist_ok=True)
-
-    profiles = []
-    if args.unlimited:
-        profiles.append("Unlimited")
-    elif args.wan:
-        profiles.append("WAN")
-    else:
-        profiles.append("LAN" if args.full else "Unlimited")
-
-    try:
-        all_results = []
-        for p in profiles:
-            all_results.extend(run_profile(p, args.source_dir, args.dest_dir, full=args.full))
-
-        print("\n" + "=" * 130)
-        print(f"{'RESULTS':^130}")
-        print("=" * 130)
-        print(f"{'Configuration':<45} | {'Profile':<12} | {'Status':<8} | {'Time':<10} | {'Details'}")
-        print("-" * 130)
-        for r in all_results:
-            print(f"{r['name']:<45} | {r['suite']:<12} | {r['status']:<8} | {r['time']:<10} | {r['error']}")
-
-        for p in profiles:
-            print_metrics(p, [r for r in all_results if r["suite"] == p], total_bytes)
-
-        failed = [r for r in all_results if r["status"] != "Success"]
-        if failed:
-            print(f"\n  {len(failed)} test(s) FAILED")
-            sys.exit(1)
-        print(f"\n  ALL {len(all_results)} TESTS PASSED")
-    finally:
-        if not args.keep_data:
-            shutil.rmtree(TEST_DIR, ignore_errors=True)
-
-
-if __name__ == "__main__":
-    main()

tests/conftest.py

@@ -0,0 +1,17 @@
+"""Shared pytest configuration for integration tests."""
+import os
+import sys
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "integration"))
+
+from common import ServerManager
+
+
+@pytest.fixture(scope="session")
+def shared_server():
+    """One server for the entire test session. Avoids 27+ server start/stop cycles."""
+    server = ServerManager()
+    server.start()
+    yield server
+    server.stop()

tests/integration/common.py

@@ -0,0 +1,181 @@
+import filecmp
+import os
+import random
+import shutil
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+
+PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+BUILD_DIR = os.path.join(PROJECT_ROOT, "build")
+SERVER_CMD = [os.path.join(BUILD_DIR, "server")]
+CLIENT_CMD = [os.path.join(BUILD_DIR, "client")]
+TEST_DATA_DIR = os.path.join(PROJECT_ROOT, "test_data")
+
+
+class ServerManager:
+    """Manages a long-lived server process. Reuses across test cases."""
+
+    def __init__(self):
+        self._proc = None
+        self._port = None
+
+    def start(self, extra_args=None):
+        self.stop()
+        self._port = _find_free_port()
+        cmd = SERVER_CMD + ["-p", str(self._port)]
+        if extra_args:
+            cmd += extra_args
+        self._proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        _wait_for_port(self._port, timeout=5)
+
+    def stop(self):
+        if self._proc:
+            _wait_proc(self._proc)
+            self._proc = None
+
+    @property
+    def port(self):
+        return self._port
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, *args):
+        self.stop()
+
+    def __del__(self):
+        self.stop()
+
+
+def run_client(source_dir, dest_dir, flags=None, port=None, extra_args=None):
+    """Run the client and return (result, duration)."""
+    cmd = CLIENT_CMD + ["--source-dir", source_dir, "--dest-dir", dest_dir, "--save-to-disk"]
+    if port:
+        cmd += ["--server-port", str(port)]
+    if flags:
+        cmd += flags
+    if extra_args:
+        cmd += extra_args
+    start = time.monotonic()
+    result = subprocess.run(cmd, text=True, capture_output=True)
+    duration = time.monotonic() - start
+    return result, duration
+
+
+def run_client_posix(source_dir, dest_dir, flags=None, port=None):
+    """Run the client with positional args (rsync-style)."""
+    cmd = CLIENT_CMD + [source_dir, dest_dir, "--save-to-disk"]
+    if port:
+        cmd += ["--server-port", str(port)]
+    if flags:
+        cmd += flags
+    start = time.monotonic()
+    result = subprocess.run(cmd, text=True, capture_output=True)
+    duration = time.monotonic() - start
+    return result, duration
+
+
+def generate_test_files(source_dir, full=False):
+    """Generate structured test data. Returns total bytes written."""
+    if os.path.exists(source_dir):
+        shutil.rmtree(source_dir)
+    os.makedirs(source_dir)
+
+    target_total = 25 * 1024 * 1024 if full else 0
+    written = 0
+
+    files = {
+        "small.txt": b"hello world\n",
+        "medium.txt": b"the quick brown fox jumps over the lazy dog\n" * 5000,
+        "binary.bin": bytes(range(256)) * 1000,
+        "nested/subdir/deep.txt": b"deeply nested file\n",
+        "nested/another.txt": b"another nested file\n" * 50,
+    }
+    for rel_path, content in files.items():
+        full_path = os.path.join(source_dir, rel_path)
+        os.makedirs(os.path.dirname(full_path), exist_ok=True)
+        with open(full_path, "wb") as f:
+            f.write(content)
+        written += len(content)
+
+    if full:
+        os.makedirs(os.path.join(source_dir, "bulk"), exist_ok=True)
+        i = 0
+        while written < target_total:
+            chunk_size = min(5 * 1024 * 1024, target_total - written)
+            with open(os.path.join(source_dir, f"bulk/file_{i}.dat"), "wb") as f:
+                f.write(random.randbytes(chunk_size))
+            written += chunk_size
+            i += 1
+
+    return written
+
+
+def verify_transfer(source_dir, received_dir):
+    """Verify all files from source exist in received_dir and match. Returns (mismatches, missing)."""
+    source_dir = os.path.abspath(source_dir)
+    received_dir = os.path.abspath(received_dir)
+    if not os.path.exists(received_dir):
+        return [], ["no received files found"]
+    mismatches, missing = [], []
+    for root, dirs, files in os.walk(source_dir):
+        for f in files:
+            src_path = os.path.join(root, f)
+            rel = os.path.relpath(src_path, source_dir)
+            dst_path = os.path.join(received_dir, rel)
+            if not os.path.exists(dst_path):
+                missing.append(rel)
+            elif not filecmp.cmp(src_path, dst_path, shallow=False):
+                mismatches.append(rel)
+    return mismatches, missing
+
+
+def clean_dir(path):
+    """Remove and recreate a directory."""
+    if os.path.exists(path):
+        shutil.rmtree(path)
+    os.makedirs(path, exist_ok=True)
+
+
+def make_result(name, success, duration=None, error=""):
+    """Create a standardized result dict."""
+    return {
+        "name": name,
+        "status": "Success" if success else "Failed",
+        "time": f"{duration:.4f}s" if duration is not None else "N/A",
+        "error": error,
+    }
+
+
+def get_dest_received_dir(dest_dir, source_dir):
+    """Get the path where received files land inside dest_dir."""
+    return os.path.join(dest_dir, os.path.abspath(source_dir).lstrip(os.sep))
+
+
+def _find_free_port():
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+def _wait_for_port(port, timeout=5):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.3):
+                return
+        except (ConnectionRefusedError, OSError):
+            time.sleep(0.05)
+    raise RuntimeError(f"Server port {port} not ready after {timeout}s")
+
+
+def _wait_proc(proc, timeout=5):
+    try:
+        proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()

tests/integration/test_features.py

@@ -0,0 +1,256 @@
+"""Feature tests: incremental sync, bandwidth limiting, dry run, metadata, filters."""
+import os
+import shutil
+import sys
+import time
+import pytest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import (
+    PROJECT_ROOT, BUILD_DIR, TEST_DATA_DIR,
+    run_client,
+    generate_test_files, verify_transfer, clean_dir, make_result,
+    get_dest_received_dir, CLIENT_CMD,
+)
+
+SOURCE_DIR = os.path.join(TEST_DATA_DIR, "feature_source")
+DEST_DIR = os.path.join(TEST_DATA_DIR, "feature_dest")
+
+
+@pytest.fixture(scope="module", autouse=True)
+def setup_test_data():
+    generate_test_files(SOURCE_DIR, full=False)
+    clean_dir(DEST_DIR)
+    yield
+    shutil.rmtree(TEST_DATA_DIR, ignore_errors=True)
+
+
+class TestDryRun:
+    def test_dry_run(self):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-n"],
+        )
+        assert result.returncode == 0, f"Exit {result.returncode}: {result.stderr[:100]}"
+        assert "Dry run:" in result.stdout, f"No dry run output: {result.stdout[:200]}"
+
+
+class TestArchiveMode:
+    def test_archive_mode(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-a"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing: {missing}"
+        assert not mismatches, f"Mismatch: {mismatches}"
+
+
+class TestExclude:
+    def test_exclude_single(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--exclude", "small.txt"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert "small.txt" in missing, "small.txt should be excluded but was transferred"
+        other_missing = [m for m in missing if m != "small.txt"]
+        assert not other_missing, f"Other files missing: {other_missing}"
+        assert not mismatches, f"Mismatch: {mismatches}"
+
+    def test_exclude_glob(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--exclude", "*.txt"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        assert not os.path.exists(os.path.join(received, "small.txt")), "small.txt should be excluded"
+        assert os.path.exists(os.path.join(received, "binary.bin")), "binary.bin should be present"
+
+
+class TestInclude:
+    def test_include_single(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--include", "binary.bin"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        assert os.path.exists(os.path.join(received, "binary.bin")), "binary.bin should be included"
+        assert not os.path.exists(os.path.join(received, "small.txt")), "small.txt should not be included"
+
+    def test_include_glob(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--include", "*.bin"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        assert os.path.exists(os.path.join(received, "binary.bin")), "binary.bin should be included"
+
+
+class TestSizeFilters:
+    def test_max_size(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--max-size", "100"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        assert os.path.exists(os.path.join(received, "small.txt")), "small.txt should be present"
+        assert not os.path.exists(os.path.join(received, "medium.txt")), "medium.txt should be skipped"
+
+    def test_min_size(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--min-size", "1000"],
+            port=shared_server.port,
+        )
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        assert not os.path.exists(os.path.join(received, "small.txt")), "small.txt should be skipped"
+        assert os.path.exists(os.path.join(received, "medium.txt")), "medium.txt should be present"
+
+
+class TestIncremental:
+    def test_incremental_skips_unchanged(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-M"],
+            port=shared_server.port,
+        )
+        assert result.returncode == 0, f"First sync failed: {result.stderr[:100]}"
+
+        start = time.monotonic()
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-M", "--incremental"],
+            port=shared_server.port,
+        )
+        incremental_time = time.monotonic() - start
+
+        assert result.returncode == 0, f"Incremental sync failed: {(result.stderr or result.stdout)[:200]}"
+
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing: {missing}"
+        assert not mismatches, f"Mismatch: {mismatches}"
+
+    def test_incremental_detects_changes(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, _ = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-M"],
+            port=shared_server.port,
+        )
+        assert result.returncode == 0
+
+        modified_file = os.path.join(SOURCE_DIR, "small.txt")
+        with open(modified_file, "wb") as f:
+            f.write(b"modified content for incremental test\n")
+
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-M", "--incremental"],
+            port=shared_server.port,
+        )
+        assert result.returncode == 0
+
+        with open(modified_file, "wb") as f:
+            f.write(b"hello world\n")
+
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        received_file = os.path.join(received, "small.txt")
+        assert os.path.exists(received_file), "Modified file should be present"
+        with open(received_file, "rb") as f:
+            content = f.read()
+        assert b"modified content" in content, f"Modified content not transferred: {content[:50]}"
+
+
+class TestDelete:
+    def test_delete_removes_extra_files(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, _ = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-M"],
+            port=shared_server.port,
+        )
+        assert result.returncode == 0
+
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        extra_file = os.path.join(received, "extra_file.txt")
+        extra_dir = os.path.join(received, "extra_dir")
+        with open(extra_file, "w") as f:
+            f.write("should be deleted")
+        os.makedirs(extra_dir, exist_ok=True)
+        with open(os.path.join(extra_dir, "nested.txt"), "w") as f:
+            f.write("nested extra")
+
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["-M", "--delete"],
+            port=shared_server.port,
+        )
+
+        assert result.returncode == 0, f"Delete sync failed: {(result.stderr or result.stdout)[:200]}"
+        assert not os.path.exists(extra_file), "extra_file.txt should be deleted"
+        assert not os.path.exists(extra_dir), "extra_dir should be deleted"
+
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing: {missing}"
+        assert not mismatches, f"Mismatch: {mismatches}"
+
+
+class TestProgress:
+    def test_progress_output(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--progress"],
+            port=shared_server.port,
+        )
+        assert result.returncode == 0, f"Exit {result.returncode}: {result.stderr[:100]}"
+        output = result.stdout + result.stderr
+        assert len(output) >= 0
+
+
+class TestBandwidthLimit:
+    def test_bwlimit_runs(self, shared_server):
+        clean_dir(DEST_DIR)
+        result, dur = run_client(
+            SOURCE_DIR, DEST_DIR,
+            flags=["--bwlimit", "10240"],
+            port=shared_server.port,
+        )
+        assert result.returncode == 0, f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}"
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing: {missing}"
+        assert not mismatches, f"Mismatch: {mismatches}"

tests/integration/test_preflight.py

@@ -0,0 +1,81 @@
+"""CLI validation and preflight checks."""
+import subprocess
+import sys
+import os
+import pytest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import BUILD_DIR, CLIENT_CMD, SERVER_CMD
+
+
+class TestHelp:
+    def test_client_help(self):
+        r = subprocess.run(CLIENT_CMD + ["--help"], capture_output=True, text=True)
+        assert r.returncode == 0
+        assert "Usage:" in r.stdout
+        assert "SSH transport" in r.stdout
+
+    def test_server_help(self):
+        r = subprocess.run(SERVER_CMD + ["--help"], capture_output=True, text=True)
+        assert r.returncode == 0
+        assert "Usage:" in r.stdout
+
+
+class TestSSHDetection:
+    def test_remote_dest_detected(self):
+        """Posix-style SSH dest should be detected and fail gracefully."""
+        r = subprocess.run(
+            CLIENT_CMD + ["/x", "somehost:/y"],
+            capture_output=True, text=True, timeout=5,
+        )
+        assert r.returncode != 0
+        stderr = (r.stderr or "").lower()
+        assert "ssh" in stderr or "error" in stderr or "could not" in stderr
+
+    def test_local_dest_not_ssh(self):
+        """Local path should not be detected as SSH."""
+        r = subprocess.run(
+            CLIENT_CMD + ["/tmp/x", "/tmp/y"],
+            capture_output=True, text=True, timeout=5,
+        )
+        # Should fail with connection error (no server), not SSH error
+        assert r.returncode != 0
+
+
+class TestServerStdio:
+    def test_stdio_mode_starts(self):
+        """Server --stdio should start and wait for stdin."""
+        try:
+            r = subprocess.run(
+                SERVER_CMD + ["--stdio"],
+                capture_output=True, text=True, timeout=3,
+            )
+            # Should exit with error (no data on stdin) or timeout
+        except subprocess.TimeoutExpired:
+            pass  # Expected: server waiting for stdin
+
+
+class TestServerPort:
+    def test_invalid_port(self):
+        """Server should reject invalid port numbers."""
+        r = subprocess.run(
+            SERVER_CMD + ["-p", "99999"],
+            capture_output=True, text=True, timeout=5,
+        )
+        assert r.returncode != 0
+
+    def test_default_port(self):
+        """Server should start on default port 8080."""
+        proc = subprocess.Popen(
+            SERVER_CMD, stdout=subprocess.DEVNULL, stderr=None,
+        )
+        try:
+            import socket, time
+            time.sleep(0.5)
+            with socket.create_connection(("127.0.0.1", 8080), timeout=2):
+                pass  # Port is listening
+        except (ConnectionRefusedError, OSError):
+            pytest.fail("Server not listening on default port 8080")
+        finally:
+            proc.terminate()
+            proc.wait(timeout=5)

tests/integration/test_ssh.py

@@ -0,0 +1,132 @@
+"""SSH transport tests."""
+import os
+import shutil
+import subprocess
+import sys
+import pytest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import (
+    PROJECT_ROOT, BUILD_DIR, TEST_DATA_DIR,
+    CLIENT_CMD, generate_test_files, verify_transfer, clean_dir, make_result,
+)
+
+SOURCE_DIR = os.path.join(TEST_DATA_DIR, "ssh_source")
+DEST_DIR = os.path.join(TEST_DATA_DIR, "ssh_dest")
+SSH_AVAILABLE = False
+
+
+def _check_ssh():
+    global SSH_AVAILABLE
+    try:
+        r = subprocess.run(
+            ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=5",
+             "localhost", "which", "fastsync-server"],
+            capture_output=True, timeout=10,
+        )
+        if r.returncode == 0:
+            SSH_AVAILABLE = True
+            return
+
+        # Try to install server binary into PATH
+        server_path = os.path.join(BUILD_DIR, "server")
+        r = subprocess.run(
+            ["ssh", "-o", "BatchMode=yes", "localhost", 'echo "$PATH"'],
+            capture_output=True, timeout=10, text=True,
+        )
+        if r.returncode != 0:
+            return
+        for d in r.stdout.strip().split(":"):
+            d = d.strip()
+            if not d or "wrappers" in d:
+                continue
+            test = subprocess.run(
+                ["ssh", "-o", "BatchMode=yes", "localhost",
+                 f'test -w "{d}" && ln -sf {server_path} "{d}/fastsync-server" && which fastsync-server'],
+                capture_output=True, timeout=10,
+            )
+            if test.returncode == 0:
+                SSH_AVAILABLE = True
+                return
+    except FileNotFoundError:
+        pass
+
+
+@pytest.fixture(scope="module", autouse=True)
+def setup_test_data():
+    _check_ssh()
+    if SSH_AVAILABLE:
+        generate_test_files(SOURCE_DIR, full=False)
+        clean_dir(DEST_DIR)
+    yield
+    shutil.rmtree(TEST_DATA_DIR, ignore_errors=True)
+
+
+def _run_ssh_test(name, flags, expected_missing=None):
+    """Run an SSH test case (no server process needed, client spawns SSH)."""
+    ssh_dest = f"localhost:{DEST_DIR}"
+    clean_dir(DEST_DIR)
+    cmd = CLIENT_CMD + [SOURCE_DIR, ssh_dest, "--save-to-disk"] + flags
+    start = __import__("time").monotonic()
+    result = subprocess.run(cmd, text=True, capture_output=True)
+    duration = __import__("time").monotonic() - start
+
+    if result.returncode != 0:
+        return make_result(name, False, duration, f"Exit {result.returncode}: {(result.stderr or result.stdout)[:100]}")
+
+    mismatches, missing = verify_transfer(SOURCE_DIR, DEST_DIR)
+    if expected_missing:
+        missing = [m for m in missing if m not in expected_missing]
+    if missing:
+        return make_result(name, False, duration, f"Missing: {', '.join(missing[:5])}")
+    if mismatches:
+        return make_result(name, False, duration, f"Mismatch: {', '.join(mismatches[:3])}")
+    return make_result(name, True, duration)
+
+
+@pytest.mark.skipif(not SSH_AVAILABLE, reason="SSH to localhost not available")
+class TestSSHStandard:
+    def test_standard(self):
+        r = _run_ssh_test("SSH (localhost)", [])
+        assert r["status"] == "Success", r["error"]
+
+    def test_multithreading(self):
+        r = _run_ssh_test("SSH Multithreading (-m)", ["-m"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_compression(self):
+        r = _run_ssh_test("SSH Compression (-c)", ["-c"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_chunk_serialization(self):
+        r = _run_ssh_test("SSH Chunk Serialization (-s)", ["-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_compression_chunk(self):
+        r = _run_ssh_test("SSH Compression + Chunk (-c -s)", ["-c", "-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_multithread_compression(self):
+        r = _run_ssh_test("SSH Multithread + Compression (-m -c)", ["-m", "-c"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_multithread_chunk(self):
+        r = _run_ssh_test("SSH Multithread + Chunk (-m -s)", ["-m", "-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_all_flags(self):
+        r = _run_ssh_test("SSH All Flags (-m -c -s)", ["-m", "-c", "-s"])
+        assert r["status"] == "Success", r["error"]
+
+
+@pytest.mark.skipif(not SSH_AVAILABLE, reason="SSH to localhost not available")
+class TestSSHFeatures:
+    def test_archive(self):
+        r = _run_ssh_test("SSH Archive (-a)", ["-a"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_exclude(self):
+        r = _run_ssh_test("SSH Exclude (--exclude small.txt)",
+                          ["--exclude", "small.txt"],
+                          expected_missing=["small.txt"])
+        assert r["status"] == "Success", r["error"]

tests/integration/test_tcp.py

@@ -0,0 +1,110 @@
+"""TCP transport correctness tests."""
+import os
+import shutil
+import sys
+import pytest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import (
+    PROJECT_ROOT, BUILD_DIR, TEST_DATA_DIR,
+    run_client, run_client_posix,
+    generate_test_files, verify_transfer, clean_dir, make_result,
+    get_dest_received_dir, CLIENT_CMD,
+)
+
+SOURCE_DIR = os.path.join(TEST_DATA_DIR, "tcp_source")
+DEST_DIR = os.path.join(TEST_DATA_DIR, "tcp_dest")
+
+
+@pytest.fixture(scope="module", autouse=True)
+def setup_test_data():
+    generate_test_files(SOURCE_DIR, full=False)
+    clean_dir(DEST_DIR)
+    yield
+    shutil.rmtree(TEST_DATA_DIR, ignore_errors=True)
+
+
+def _run_tcp_test(name, port, flags, use_metadata=True, posix=False):
+    """Run a single TCP test case against a shared server."""
+    clean_dir(DEST_DIR)
+    if posix:
+        result, dur = run_client_posix(SOURCE_DIR, DEST_DIR,
+                                       flags=(["-M"] if use_metadata else []) + flags,
+                                       port=port)
+    else:
+        result, dur = run_client(SOURCE_DIR, DEST_DIR,
+                                 flags=(["-M"] if use_metadata else []) + flags,
+                                 port=port)
+
+    if result.returncode != 0:
+        return make_result(name, False, dur, f"Exit {result.returncode}: {(result.stderr or result.stdout)[:100]}")
+
+    received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+    mismatches, missing = verify_transfer(SOURCE_DIR, received)
+    if missing:
+        return make_result(name, False, dur, f"Missing: {', '.join(missing[:5])}")
+    if mismatches:
+        return make_result(name, False, dur, f"Mismatch: {', '.join(mismatches[:3])}")
+    return make_result(name, True, dur)
+
+
+class TestTCPStandard:
+    def test_standard(self, shared_server):
+        r = _run_tcp_test("Standard", shared_server.port, [])
+        assert r["status"] == "Success", r["error"]
+
+    def test_posix_args(self, shared_server):
+        r = _run_tcp_test("Posix Args", shared_server.port, [], posix=True)
+        assert r["status"] == "Success", r["error"]
+
+    def test_no_metadata(self, shared_server):
+        r = _run_tcp_test("Standard (no metadata)", shared_server.port, [], use_metadata=False)
+        assert r["status"] == "Success", r["error"]
+
+
+class TestTCPFlags:
+    def test_multithreading(self, shared_server):
+        r = _run_tcp_test("Multithreading (-m)", shared_server.port, ["-m"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_compression(self, shared_server):
+        r = _run_tcp_test("Compression (-c)", shared_server.port, ["-c"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_chunk_serialization(self, shared_server):
+        r = _run_tcp_test("Chunk Serialization (-s)", shared_server.port, ["-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_compression_chunk(self, shared_server):
+        r = _run_tcp_test("Compression + Chunk (-c -s)", shared_server.port, ["-c", "-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_multithread_compression(self, shared_server):
+        r = _run_tcp_test("Multithreading + Compression (-m -c)", shared_server.port, ["-m", "-c"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_multithread_chunk(self, shared_server):
+        r = _run_tcp_test("Multithreading + Chunk (-m -s)", shared_server.port, ["-m", "-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_all_flags(self, shared_server):
+        r = _run_tcp_test("Multithread + Compression + Chunk (-m -c -s)", shared_server.port, ["-m", "-c", "-s"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_sendfile(self, shared_server):
+        r = _run_tcp_test("Sendfile (-f)", shared_server.port, ["-f"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_sendfile_multithread(self, shared_server):
+        r = _run_tcp_test("Sendfile + Multithreading (-f -m)", shared_server.port, ["-f", "-m"])
+        assert r["status"] == "Success", r["error"]
+
+
+class TestTCPChunkSize:
+    def test_custom_chunk_size(self, shared_server):
+        r = _run_tcp_test("Chunk size 5MB", shared_server.port, ["--chunk-size", "5242880"])
+        assert r["status"] == "Success", r["error"]
+
+    def test_small_chunk_size(self, shared_server):
+        r = _run_tcp_test("Chunk size 1KB", shared_server.port, ["--chunk-size", "1024"])
+        assert r["status"] == "Success", r["error"]

tests/integration/test_tls.py

@@ -0,0 +1,181 @@
+"""TLS transport tests. Generates self-signed certs for testing."""
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import pytest
+
+sys.path.insert(0, os.path.dirname(__file__))
+from common import (
+    PROJECT_ROOT, BUILD_DIR, SERVER_CMD, TEST_DATA_DIR,
+    ServerManager, run_client,
+    generate_test_files, verify_transfer, clean_dir, make_result,
+    get_dest_received_dir, _find_free_port, _wait_proc,
+)
+
+SOURCE_DIR = os.path.join(TEST_DATA_DIR, "tls_source")
+DEST_DIR = os.path.join(TEST_DATA_DIR, "tls_dest")
+CERT_DIR = os.path.join(TEST_DATA_DIR, "tls_certs")
+
+
+def _generate_certs(cert_dir):
+    """Generate a self-signed CA, server cert, and client cert for testing."""
+    os.makedirs(cert_dir, exist_ok=True)
+    ca_key = os.path.join(cert_dir, "ca.key")
+    ca_cert = os.path.join(cert_dir, "ca.pem")
+    server_key = os.path.join(cert_dir, "server.key")
+    server_cert = os.path.join(cert_dir, "server.pem")
+    client_key = os.path.join(cert_dir, "client.key")
+    client_cert = os.path.join(cert_dir, "client.pem")
+
+    # CA key + cert
+    subprocess.run([
+        "openssl", "req", "-x509", "-newkey", "rsa:2048", "-nodes",
+        "-keyout", ca_key, "-out", ca_cert,
+        "-days", "1", "-subj", "/CN=FastSync Test CA",
+    ], check=True, capture_output=True)
+
+    # Server key + CSR + cert (signed by CA)
+    subprocess.run([
+        "openssl", "req", "-newkey", "rsa:2048", "-nodes",
+        "-keyout", server_key, "-out", os.path.join(cert_dir, "server.csr"),
+        "-subj", "/CN=localhost",
+    ], check=True, capture_output=True)
+    subprocess.run([
+        "openssl", "x509", "-req", "-in", os.path.join(cert_dir, "server.csr"),
+        "-CA", ca_cert, "-CAkey", ca_key, "-CAcreateserial",
+        "-out", server_cert, "-days", "1",
+    ], check=True, capture_output=True)
+
+    # Client key + CSR + cert (signed by CA)
+    subprocess.run([
+        "openssl", "req", "-newkey", "rsa:2048", "-nodes",
+        "-keyout", client_key, "-out", os.path.join(cert_dir, "client.csr"),
+        "-subj", "/CN=fastsync-client",
+    ], check=True, capture_output=True)
+    subprocess.run([
+        "openssl", "x509", "-req", "-in", os.path.join(cert_dir, "client.csr"),
+        "-CA", ca_cert, "-CAkey", ca_key, "-CAcreateserial",
+        "-out", client_cert, "-days", "1",
+    ], check=True, capture_output=True)
+
+    return {
+        "ca": ca_cert,
+        "server_cert": server_cert,
+        "server_key": server_key,
+        "client_cert": client_cert,
+        "client_key": client_key,
+    }
+
+
+@pytest.fixture(scope="module")
+def certs():
+    """Generate test certificates once per test module."""
+    if os.path.exists(CERT_DIR):
+        shutil.rmtree(CERT_DIR)
+    c = _generate_certs(CERT_DIR)
+    yield c
+    shutil.rmtree(CERT_DIR, ignore_errors=True)
+
+
+@pytest.fixture(scope="module", autouse=True)
+def setup_test_data():
+    generate_test_files(SOURCE_DIR, full=False)
+    clean_dir(DEST_DIR)
+    yield
+    shutil.rmtree(TEST_DATA_DIR, ignore_errors=True)
+
+
+class TestTLSBasic:
+    def test_tls_server_client(self, certs):
+        """Basic TLS: server with cert/key, client with cert/key + CA."""
+        clean_dir(DEST_DIR)
+        with ServerManager() as server:
+            server.start(extra_args=[
+                "--tls", "--cert", certs["server_cert"], "--key", certs["server_key"],
+            ])
+            result, dur = run_client(
+                SOURCE_DIR, DEST_DIR,
+                flags=["--tls",
+                       "--cert", certs["client_cert"], "--key", certs["client_key"],
+                       "--ca", certs["ca"]],
+                port=server.port,
+            )
+
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing files: {missing}"
+        assert not mismatches, f"Mismatched files: {mismatches}"
+
+    def test_tls_with_compression(self, certs):
+        """TLS + compression."""
+        clean_dir(DEST_DIR)
+        with ServerManager() as server:
+            server.start(extra_args=[
+                "--tls", "--cert", certs["server_cert"], "--key", certs["server_key"],
+            ])
+            result, dur = run_client(
+                SOURCE_DIR, DEST_DIR,
+                flags=["-c", "--tls",
+                       "--cert", certs["client_cert"], "--key", certs["client_key"],
+                       "--ca", certs["ca"]],
+                port=server.port,
+            )
+
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing files: {missing}"
+        assert not mismatches, f"Mismatched files: {mismatches}"
+
+    def test_tls_with_multithreading(self, certs):
+        """TLS + multithreading."""
+        clean_dir(DEST_DIR)
+        with ServerManager() as server:
+            server.start(extra_args=[
+                "--tls", "--cert", certs["server_cert"], "--key", certs["server_key"],
+            ])
+            result, dur = run_client(
+                SOURCE_DIR, DEST_DIR,
+                flags=["-m", "--tls",
+                       "--cert", certs["client_cert"], "--key", certs["client_key"],
+                       "--ca", certs["ca"]],
+                port=server.port,
+            )
+
+        if result.returncode != 0:
+            pytest.fail(f"Exit {result.returncode}: {(result.stderr or result.stdout)[:200]}")
+
+        received = get_dest_received_dir(DEST_DIR, SOURCE_DIR)
+        mismatches, missing = verify_transfer(SOURCE_DIR, received)
+        assert not missing, f"Missing files: {missing}"
+        assert not mismatches, f"Mismatched files: {mismatches}"
+
+
+class TestTLSErrorCases:
+    def test_server_tls_missing_cert_key(self):
+        """Server should fail if --tls is given without --cert/--key."""
+        proc = subprocess.Popen(
+            SERVER_CMD + ["--tls"],
+            stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+        )
+        _, stderr = proc.communicate(timeout=5)
+        assert proc.returncode != 0, "Server should fail with --tls but no cert/key"
+
+    def test_client_tls_missing_key(self):
+        """Client should fail if --tls is given without --key."""
+        clean_dir(DEST_DIR)
+        with ServerManager() as server:
+            result, _ = run_client(
+                SOURCE_DIR, DEST_DIR,
+                flags=["--tls",
+                       "--cert", "/nonexistent/cert.pem"],
+                port=server.port,
+            )
+        assert result.returncode != 0, "Client should fail with --tls but no --key"

tests/runner.c

@@ -2,6 +2,7 @@
 #include "test_chunk.h"
 #include "test_compression.h"
 #include "test_config.h"
+#include "test_delta.h"
 #include "test_queue.h"
 #include "test_scanner.h"
 #include "test_shared_utils.h"
@@ -23,6 +24,7 @@ int main() {
   RUN_TEST(test_config);
   RUN_TEST(test_compression);
   RUN_TEST(test_scanner);
+  RUN_TEST(test_delta);
 
   printf("\n\033[1;36m=== TEST SUMMARY ===\033[0m\n");
   printf("Total Tests Run: %d\n", tests_run);

tests/test_delta.c

@@ -0,0 +1,334 @@
+#include "test_utils.h"
+#include "delta.h"
+#include <string.h>
+#include <stdlib.h>
+
+static void test_adler32_basic() {
+  const char *data = "Hello";
+  uint32_t h = delta_adler32(data, 5);
+  EXPECT_TRUE(h != 0);
+  uint32_t h2 = delta_adler32(data, 5);
+  EXPECT_EQ_INT((int)h, (int)h2);
+}
+
+static void test_adler32_different_data() {
+  const char *a = "AAAA";
+  const char *b = "BBBB";
+  uint32_t ha = delta_adler32(a, 4);
+  uint32_t hb = delta_adler32(b, 4);
+  EXPECT_TRUE(ha != hb);
+}
+
+static void test_xxhash32_basic() {
+  const char *data = "Hello";
+  uint32_t h = delta_xxhash32(data, 5);
+  EXPECT_TRUE(h != 0);
+  uint32_t h2 = delta_xxhash32(data, 5);
+  EXPECT_EQ_INT((int)h, (int)h2);
+}
+
+static void test_xxhash32_different_data() {
+  const char *a = "AAAA";
+  const char *b = "BBBB";
+  uint32_t ha = delta_xxhash32(a, 4);
+  uint32_t hb = delta_xxhash32(b, 4);
+  EXPECT_TRUE(ha != hb);
+}
+
+static void test_signature_roundtrip() {
+  char old_data[4096];
+  for (int i = 0; i < 4096; i++) old_data[i] = (char)(i % 256);
+
+  DeltaSignature *sig = delta_signature_create(old_data, 4096, 1024);
+  EXPECT_NOT_NULL(sig);
+  EXPECT_EQ_INT((int)sig->block_count, 4);
+  EXPECT_EQ_INT((int)sig->block_size, 1024);
+
+  Data *serialized = delta_signature_serialize(sig);
+  EXPECT_NOT_NULL(serialized);
+
+  DeltaSignature *deserialized = delta_signature_deserialize(serialized);
+  EXPECT_NOT_NULL(deserialized);
+  EXPECT_EQ_INT((int)deserialized->block_count, (int)sig->block_count);
+  EXPECT_EQ_INT((int)deserialized->block_size, (int)sig->block_size);
+
+  for (uint32_t i = 0; i < sig->block_count; i++) {
+    EXPECT_EQ_INT((int)deserialized->blocks[i].adler32, (int)sig->blocks[i].adler32);
+    EXPECT_EQ_INT((int)deserialized->blocks[i].xxhash, (int)sig->blocks[i].xxhash);
+  }
+
+  delta_signature_destroy(sig);
+  data_destroy(serialized);
+  delta_signature_destroy(deserialized);
+}
+
+static void test_delta_identical_files() {
+  char data[2048];
+  for (int i = 0; i < 2048; i++) data[i] = (char)(i % 128);
+
+  DeltaSignature *sig = delta_signature_create(data, 2048, 512);
+  EXPECT_NOT_NULL(sig);
+
+  Delta *delta = delta_compute(data, 2048, sig, 512);
+  EXPECT_NOT_NULL(delta);
+
+  bool has_match = false;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_BLOCK_MATCH) {
+      has_match = true;
+      break;
+    }
+  }
+  EXPECT_TRUE(has_match);
+
+  bool all_match = true;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type != DELTA_INSTR_BLOCK_MATCH) {
+      all_match = false;
+      break;
+    }
+  }
+  EXPECT_TRUE(all_match);
+
+  delta_signature_destroy(sig);
+  delta_destroy(delta);
+}
+
+static void test_delta_small_edit() {
+  char old_data[4096];
+  char new_data[4096];
+  for (int i = 0; i < 4096; i++) {
+    old_data[i] = (char)(i % 256);
+    new_data[i] = old_data[i];
+  }
+  new_data[100] = 'X';
+  new_data[101] = 'Y';
+  new_data[102] = 'Z';
+
+  DeltaSignature *sig = delta_signature_create(old_data, 4096, 1024);
+  EXPECT_NOT_NULL(sig);
+
+  Delta *delta = delta_compute(new_data, 4096, sig, 1024);
+  EXPECT_NOT_NULL(delta);
+
+  uint64_t total_literal = 0;
+  uint32_t match_count = 0;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_LITERAL)
+      total_literal += delta->instructions[i].literal.length;
+    else
+      match_count++;
+  }
+  EXPECT_TRUE(match_count > 0);
+  EXPECT_TRUE(total_literal < 4096);
+
+  void *reconstructed = delta_apply(old_data, 4096, delta, 1024);
+  EXPECT_NOT_NULL(reconstructed);
+  EXPECT_EQ_INT(memcmp(reconstructed, new_data, 4096), 0);
+
+  free(reconstructed);
+  delta_signature_destroy(sig);
+  delta_destroy(delta);
+}
+
+static void test_delta_completely_different() {
+  char old_data[4096];
+  char new_data[4096];
+  for (int i = 0; i < 4096; i++) {
+    old_data[i] = (char)(i * 7 + 3);
+    new_data[i] = (char)(i * 13 + 97);
+  }
+
+  DeltaSignature *sig = delta_signature_create(old_data, 4096, 1024);
+  EXPECT_NOT_NULL(sig);
+
+  Delta *delta = delta_compute(new_data, 4096, sig, 1024);
+  EXPECT_NOT_NULL(delta);
+
+  bool has_match = false;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_BLOCK_MATCH) {
+      has_match = true;
+      break;
+    }
+  }
+  EXPECT_TRUE(!has_match);
+  EXPECT_TRUE(!delta_is_worthwhile(delta, 4096));
+
+  delta_signature_destroy(sig);
+  delta_destroy(delta);
+}
+
+static void test_delta_serialize_roundtrip() {
+  char old_data[4096];
+  char new_data[4096];
+  for (int i = 0; i < 4096; i++) {
+    old_data[i] = (char)(i % 256);
+    new_data[i] = old_data[i];
+  }
+  new_data[500] = 'A';
+  new_data[501] = 'B';
+
+  DeltaSignature *sig = delta_signature_create(old_data, 4096, 1024);
+  Delta *delta = delta_compute(new_data, 4096, sig, 1024);
+  EXPECT_NOT_NULL(delta);
+
+  Data *serialized = delta_serialize(delta);
+  EXPECT_NOT_NULL(serialized);
+
+  Delta *deserialized = delta_deserialize(serialized);
+  EXPECT_NOT_NULL(deserialized);
+  EXPECT_EQ_INT((int)deserialized->new_file_size, (int)delta->new_file_size);
+  EXPECT_EQ_INT((int)deserialized->instruction_count, (int)delta->instruction_count);
+
+  void *reconstructed = delta_apply(old_data, 4096, deserialized, 1024);
+  EXPECT_NOT_NULL(reconstructed);
+  EXPECT_EQ_INT(memcmp(reconstructed, new_data, 4096), 0);
+
+  free(reconstructed);
+  data_destroy(serialized);
+  delta_destroy(deserialized);
+  delta_signature_destroy(sig);
+  delta_destroy(delta);
+}
+
+static void test_delta_file_growth() {
+  char old_data[2048];
+  char new_data[3072];
+  for (int i = 0; i < 2048; i++) old_data[i] = (char)(i % 256);
+  memcpy(new_data, old_data, 2048);
+  for (int i = 2048; i < 3072; i++) new_data[i] = (char)(i % 256);
+
+  DeltaSignature *sig = delta_signature_create(old_data, 2048, 512);
+  EXPECT_NOT_NULL(sig);
+
+  Delta *delta = delta_compute(new_data, 3072, sig, 512);
+  EXPECT_NOT_NULL(delta);
+
+  void *reconstructed = delta_apply(old_data, 2048, delta, 512);
+  EXPECT_NOT_NULL(reconstructed);
+  EXPECT_EQ_INT(delta->new_file_size, 3072);
+  EXPECT_EQ_INT(memcmp(reconstructed, new_data, 3072), 0);
+
+  free(reconstructed);
+  delta_signature_destroy(sig);
+  delta_destroy(delta);
+}
+
+static void test_delta_file_shrink() {
+  char old_data[3072];
+  char new_data[2048];
+  for (int i = 0; i < 3072; i++) old_data[i] = (char)(i % 256);
+  for (int i = 0; i < 2048; i++) new_data[i] = old_data[i];
+
+  DeltaSignature *sig = delta_signature_create(old_data, 3072, 512);
+  EXPECT_NOT_NULL(sig);
+
+  Delta *delta = delta_compute(new_data, 2048, sig, 512);
+  EXPECT_NOT_NULL(delta);
+
+  void *reconstructed = delta_apply(old_data, 3072, delta, 512);
+  EXPECT_NOT_NULL(reconstructed);
+  EXPECT_EQ_INT(delta->new_file_size, 2048);
+  EXPECT_EQ_INT(memcmp(reconstructed, new_data, 2048), 0);
+
+  free(reconstructed);
+  delta_signature_destroy(sig);
+  delta_destroy(delta);
+}
+
+static void test_should_attempt() {
+  EXPECT_TRUE(delta_should_attempt(100000, 100000, DELTA_MAX_FILE_SIZE));
+  EXPECT_TRUE(!delta_should_attempt(100, 100, DELTA_MAX_FILE_SIZE));
+  EXPECT_TRUE(!delta_should_attempt(100000, 10, DELTA_MAX_FILE_SIZE));
+  EXPECT_TRUE(!delta_should_attempt(300000000, 300000000, DELTA_MAX_FILE_SIZE));
+  EXPECT_TRUE(delta_should_attempt(50000, 60000, DELTA_MAX_FILE_SIZE));
+  EXPECT_TRUE(!delta_should_attempt(50000, 600000, DELTA_MAX_FILE_SIZE));
+  EXPECT_TRUE(delta_should_attempt(50000, 60000, 500000));
+  EXPECT_TRUE(!delta_should_attempt(100000, 100000, 50000));
+}
+
+static void test_is_worthwhile() {
+  Delta d;
+  d.instruction_count = 1;
+  DeltaInstruction instr;
+  instr.type = DELTA_INSTR_BLOCK_MATCH;
+  d.instructions = &instr;
+
+  d.delta_size = 100;
+  EXPECT_TRUE(delta_is_worthwhile(&d, 1000));
+
+  d.delta_size = 800;
+  EXPECT_TRUE(!delta_is_worthwhile(&d, 1000));
+
+  d.instruction_count = 1;
+  instr.type = DELTA_INSTR_LITERAL;
+  EXPECT_TRUE(!delta_is_worthwhile(&d, 1000));
+
+  EXPECT_TRUE(!delta_is_worthwhile(NULL, 1000));
+}
+
+static void test_large_file_delta() {
+  uint32_t block_size = 8192;
+  uint64_t old_size = 200000;
+  uint64_t new_size = 200000;
+
+  void *old_data = malloc((size_t)old_size);
+  void *new_data = malloc((size_t)new_size);
+  EXPECT_TRUE(old_data != NULL && new_data != NULL);
+
+  for (uint64_t i = 0; i < old_size; i++)
+    ((uint8_t *)old_data)[i] = (uint8_t)(i % 251);
+  memcpy(new_data, old_data, (size_t)old_size);
+
+  uint64_t offset = 100000;
+  uint32_t change_len = 4096;
+  for (uint32_t i = 0; i < change_len; i++)
+    ((uint8_t *)new_data)[offset + i] = (uint8_t)((i * 7 + 13) % 256);
+
+  DeltaSignature *sig = delta_signature_create(old_data, old_size, block_size);
+  EXPECT_TRUE(sig != NULL);
+  EXPECT_TRUE(sig->block_count == (uint32_t)((old_size + block_size - 1) / block_size));
+
+  Delta *delta = delta_compute(new_data, new_size, sig, block_size);
+  EXPECT_TRUE(delta != NULL);
+
+  uint64_t total_literal = 0;
+  uint32_t match_count = 0;
+  for (uint32_t i = 0; i < delta->instruction_count; i++) {
+    if (delta->instructions[i].type == DELTA_INSTR_LITERAL)
+      total_literal += delta->instructions[i].literal.length;
+    else
+      match_count++;
+  }
+  EXPECT_TRUE(match_count > 0);
+  EXPECT_TRUE(delta->delta_size < new_size / 2);
+
+  void *result = delta_apply(old_data, old_size, delta, block_size);
+  EXPECT_TRUE(result != NULL);
+  EXPECT_TRUE(delta->new_file_size == new_size);
+  EXPECT_TRUE(memcmp(result, new_data, (size_t)new_size) == 0);
+
+  free(result);
+  delta_destroy(delta);
+  delta_signature_destroy(sig);
+  free(old_data);
+  free(new_data);
+}
+
+void test_delta() {
+  test_adler32_basic();
+  test_adler32_different_data();
+  test_xxhash32_basic();
+  test_xxhash32_different_data();
+  test_signature_roundtrip();
+  test_delta_identical_files();
+  test_delta_small_edit();
+  test_delta_completely_different();
+  test_delta_serialize_roundtrip();
+  test_delta_file_growth();
+  test_delta_file_shrink();
+  test_should_attempt();
+  test_is_worthwhile();
+  test_large_file_delta();
+}

tests/test_delta.h

@@ -0,0 +1,6 @@
+#ifndef TEST_DELTA_H
+#define TEST_DELTA_H
+
+void test_delta(void);
+
+#endif