Gradle agent: restore unread m2 copies, judge partly-held copies, probe hash dirs

- rollback/remove restore a ~/.m2 copy a Gradle-only build no longer reads
  (patched by an earlier apply); skipping it reported success while the
  shared jar stayed patched and remove dropped the record.
- A Gradle version dir holding only some of a leaf record's files is an
  install: apply patches the held files and fails the missing ones as not
  found (as on ~/.m2), and vex keeps the copy so it withholds.
- mismatch_blob_gaps expands Gradle version dirs into their hash dirs, so a
  drifted Gradle copy queues the afterHash blob the Warn policy needs.
- New gradle_m2_may_be_unconsumed warning when a Gradle-only build reading
  mavenLocal() has only the ~/.m2 copy patched.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: mikolalysenko

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -1690,13 +1690,18 @@ never filters.
 `apply` writes every copy a build consumes: each `~/.m2` version directory the build
 reads and each Gradle hash directory that holds the record's files. A Gradle version
 directory holding none of the record's files is not an install of it
-(`package_not_installed`). A record keyed by jar members (`<a>-<v>.jar/<member>`,
+(`package_not_installed`). One holding only some of them is: the held files are
+patched and the missing ones fail that copy as not found, as on `~/.m2` (the build
+still loads the held jar). A record keyed by jar members (`<a>-<v>.jar/<member>`,
 #264) swaps the whole jar for the patch service's build of it, in one transaction
 across every consumed copy: one download, one backup per distinct original under
 `.socket/jvm-originals/`, and a failed write puts every copy already swapped back.
-`rollback` restores only copies `apply` writes (never the read-only cache, never a
-`~/.m2` copy a Gradle-only build does not read), from the backup, else, online and
-for a Gradle copy only, from an upstream download that hashes to the copy's hash
+`rollback` (and `remove`) restores every writable copy that still holds the record's
+patched bytes: never the read-only cache, but also a `~/.m2` copy a Gradle-only build
+no longer reads (an earlier apply wrote it while the build declared `mavenLocal()`,
+or before v5.0 gated `~/.m2`; leaving it would strand the shared jar patched once
+`remove` drops the record). It restores from the backup, else, online and for a
+Gradle copy only, from an upstream download that hashes to the copy's hash
 directory.
 
 Run-level `warnings[]` codes (a refusal is also a `failed` event whose `error`
@@ -1706,6 +1711,7 @@ starts with the code):
 |---|---|---|
 | `gradle_verification_metadata_present` | refused, exit 1 | `gradle/verification-metadata.xml` exists; rewritten cache bytes would fail (or, with key-only trust, slip past) Gradle's dependency verification. Nothing is written; use `--mode vendored` or `--mode hosted`. |
 | `gradle_build_ignores_m2` | refused, exit 1 | The only installed copy is in `~/.m2`, which this Gradle-only build never reads. Nothing is patched; build once so Gradle caches it, then apply again. |
+| `gradle_m2_may_be_unconsumed` | warning | A Gradle-only build that declares `mavenLocal()` (or may) has no Gradle cache copy, so only the `~/.m2` copy was patched. Gradle takes a module from the first declared repository that has it: with another repository before `mavenLocal()`, the next build downloads the unpatched jar. Run the build once and apply again. |
 | `gradle_ro_cache_shadows` | exit 1 | The read-only cache holds a copy that is never written and that Gradle may read first. Writable copies are still patched. |
 | `gradle_copy_unexpected_bytes` | refused, exit 1 | A hash directory's file is the pristine download (its sha1 names the directory) but neither side of the record, or a hash directory holds a variant's files whose bytes no variant was made for. That copy is left unpatched and the run fails (changed in v5.0: it used to only warn), since the build still loads it. |
 | `gradle_transform_copy_stale` | that copy fails | After the write, Gradle still holds a copy derived from the pristine jar (`caches/transforms-*`, `caches/jars-*`, instrumented jars). Run `gradle --stop`, delete those directories, apply again. |
@@ -1844,7 +1850,8 @@ CLI.
 `vex` re-hashes every copy a build consumes (`~/.m2` copies the build reads, every
 Gradle hash directory holding the record's files, and the suffixed copies of a
 hosted pin) and attests only when all of them carry the patch. A Gradle version
-directory that holds none of the record's files is ignored. A derived copy
+directory that holds none of the record's files is ignored; one that holds only some
+of them is judged, and its missing files withhold the statement. A derived copy
 (`caches/transforms-*`, `caches/jars-*`, instrumented jars) proven to come from the
 pristine jar, or a same-named one that is older than the patched jar and does not
 match it, withholds the statement:

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

@@ -209,10 +209,13 @@ fn format_mismatch_fetch_result(downloaded: usize, needed: usize) -> String {
 /// mismatched files still need their afterHash blobs. The variant gate
 /// mirrors the apply loop's representative check PER COPY for gem and
 /// PyPI (which patch every copy, and two envs can hold different wheels
-/// of one release), and against the FIRST copy otherwise (Maven's
-/// Gradle copies are version dirs whose files sit in hash dirs, gated per
-/// hash dir by `apply_maven_base`): a variant's files are probed only on
-/// the copies it is attempted on.
+/// of one release), and against the FIRST copy otherwise: a variant's
+/// files are probed only on the copies it is attempted on. Maven's Gradle
+/// copies are version dirs whose files sit in hash dirs, so each one is
+/// first expanded into the hash dirs holding the record's files (as
+/// `apply_maven_base` does) and gated and probed per hash dir; probing the
+/// version dir itself would only ever find nothing, and a drifted Gradle
+/// copy would never queue the afterHash blob its write needs.
 ///
 /// Only a mismatched file whose afterHash blob is NOT staged can queue a
 /// fetch, so the probe first decides that with metadata probes alone and
@@ -265,21 +268,40 @@ async fn mismatch_blob_gaps(
                 || records
                     .first()
                     .is_some_and(|(key, _)| key.as_str() != stripped));
-        // The copies the apply loop gates per copy: gem and PyPI patch
-        // every copy, each against its own representative check; the
-        // rest gate on the first.
-        let gate_copies: &[PathBuf] = if matches!(
-            Ecosystem::from_purl(purl),
-            Some(Ecosystem::Gem | Ecosystem::Pypi)
-        ) {
-            pkg_paths.as_slice()
-        } else {
-            std::slice::from_ref(first_path)
-        };
+        let maven = Ecosystem::from_purl(purl) == Some(Ecosystem::Maven);
         for (_, record) in records {
             if !can_queue(record) {
                 continue;
             }
+            // Maven: every Gradle version dir expanded into the hash dirs
+            // holding the record's files.
+            let expanded: Vec<PathBuf> = if maven {
+                pkg_paths
+                    .iter()
+                    .flat_map(|p| {
+                        socket_patch_core::crawlers::gradle_cache::installed_copies(
+                            p,
+                            &record.files,
+                        )
+                        .into_iter()
+                        .map(|(dir, _)| dir)
+                    })
+                    .collect()
+            } else {
+                Vec::new()
+            };
+            let pkg_paths: &[PathBuf] = if maven { &expanded } else { pkg_paths };
+            // The copies the apply loop gates per copy: gem and PyPI patch
+            // every copy, each against its own representative check, and
+            // Maven each hash dir; the rest gate on the first.
+            let gate_copies: &[PathBuf] = if matches!(
+                Ecosystem::from_purl(purl),
+                Some(Ecosystem::Gem | Ecosystem::Pypi | Ecosystem::Maven)
+            ) {
+                pkg_paths
+            } else {
+                std::slice::from_ref(first_path)
+            };
             // Copies this variant is attempted on: a copy whose installed
             // distribution is another variant (two envs can hold different
             // wheels of one release) is skipped there by the apply loop.
@@ -2527,6 +2549,35 @@ async fn apply_maven_base(m: &MavenBase<'_>) -> MavenApplied {
         return out;
     }
 
+    // A Gradle-only build that reads `~/.m2` (mavenLocal() declared or
+    // undetermined) but has no Gradle cache copy: the m2 copy is patched,
+    // yet Gradle takes a module from the FIRST declared repository that
+    // has it, so when another repository comes before mavenLocal() the
+    // next build downloads the pristine jar instead. Gradle never caches
+    // a mavenLocal() artifact in files-2.1, so this is also exactly what a
+    // build reading the module from mavenLocal() looks like: warn, not
+    // refuse. `vex` re-hashes the Gradle cache copy that build makes.
+    if matches!(
+        m.scope.gate,
+        Some(socket_patch_core::crawlers::maven_crawler::M2Gate::Declared(_))
+            | Some(socket_patch_core::crawlers::maven_crawler::M2Gate::Undetermined(_))
+    ) && copies.consumed.iter().all(|c| !is_gradle_version_dir(c))
+    {
+        out.warn(
+            "gradle_m2_may_be_unconsumed",
+            format!(
+                "{}: the only patched copy is in the Maven local repository ({}). This Gradle                  build reads it only when no repository declared before mavenLocal() has the                  module; otherwise its next build downloads the unpatched jar. Run the build                  once and apply again so the Gradle cache copy is patched too.",
+                normalize_purl(m.base_purl),
+                copies
+                    .consumed
+                    .iter()
+                    .map(|p| p.display().to_string())
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            ),
+        );
+    }
+
     let multi = variants.len() > 1 || variants.first().is_some_and(|v| **v != m.base_purl);
     let gate_variants = !args.force && multi;
     let mut attempted = false;
@@ -2589,22 +2640,33 @@ async fn apply_maven_base(m: &MavenBase<'_>) -> MavenApplied {
 
         for copy in &copies.consumed {
             // Leaf record: the hash dirs holding its files (the copy itself
-            // for `~/.m2`). A key no hash dir holds means this Gradle copy
-            // does not hold the variant.
-            let targets = if is_gradle_version_dir(copy) {
+            // for `~/.m2`). A Gradle copy holding NONE of the record's
+            // files is not an install of it. One holding only some of them
+            // is: its held files are patched, and the keys no hash dir
+            // holds are applied against the version dir, where they are
+            // not found and fail the copy as they would on `~/.m2` (the
+            // build still loads the held jar, so a silent skip would leave
+            // it unpatched behind a clean exit).
+            let (targets, absent) = if is_gradle_version_dir(copy) {
                 let detailed = gradle_cache::installed_copies_detailed(copy, &patch.files);
-                if !detailed.missing.is_empty() {
+                if detailed.targets.is_empty() {
                     continue;
                 }
                 for (dir, _) in &detailed.targets {
                     held.entry(dir.clone())
                         .or_default()
                         .push((*variant).clone());
                 }
-                detailed.targets
+                let absent: HashMap<String, PatchFileInfo> = detailed
+                    .missing
+                    .iter()
+                    .filter_map(|k| patch.files.get(k).map(|info| (k.clone(), info.clone())))
+                    .collect();
+                (detailed.targets, absent)
             } else {
-                vec![(copy.clone(), patch.files.clone())]
+                (vec![(copy.clone(), patch.files.clone())], HashMap::new())
             };
+            let mut copy_attempted = false;
             for (dir, files) in targets {
                 if gate_variants {
                     let status = match representative_file(&files) {
@@ -2619,6 +2681,7 @@ async fn apply_maven_base(m: &MavenBase<'_>) -> MavenApplied {
                 }
                 hit.insert(dir.clone());
                 out.matched.push((*variant).clone());
+                copy_attempted = true;
                 if let Some(detail) = unexpected_gradle_bytes(&dir, &files).await {
                     out.refuse(variant, &dir, "gradle_copy_unexpected_bytes", detail);
                     continue;
@@ -2639,6 +2702,24 @@ async fn apply_maven_base(m: &MavenBase<'_>) -> MavenApplied {
                 }
                 out.record(args, result);
             }
+            // The record's keys this Gradle copy lacks, once the variant
+            // was attempted on its held files: not found there (a failure
+            // under the default and strict policies, a skip under
+            // `--force`), as on a `~/.m2` copy missing them.
+            if copy_attempted && !absent.is_empty() {
+                attempted = true;
+                let result = apply_package_patch(
+                    variant,
+                    copy,
+                    &absent,
+                    m.sources,
+                    Some(&patch.uuid),
+                    args.common.dry_run,
+                    m.policy,
+                )
+                .await;
+                out.record(args, result);
+            }
         }
     }
     // A Gradle hash dir that holds a variant's files but whose bytes no
@@ -3336,6 +3417,43 @@ mod tests {
         );
     }
 
+    /// #646 review: a Gradle copy is a `files-2.1` version dir whose files
+    /// sit one level down in `<sha1>/` hash dirs. A drifted jar there (not
+    /// pristine, not the record's beforeHash) must queue its afterHash
+    /// blob as a drifted `~/.m2` copy does: the default Warn policy
+    /// overwrites it with the full blob.
+    #[tokio::test]
+    async fn mismatch_blob_gaps_probes_gradle_hash_dirs() {
+        let dir = tempfile::tempdir().unwrap();
+        let version = dir
+            .path()
+            .join(".gradle/caches/modules-2/files-2.1/com.example/victim/1.0");
+        let hash = version.join("0123456789abcdef0123456789abcdef01234567");
+        tokio::fs::create_dir_all(&hash).await.unwrap();
+        tokio::fs::write(hash.join("victim-1.0.jar"), b"older patch bytes")
+            .await
+            .unwrap();
+        let blobs = dir.path().join("blobs");
+        tokio::fs::create_dir_all(&blobs).await.unwrap();
+        let mut files = HashMap::new();
+        files.insert(
+            "package/victim-1.0.jar".to_string(),
+            PatchFileInfo {
+                before_hash: "4".repeat(64),
+                after_hash: "5".repeat(64),
+            },
+        );
+        let manifest = manifest_with_record("pkg:maven/com.example/victim@1.0", files);
+        let mut all_packages = HashMap::new();
+        all_packages.insert(
+            "pkg:maven/com.example/victim@1.0".to_string(),
+            vec![version.clone()],
+        );
+        let needed =
+            mismatch_blob_gaps(&manifest, &all_packages, &HashSet::new(), &blobs, false).await;
+        assert_eq!(needed, HashSet::from(["5".repeat(64)]));
+    }
+
     /// A QUALIFIED singleton (`?platform=`…) keeps the
     /// installed-distribution gate — it names one specific distribution,
     /// and the apply loop skips it when the representative file

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

@@ -2296,11 +2296,17 @@ pub(crate) async fn rollback_patches_inner(
             .as_ref()
             .filter(|_| Ecosystem::from_purl(purl) == Some(Ecosystem::Maven))
         {
-            // Only the copies apply writes (`JvmScope::split`'s consumed
-            // ones): the read-only cache is never written, and a `~/.m2`
-            // copy this Gradle-only build never reads belongs to some
-            // other build — restoring it would unpatch that build.
-            for pkg_path in &scope.split(pkg_paths).consumed {
+            // Every writable copy: the read-only cache is never written,
+            // but a `~/.m2` copy this Gradle-only build no longer reads
+            // (`m2_ignored`) is still restored. An earlier apply wrote it
+            // (before the gate existed, or while `mavenLocal()` was
+            // declared); skipping it would leave the shared jar patched
+            // with no record to restore it from once `remove` drops the
+            // entry. Only bytes that verify as this record's afterHash
+            // are ever put back, and a Maven build that wants the patch
+            // re-applies it from its own manifest.
+            let copies = scope.split(pkg_paths);
+            for pkg_path in copies.consumed.iter().chain(&copies.m2_ignored) {
                 let key = (strip_purl_qualifiers(purl).to_string(), pkg_path.clone());
                 match maven_groups.iter_mut().find(|(k, _)| *k == key) {
                     Some((_, purls)) => purls.push(purl),

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

@@ -811,7 +811,9 @@ async fn generate_vex(
 /// declared or undetermined keeps it), each Gradle cache and the read-only
 /// cache, all re-hashed at VEX time. A Gradle version dir holding none of
 /// the record's files (a pom-only entry, another classifier) is not an
-/// install of it and is dropped, as apply does.
+/// install of it and is dropped, as apply does. One holding only some of
+/// them is kept: the keys it lacks verify as not found, so the statement
+/// is withheld while the build loads the held (unpatched) jar.
 async fn vex_copy_sets(
     common: &GlobalArgs,
     manifest: &PatchManifest,
@@ -830,10 +832,9 @@ async fn vex_copy_sets(
         }
         match jvm_jar::classify(purl, &record.files) {
             RecordShape::Members { jar_leaf } => !jvm_jar::jar_copies(path, &jar_leaf).is_empty(),
-            RecordShape::Leaf => {
-                let detailed = installed_copies_detailed(path, &record.files);
-                detailed.missing.is_empty() && !detailed.targets.is_empty()
-            }
+            RecordShape::Leaf => !installed_copies_detailed(path, &record.files)
+                .targets
+                .is_empty(),
         }
     };
     let maven = copies.keys().any(|p| p.starts_with("pkg:maven/"));

crates/socket-patch-cli/tests/e2e_redirect_gradle_build.rs

@@ -824,8 +824,8 @@ fn gradle_hosted_selector_port_matches_golden_tables() {
 #[ignore = "real Gradle; run with --ignored"]
 fn gradle_hosted_selector_golden_tables_match_real_gradle() {
     use socket_patch_core::gradle::selector::{
-        admits_for, gradle_version_cmp_for, parse_selector, GOLDEN_ADMITS,
-        GOLDEN_ADMITS_BY_MAJOR, GOLDEN_ORDERING, GOLDEN_ORDERING_BY_MAJOR,
+        admits_for, gradle_version_cmp_for, parse_selector, GOLDEN_ADMITS, GOLDEN_ADMITS_BY_MAJOR,
+        GOLDEN_ORDERING, GOLDEN_ORDERING_BY_MAJOR,
     };
     let groovy = |s: &str| format!("'{}'", s.replace('\\', "\\\\").replace('\'', "\\'"));
     let mut ords: Vec<(&str, &str)> = GOLDEN_ORDERING.iter().map(|(a, b, _)| (*a, *b)).collect();
@@ -865,7 +865,10 @@ for (r in adm) {{
     let Some(c) = cell(
         Dsl::Groovy,
         &[
-            ("settings.gradle".into(), "rootProject.name = 'probe'\n".into()),
+            (
+                "settings.gradle".into(),
+                "rootProject.name = 'probe'\n".into(),
+            ),
             ("build.gradle".into(), probe),
         ],
     ) else {