Merge main into arch-refactor/792-retire-diff-download-mode

Resolve docs/migrating-to-v5.md: keep this PR's --download-mode removal
row and main's new SOCKET_FORCE row (#1021) in the removed-spellings table.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

.github/workflows/composer-compatibility.yml

@@ -181,7 +181,10 @@ jobs:
         include:
           - {os: macos-latest, composer: '1.10.28', php: '8.1', sha256: 0915af36eb01e3f0e16cd309adff7051832b9ef014e38371756804b20425cd5a}
           - {os: macos-latest, composer: '2.2.30', php: '8.3', sha256: 8c2b4478b64f8f7cdf1574838fdb0033b29049ca821dad452db7a3dcfcdbffc2}
-          - {os: macos-latest, composer: '2.10.3', php: '8.5', sha256: 7a2d379d5b8ffdaa028580ef26494c36d2feef4b178d3dd1473a4dbc5e17c8d6}
+          # PHP 8.4 on macOS: setup-php 2.37.2 cannot install 8.5 from Homebrew
+          # since PHP 8.6 shipped (every run from 2026-10-07 23:51Z failed in
+          # "Setup PHP"). Ubuntu and Windows keep the 2.10.3 / 8.5 cell.
+          - {os: macos-latest, composer: '2.10.3', php: '8.4', sha256: 7a2d379d5b8ffdaa028580ef26494c36d2feef4b178d3dd1473a4dbc5e17c8d6}
     runs-on: ${{ matrix.os }}
     timeout-minutes: 60
     steps: *native-steps

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -676,7 +676,6 @@ pub const GLOBAL_ARG_ENV_VARS: &[&str] = &[
 /// missing here escapes the empty-var scrub — the invariant tests below
 /// parse every entry against its owning subcommand to keep this honest.
 pub const LOCAL_ARG_ENV_VARS: &[&str] = &[
-    "SOCKET_FORCE",
     "SOCKET_PATCH_VERSION",
     "SOCKET_SAVE_ONLY",
     "SOCKET_ALL_RELEASES",
@@ -1619,9 +1618,6 @@ mod tests {
         // (env var, argv of a subcommand that binds it) — every bool entry
         // of `LOCAL_ARG_ENV_VARS`, on each subcommand that binds it.
         const BOOL_BINDINGS: &[(&str, &[&str])] = &[
-            ("SOCKET_FORCE", &["socket-patch", "apply"]),
-            ("SOCKET_FORCE", &["socket-patch", "vendor"]),
-            ("SOCKET_FORCE", &["socket-patch", "self-update"]),
             ("SOCKET_SAVE_ONLY", &["socket-patch", "get", "x"]),
             ("SOCKET_ALL_RELEASES", &["socket-patch", "get", "x"]),
             ("SOCKET_ALL_RELEASES", &["socket-patch", "scan"]),
@@ -1659,6 +1655,48 @@ mod tests {
         });
     }
 
+    /// v5 retired `SOCKET_FORCE` (#615): `--force` is flag-only on `apply`,
+    /// `vendor` and `--update`. A stale export must be ignored, so it can
+    /// never quietly skip the beforeHash check or the managed-install
+    /// refusal; the flag itself still works.
+    #[test]
+    #[serial_test::serial]
+    fn socket_force_env_is_ignored_and_force_flag_still_works() {
+        fn force_of(argv: &[&str]) -> bool {
+            let argv = argv.iter().map(|s| s.to_string()).collect();
+            match crate::parse_argv_with_shortcuts(argv)
+                .unwrap_or_else(|e| panic!("parse failed: {e}"))
+                .command
+            {
+                crate::Commands::Apply(a) => a.force,
+                crate::Commands::Vendor(a) => a.force,
+                crate::Commands::SelfUpdate(a) => a.force,
+                _ => panic!("unexpected subcommand"),
+            }
+        }
+
+        const ARGVS: &[&[&str]] = &[
+            &["socket-patch", "apply"],
+            &["socket-patch", "vendor"],
+            &["socket-patch", "self-update"],
+            &["socket-patch", "--update"],
+        ];
+
+        with_clean_socket_env(|| {
+            with_env_cleared(&["SOCKET_FORCE"], || {
+                for val in ["1", "true", "yes"] {
+                    std::env::set_var("SOCKET_FORCE", val);
+                    for &argv in ARGVS {
+                        assert!(!force_of(argv), "SOCKET_FORCE={val} set force on {argv:?}");
+                        let mut with_flag = argv.to_vec();
+                        with_flag.push("--force");
+                        assert!(force_of(&with_flag), "--force ignored on {argv:?}");
+                    }
+                }
+            });
+        });
+    }
+
     /// Companion invariant for the **value-typed** local env vars: an
     /// exported-but-empty value (`VAR=`) must not crash its subcommand —
     /// [`scrub_empty_env_vars`] (run by `main` before clap) removes it, and

crates/socket-patch-cli/src/args.rs

@@ -106,7 +106,6 @@ pub struct ApplyArgs {
     #[arg(
         short = 'f',
         long,
-        env = "SOCKET_FORCE",
         default_value_t = false,
         value_parser = crate::args::parse_bool_flag,
     )]

crates/socket-patch-cli/src/commands/apply.rs

@@ -1496,7 +1496,7 @@ async fn filter_to_installed_purls(
         if mode != super::scan::ScanMode::Agent {
             present.extend(supplement.entries.iter().map(|e| PurlKey::new(&e.purl)));
             let vendored =
-                super::scan::project_vendored_supplement(common, &[], &ctx.loaded().await.vendor)
+                super::scan::project_vendored_supplement(&ctx, &[], &ctx.loaded().await.vendor)
                     .await;
             present.extend(vendored.packages.iter().map(|p| PurlKey::new(&p.purl)));
         }

crates/socket-patch-cli/src/commands/get.rs

@@ -173,16 +173,20 @@ pub(crate) struct LedgerSupplement {
 /// the ledger `run` already loaded (`vendor::load_state`).
 ///
 /// That holds only while the lock still wires the artifact. An entry the
-/// lockfile in-use probe (the one the prune GC reverts by) answers
-/// `Some(false)` for is the dependency having left the lock — bumped or
+/// project no longer consumes ([`Discovery::vendor_entry_in_use`] is
+/// `Some(false)` — the verdict the prune GC reverts by, read from `ctx`'s
+/// discovery) is the dependency having left the lock — bumped or
 /// uninstalled — and is reported in [`LedgerSupplement::unwired`] instead:
 /// re-vendoring it would fail against a lock that no longer has it. `None`
-/// (no probe for the ecosystem, or no readable lock) keeps the entry.
+/// (no readable lock for the ecosystem) keeps the entry.
+///
+/// [`Discovery::vendor_entry_in_use`]: socket_patch_core::vex::discover::Discovery::vendor_entry_in_use
 pub(crate) async fn vendored_ledger_supplement(
-    common: &GlobalArgs,
+    ctx: &crate::commands::context::ProjectContext<'_>,
     crawled: &[socket_patch_core::crawlers::types::CrawledPackage],
     state: &std::io::Result<VendorState>,
 ) -> LedgerSupplement {
+    let common = ctx.common;
     let mut out = LedgerSupplement::default();
     if common.is_global() {
         return out;
@@ -226,7 +230,12 @@ pub(crate) async fn vendored_ledger_supplement(
             continue;
         }
         if let Some(entry) = entry {
-            if crate::commands::vendor::dispatch_in_use_one(entry, &common.cwd).await == Some(false)
+            if ctx
+                .discovery()
+                .await
+                .vendor_entry_in_use(&common.cwd, entry)
+                .await
+                == Some(false)
             {
                 out.unwired.push(ledger_key.clone());
                 continue;
@@ -1120,9 +1129,13 @@ mod tests {
             ..GlobalArgs::default()
         };
         let state = socket_patch_core::vendor::load_state(root).await;
-        vendored_ledger_supplement(&args, crawled, &state)
-            .await
-            .packages
+        vendored_ledger_supplement(
+            &crate::commands::context::ProjectContext::new(&args),
+            crawled,
+            &state,
+        )
+        .await
+        .packages
     }
 
     /// A ledger entry vendored as `@3.0.2.0` is the crawled composer
@@ -1148,18 +1161,26 @@ mod tests {
             cwd: tmp.path().to_path_buf(),
             ..GlobalArgs::default()
         };
-        let out = vendored_ledger_supplement(&args, &[crawled], &Ok(state.clone()))
-            .await
-            .packages;
+        let out = vendored_ledger_supplement(
+            &crate::commands::context::ProjectContext::new(&args),
+            &[crawled],
+            &Ok(state.clone()),
+        )
+        .await
+        .packages;
         assert!(
             out.is_empty(),
             "{:?}",
             out.iter().map(|p| &p.purl).collect::<Vec<_>>()
         );
 
-        let out = vendored_ledger_supplement(&args, &[], &Ok(state))
-            .await
-            .packages;
+        let out = vendored_ledger_supplement(
+            &crate::commands::context::ProjectContext::new(&args),
+            &[],
+            &Ok(state),
+        )
+        .await
+        .packages;
         assert_eq!(
             out.iter().map(|p| p.purl.as_str()).collect::<Vec<_>>(),
             vec!["pkg:composer/psr/log@3.0.2.0"]
@@ -1229,19 +1250,82 @@ mod tests {
         })
         .to_string();
         let state = npm_ledger_with_lock(tmp.path(), Some(&bumped)).await;
-        let out = vendored_ledger_supplement(&args(tmp.path()), &[], &state).await;
+        let out = vendored_ledger_supplement(
+            &crate::commands::context::ProjectContext::new(&args(tmp.path())),
+            &[],
+            &state,
+        )
+        .await;
         assert!(out.packages.is_empty(), "{:?}", out.packages);
         assert_eq!(out.unwired, vec!["pkg:npm/left-pad@1.3.0".to_string()]);
 
         // Uninstalled: the lock has no left-pad at all.
         let tmp = tempfile::tempdir().unwrap();
         let removed = r#"{"name":"app","lockfileVersion":3,"packages":{"":{"name":"app"}}}"#;
         let state = npm_ledger_with_lock(tmp.path(), Some(removed)).await;
-        let out = vendored_ledger_supplement(&args(tmp.path()), &[], &state).await;
+        let out = vendored_ledger_supplement(
+            &crate::commands::context::ProjectContext::new(&args(tmp.path())),
+            &[],
+            &state,
+        )
+        .await;
         assert!(out.packages.is_empty(), "{:?}", out.packages);
         assert_eq!(out.unwired, vec!["pkg:npm/left-pad@1.3.0".to_string()]);
     }
 
+    /// B19: the supplement and the prune GC share one in-use verdict for
+    /// every ecosystem, not only npm/cargo/pypi-requirements. A COMPOSER
+    /// entry whose dependency composer.lock bumped to a registry release is
+    /// unwired — before, it was resurrected as a discovered package forever.
+    #[tokio::test]
+    async fn ledger_supplement_reports_a_bumped_composer_entry_unwired() {
+        const COMPOSER_PURL: &str = "pkg:composer/monolog/monolog@3.0.0";
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path();
+        let leaf = format!(".socket/vendor/composer/{VENDORED_UUID}/monolog/monolog@3.0.0");
+        let entry: socket_patch_core::vendor::VendorEntry =
+            serde_json::from_value(serde_json::json!({
+                "ecosystem": "composer",
+                "basePurl": COMPOSER_PURL,
+                "uuid": VENDORED_UUID,
+                "artifact": {"path": leaf, "sha256": ""},
+                "wiring": [],
+                "detached": true,
+            }))
+            .unwrap();
+        let mut state = VendorState::default();
+        state.entries.insert(COMPOSER_PURL.to_string(), entry);
+        std::fs::write(
+            root.join("composer.lock"),
+            serde_json::json!({
+                "packages": [{
+                    "name": "monolog/monolog",
+                    "version": "3.1.0",
+                    "dist": {
+                        "type": "zip",
+                        "url": "https://api.github.com/repos/Seldaek/monolog/zipball/abc",
+                        "reference": "abc",
+                    },
+                }],
+                "packages-dev": [],
+            })
+            .to_string(),
+        )
+        .unwrap();
+        let args = GlobalArgs {
+            cwd: root.to_path_buf(),
+            ..GlobalArgs::default()
+        };
+        let out = vendored_ledger_supplement(
+            &crate::commands::context::ProjectContext::new(&args),
+            &[],
+            &Ok(state),
+        )
+        .await;
+        assert!(out.packages.is_empty(), "{:?}", out.packages);
+        assert_eq!(out.unwired, vec![COMPOSER_PURL.to_string()]);
+    }
+
     /// The fresh-clone case the supplement exists for: the lock still
     /// resolves through the committed artifact, so the entry stays
     /// discoverable. With no lock at all, nothing proves the entry unused,
@@ -1260,7 +1344,12 @@ mod tests {
                 ..GlobalArgs::default()
             };
             let state = npm_ledger_with_lock(tmp.path(), lock.as_deref()).await;
-            let out = vendored_ledger_supplement(&args, &[], &state).await;
+            let out = vendored_ledger_supplement(
+                &crate::commands::context::ProjectContext::new(&args),
+                &[],
+                &state,
+            )
+            .await;
             assert_eq!(
                 out.packages
                     .iter()