Delta-upload protocol: negotiate chunks by hash, upload only what changed

Phase 1 of the delta-sync plan, server side. The CDC store already shares
unchanged chunks between file versions after the bytes arrive; these three
stateless endpoints move that detection to the client, so editing a few
bytes of a large file uploads ~1 MiB instead of the whole file:

- POST /api/files/delta/negotiate — given the file's chunk hashes, answer
  which ones the caller must upload. User-scoped and purely advisory.
- PUT  /api/files/delta/chunks — missing chunks as [u32 BE len][bytes]
  frames (streaming parse, ≤1 MiB per frame, chunk_max_bytes per request).
  Every hash is recomputed server-side; chunks land as ref_count=0 orphans
  that a commit pins or the periodic GC sweeps — no session table.
- POST /api/files/delta/commit — pin one reference per distinct chunk with
  a single UPDATE…RETURNING restricted to chunks the caller is entitled
  to (reachable through their own non-trashed files, or unreferenced
  orphans); anything else returns 409 {still_missing} for the client to
  upload and retry. The pinned sequence is then RE-READ and the whole-file
  BLAKE3 recomputed before any manifest exists — a declared file_hash is
  never trusted, because a forged manifest would poison future whole-file
  dedup hits for other users. The manifest accounting is shared with the
  byte path (attach_manifest, extracted from store_from_stream); the file
  row is created (201) or its content swapped by file_id (200). Owners of
  the exact file_hash short-circuit to a pure reference bump.

Supporting pieces: GIN index on chunk_manifests.chunk_hashes (containment
probes were sequential scans), claimable/pin/release/store-loose/verify
primitives on DedupService, update-by-id with Update-permission AuthZ on
FileUploadService, per-caller rate limiter (240/min), audit events with
stable reasons (rate_limited, chunk_verification_failed,
file_hash_mismatch), OpenAPI + docs/delta-upload-protocol.md, framing
parser unit tests and a PG-gated integration suite covering the
entitlement matrix (owned/foreign/orphan/unknown), orphan registration
and the verification read.

Verified end-to-end against PostgreSQL 16 with a node client hashing via
the vendored WASM: a 24 MB file delta-committed in 96 fixed-size chunks;
a 3-byte edit then negotiated missing 1/96 and synced with 278 KB on the
wire vs 24 MB (98.9% saved), downloading byte-identical. A second user
probing the same chunks got nothing (negotiate: all missing; commit: 409
with all 96 still withheld); a forged file_hash returned 400 plus the
audit line; a commit referencing one never-uploaded chunk returned 409
naming exactly that hash; the GIN index serves containment probes
(Bitmap Index Scan) once the planner favors it.

https://claude.ai/code/session_01WdNenpnujNR2sc32XVvwfS

src/common/di.rs

@@ -461,6 +461,18 @@ impl AppServiceFactory {
             ),
         );
 
+        // Delta-upload protocol — chunk negotiation over the same dedup
+        // store. Bounded by the same whole-file ceiling as byte uploads.
+        let delta_upload_service = Arc::new(
+            crate::application::services::delta_upload_service::DeltaUploadService::new(
+                core.dedup_service.clone(),
+                file_upload_service.clone(),
+                storage_usage.clone(),
+                authz.clone(),
+                self.config.storage.max_upload_size as u64,
+            ),
+        );
+
         let file_retrieval_service = Arc::new(FileRetrievalService::new_with_cache(
             repos.file_read_repository.clone(),
             core.file_content_cache.clone(),
@@ -505,6 +517,7 @@ impl AppServiceFactory {
             // Traits for abstraction
             folder_service,
             file_upload_service,
+            delta_upload_service,
             file_retrieval_service,
             file_management_service,
             file_use_case_factory,
@@ -1040,6 +1053,13 @@ impl AppServiceFactory {
             user_profile_rate_limiter: Arc::new(
                 crate::interfaces::middleware::rate_limit::RateLimiter::new(60, 60, 50_000),
             ),
+            // Delta upload: 240 requests / minute / caller. Generous for a
+            // real client (chunk PUTs carry up to 100 MB each) while
+            // stopping pin/negotiate floods; 50 000 tracked callers bound
+            // the memory like the other limiters.
+            delta_upload_rate_limiter: Arc::new(
+                crate::interfaces::middleware::rate_limit::RateLimiter::new(240, 60, 50_000),
+            ),
             // PR 12 — per-sharer email-invite ceiling: caller_id-keyed.
             // Defends against a compromised account spamming external
             // invites (each invite mints a new external user + email).
@@ -1377,6 +1397,8 @@ pub struct ApplicationServices {
     // Traits for abstraction
     pub folder_service: Arc<FolderService>,
     pub file_upload_service: Arc<FileUploadService>,
+    pub delta_upload_service:
+        Arc<crate::application::services::delta_upload_service::DeltaUploadService>,
     pub file_retrieval_service: Arc<FileRetrievalService>,
     pub file_management_service: Arc<FileManagementService>,
     pub file_use_case_factory: Arc<dyn FileUseCaseFactory>,
@@ -1496,6 +1518,9 @@ pub struct AppState {
     /// authenticated caller covers any legitimate UI rendering while
     /// throttling enumeration.
     pub user_profile_rate_limiter: Arc<crate::interfaces::middleware::rate_limit::RateLimiter>,
+    /// Per-caller flood guard for the delta-upload endpoints
+    /// (negotiate / chunks / commit share one budget).
+    pub delta_upload_rate_limiter: Arc<crate::interfaces::middleware::rate_limit::RateLimiter>,
     /// Per-sharer ceiling on `POST /api/grants` invitations whose
     /// subject is `{ type: "email" }`. 50 per hour keyed on
     /// `caller_id`. Anonymous attackers can't reach this code path