Decide: make --download-mode file the default and retire the diff download path

[mikolalysenko]

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: discussion #560 register.

Kind: decision. Source: review Part 7.4 and R10; register C25.

Question

--download-mode diff is the default, but on a cold cache it downloads every diff archive and then every blob anyway. Should file become the default, and should the diff download path be retired?

Options:

• A. Make file the default now (a MAJOR per CLI_CONTRACT.md#L1578). Keep diff as an accepted value that behaves like file for one major, then delete the diff machinery. Recommended.
• B. Keep diff as the default, but stop the redundant blob top-up. Fetch blobs only for the files whose diff is missing or for created files, as is already done when every archive is cached. That keeps all the diff code and fixes only the bytes.
• C. No change.

Problem (verified at 045d7ec)

• Default: default_value = "diff" (args.rs#L153-L162).
• Cold cache: in fetch_stage.rs#L314-L319,`` diff mode downloads whenever any archive is missing. Then the top-up in fetch_stage.rs#L377-L398 sets `blob_scope = manifest` whenever `missing_diff_archives` was non-empty, and fetches every blob still missing from the stage. The diff fetch writes no blobs, so that is all of them.
• When diff saves bytes: only when a user has committed .socket/diffs but not .socket/blobs. Then just the blobs of created files are fetched (files_diffs_cannot_cover).
• Code that exists only for diff:
  • patch/diff.rs (99 production lines, bspatch);
  • patch/package.rs (332 production lines, diff archive tarball reader);
  • fetch_missing_diff_archives and get_missing_archives in api/blob_fetcher.rs;
  • resolve_from_diff / AppliedVia::Diff in patch/apply.rs;
  • the diff branches of fetch_stage.rs (patches_without_source, files_diffs_cannot_cover, the top-up, deferred failures) and repair.rs;
  • the qbsdiff dependency in both crates.
• Overlap with other work: diff archives are fetched sequentially with no retry (Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676 tracks retry), and the streaming work in Stream patch blob and diff downloads to disk (#571) #607 has to handle both artifact kinds.

Impact: every first apply on a fresh CI checkout pays an extra round-trip per patch for archives it then backs up with blobs. Removing the path deletes roughly 700 production lines and a dependency.

Proposed change (option A)

1. Change the default to file (clap default_value, the GlobalArgs::default(), CLI_CONTRACT.md line 56 and the env table, and the changelog as a MAJOR). diff stays accepted.
2. Next major: make diff an alias of file, and delete patch/diff.rs, patch/package.rs, the diff fetch and coverage code in blob_fetcher.rs/fetch_stage.rs/repair.rs, AppliedVia::Diff, PatchSources::diffs_path and qbsdiff. repair keeps sweeping orphaned .socket/diffs/* once, then the directory is ignored.

Size and scope

• Step 1: ~20 lines plus docs.
• Step 2: about −700 production lines and −1,000 test lines, and it lands as one PR.
• Out of scope: blob retry (Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676) and streaming (Stream patch blob and diff downloads to disk (#571) #607).

Acceptance criteria

• The owner picks an option.
• (A, step 1) socket-patch apply on a cold cache issues blob GETs only; a test asserts that no /diffs/ request is made with the default.
• (A, step 2) cargo tree -p socket-patch-cli lists no qbsdiff; the apply/repair suites stay green with diff fixtures removed.
• (B) A cold-cache diff-mode test asserts that blobs are fetched only for the files no fetched archive covers.

Dependencies

• Interacts with An invalid --download-mode fails apply and repair with exit 1 but is accepted by every other command #791 (typed --download-mode), Stream patch blob and diff downloads to disk (#571) #607 and Tracking: one retry primitive for the patch API client (JSON, vendor service, blob and diff) #676.
• Blocks nothing.