Decide vendored-entry liveness through one discovery verdict

[Mikola Lysenko (mikolalysenko)]

Problem

Architecture audit §3.B asks one question: is this vendored entry still live? Four separate oracles answer it today: vendor_entry_live, dispatch_in_use_one, scan_vendor_references and the JVM entry_wired. They disagree.

• B19. dispatch_in_use_one serves the prune GC, scan's ledger supplement and the vendor --check remedy. It only had probes for npm, cargo and the pypi requirements flavor. Every gem, golang, composer, nuget, maven/jvm, uv, poetry, pdm, pipenv and pylock entry answered None and was kept forever:
  • scan --prune could never reclaim one;
  • scan's supplement recreated it as a discovered package and never emitted vendor_ledger_entry_unwired;
  • meanwhile vendor --check and vex already called it dead.
• B62. vendor --check reported orphaned JVM trees (maven2, gradle, coursier and their indexes, plus the generated sbt file) only when the whole ledger was empty.
• B61. Legacy Maven and NuGet treated a raw substring as "already wired". A commented-out <repository> or <packageSources> source took the in-sync hot path, so the build resolved the unpatched package.

Change

• Core: one GC / supplement in-use verdict. Discovery::vendor_entry_in_use(root, entry) -> Option<bool> sits next to vendor_entry_live and is derived from the same discovery:

  • Some(true) in any of these cases:
    • the entry is live;
    • another lock contests its wiring;
    • a file that mentions its uuid had wiring dropped as DIAG_REF_UNATTRIBUTABLE;
    • cargo withheld a relock-pending [patch].
  • Some(false): discovery read and parsed an install-deciding lockfile of the entry's ecosystem, and nothing above holds.
  • None: discovery read no such lockfile, or one of its files could not be read or parsed.
  • JVM entries answer from their own layout (entry_references).

• An attestation drop is not a liveness verdict. Attestation fails closed by dropping a ref it cannot tie to the one copy that installs. Examples:

  • an unpatched copy in the same lock;
  • npm's legacy dependencies mirror;
  • a non-registry nested copy;
  • vlt's other instances or bundled copies;
  • a yarn git block;
  • a version-less Go replace.

  The GC has to fail safe, by keeping the entry. One rule covers every extractor: keep the entry whenever a file that mentions the uuid carries an unattributable diagnostic. This is deliberately file-grained, so it errs toward keeping. Mentions rejected as DIAG_REF_INVALID are shapes the package manager never installs from, and they still read as unused. Examples: stale bun.lockb pool strings, a vlt edge spec, cargo's leftover [patch] after a hosted takeover.

• New discovery evidence:

  • Discovery::read: every guarded read, tagged with the reading extractor's ecosystem. A manifest alone (Cargo.toml, pyproject.toml, hatch.toml) is not a lock, so it decides nothing.
  • Discovery::withheld: now only cargo's relock-pending [patch], which cargo reports as invalid rather than unattributable. The earlier npm and bun pushes were removed because the diagnostic rule subsumes them.

• Routing.

  • run_vendor_gc pass (b) takes every verdict from one discovery snapshot taken before it reverts anything. Before, each probe re-read the files after the previous revert. Reverting one entry never rewires another, so the snapshot only removes ordering effects.
  • vendored_ledger_supplement reads the run's ProjectContext discovery (scan and get pass their context).
  • The vendor --check remedy uses the same verdict.

• B62. The JVM orphan check fires whenever no ledger entry is a JVM entry:

  • empty ledger: refuses, as before;
  • otherwise: records a failed vendor_ledger_missing artifact event, whose path names the orphan.

  The path list is now one jvm::apply::LEDGER_OWNED_PATHS.

• B61. Each backend now uses the comment-masking reader its forward writer already uses: find_wireable_anchor for the pom, parse_config_source_keys(blank_comments(..)) for nuget.config.

Duplicates deleted

The GC, supplement and vendor --check remedy oracles go from 5 to 1. Deleted:

• commands::vendor::dispatch_in_use_one
• vendor::npm_flavor::vendored_entry_in_use
• vendor::cargo::vendored_entry_in_use
• vendor::pypi::vendored_entry_in_use
• vendor::pypi_requirements::requirements_entry_in_use

Kept on purpose (see Deferred):

• the pnpm, pnpm-legacy and vlt structural probes (pnpm_entry_in_use, pnpm_legacy_entry_in_use, vlt_entry_in_use). Their revert guards still use them. If one disagrees with the GC verdict, the guard refuses and the entry lands in GC failed, so nothing is reverted unsafely.
• the two JVM checks. entry_wired (vex, vendor --check) is strict attestation: every half is wired and the Gradle script is intact. entry_references (GC, supplement) asks whether anything still references the tree. Wired implies referenced, so the GC never reverts an entry that vex attests.
• scan_vendor_references, the raw-text check used by orphan sweeps, repair, rollback and vendor --check's unknown-wiring scan.

JVM orphan path lists: the CLI inline list and coursier_tree::ORPHAN_PATHS become LEDGER_OWNED_PATHS, so 2 lists become 1.

Behaviour changes

• Newly prunable by scan --prune when an install-deciding lock no longer mentions them: gem, golang, composer, nuget, legacy maven, JVM, and the uv, poetry, pdm, pipenv and pylock pypi flavors.
• npm. An unknown or mismatched npm flavor, or a v9 lock under a pnpm-legacy entry, used to read as None. Now a lock that resolves nothing for the entry reads as unused.
• Still undecidable. Lock-less pyproject projects (hatch, or any flavor before its first lock) keep answering None, and the entry is kept. This is now pinned by a test. Earlier wording that listed hatch among the B19 fixes was wrong for the lock-less case.
• None of this needs a maintainer decision (Decide: one shape for the --json top-level error (scan and get emit both a string and a {code, message} object) #704, Decide: warn on and then remove scan --apply/--vendor, and whether --vex stays embedded #966, Decide: give SOCKET_FORCE per-command names so forcing a self-update doesn't also force apply and vendor #615, Decide: where patch API calls go when a token is set but the org slug can't be resolved #648, C34, E44-E47 are untouched).

Testing

Run locally on macOS. Every cargo command went through heavy-job.sh with CARGO_INCREMENTAL=0 and -j4.

• cargo test -p socket-patch-core --lib -- vex:: vendor::: 2987 passed, plus the new pyproject test.

• cargo test -p socket-patch-cli:

  target	passed
  --lib	871
  vendor_jvm_cli	30
  covgap_commands_scan_mod	53
  covgap_commands_vendor	54
  scan	118
  repair	126
  rollback	38
  vendor	91
  e2e_vex_lockfile	323
  in_process_vendor	121
  scan_vendor_e2e	37
  scan_vendor_requirements_unwired	3
  vendor_eject	8

  All green on head.

• cargo clippy -p socket-patch-core -p socket-patch-cli --all-targets: no diagnostics in any file this PR touches. Toolchain 1.93.1 still flags pre-existing lints elsewhere (jvm_jar.rs, python_crawler.rs, redirect/mod.rs, test helpers), and those are on main too.

Keep-side coverage for every newly prunable ecosystem. Each successful, non-dry-run vendor through the vendor::test_support wrappers now asserts that the GC verdict on the entry it just wrote is not Some(false). In vendor::, that ran against real backend output for every ecosystem and flavor, with every verdict Some(true) (count per ecosystem/flavor):

ecosystem / flavor	runs
cargo	70
composer	45
gem	76
golang	23
maven	43
nuget	42
jvm	1
npm (package-lock, bun, pnpm, pnpm-legacy, vlt, yarn-berry, yarn-classic)	535
pypi requirements	44
pypi uv	13
pypi poetry	14
pypi pdm	23
pypi pipenv	11
pypi hatch	3
pypi python-lock	3

Regression tests, failing first.

• vendor::npm_flavor::tests::unattributable_wiring_stays_in_use covers the v2 legacy mirror, a v3 nested git copy and a vlt other instance. With the new rule disabled it fails: left: Some(false), right: Some(true).

• gc_tests::vendor_gc_keeps_an_entry_whose_wiring_is_only_unattributable: run_vendor_gc keeps a legacy-mirror entry, dry and wet. It fails with the rule disabled.

• vex::discover::tests::lockless_pyproject_entries_stay_undecidable pins None.

• Run on the merge-base c5be5d1 (test hunks only, in a throwaway worktree), these three failed as expected:

  • vendor_gc_reclaims_unused_composer_entry_and_keeps_a_wired_one (B19): unused_reverted was [].
  • ledger_supplement_reports_a_bumped_composer_entry_unwired (B19): the entry was resurrected into packages.
  • check_reports_jvm_trees_without_a_jvm_entry_beside_other_entries (B62): no JVM orphan event; only the npm entry's own failure.

  The B62 test now also asserts that the event's path is an existing LEDGER_OWNED_PATHS member.

• commented_out_repository_is_not_wired and commented_out_source_is_not_wired (B61) fail with the old substring checks restored.

Linux and docker suites are left to CI.

Deferred

• scan_vendor_references (orphan sweeps, repair, rollback's ledger-less gate, vendor --check's unknown-wiring scan) is still a separate raw-text scan. Scan every vendored-write file for vendored references (#832, #958) #1015 (Vendored-reference scan never sees NuGet or Maven wiring, so the orphan sweep deletes a still-wired unit #832, Vendored-reference scan never reads hatch.toml, so the orphan sweep deletes a wheel that a Hatch environment still installs #958) is extending it now. Retiring it into discovery is the follow-up once Scan every vendored-write file for vendored references (#832, #958) #1015 merges. This PR touches neither repair.rs nor registry.rs.
• Route the pnpm, pnpm-legacy and vlt revert guards through Discovery::vendor_entry_in_use. The pnpm part needs coordination with Fix 15 open pnpm issues across hosted, vendored and agent modes #1007's owner.
• Derive the JVM attestation check (entry_wired) from the reference check plus a layout-intact check, together with a single jvm::layout module and per-GAV JVM orphan detection (a tree dir with no matching JVM entry while other JVM entries exist).
• Lock-less pyproject pypi entries (hatch, or before the first lock) stay undecidable, so they are kept.
• withheld and the unattributable rule match on uuid and mode. A uuid names one patch, so one package version, so matching on base_purl too would add nothing today.
• NuGet hosted and vendored still share the socket-patch-<uuid> key. Deciding "ours" by the source value (NuGet scan --mode vendored over a hosted pin skips the takeover (purl case mismatch), keeps the hosted feed wired, writes no vendor ledger and still reports success #553) is not addressed here.
• ecosystem_in_scope does not map "jvm" to maven (a separate audit finding).

🤖 Generated with Claude Code

---

Note

High Risk
Changes prune GC, vendor --check, and scan supplement behavior across all ecosystems; incorrect liveness could revert live patches or leave stale ledger entries.

Overview
Unifies vendored-ledger liveness behind Discovery::vendor_entry_in_use, replacing separate per-ecosystem probes (dispatch_in_use_one, npm/cargo/pypi vendored_entry_in_use) so scan --prune, the vendored ledger supplement, and vendor --check share one verdict.

Discovery now records which lockfiles were read (Discovery::read) and cargo relock-pending wiring (withheld), and treats unattributable attestation drops and contested locks as keep (fail-safe) rather than unused. The prune GC loads one discovery snapshot before reverting entries so half-pruned locks cannot skew later probes.

Behavior fixes: Composer and other previously unprobed ecosystems can be reclaimed when install-deciding locks no longer wire them; JVM orphan detection runs when the ledger has no JVM entry (not only when empty); Maven/NuGet commented-out repository/source blocks no longer count as wired for the in-sync vendor path.

Vendor test helpers assert a freshly vendored entry is never Some(false) for the GC verdict.

^{Reviewed by Cursor Bugbot for commit e9bd805. Configure here.}

---

Generated by Claude Code

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Gradle JVM prune may fail open
  • Created gradle::references_checked that returns Result<bool, String> and fails when files cannot be read, ensuring fail-closed behavior consistent with other JVM backends.
• ✅ Fixed: Empty-wiring JVM entries skip layout check
  • Modified is_jvm_entry to recognize empty-wiring maven-ecosystem entries with valid maven purls, preventing them from incorrectly falling through to generic maven discovery.

Or push these changes by commenting:

@cursor push 002ca36d71

Preview (002ca36d71)

diff --git a/crates/socket-patch-core/src/vendor/jvm/apply.rs b/crates/socket-patch-core/src/vendor/jvm/apply.rs
--- a/crates/socket-patch-core/src/vendor/jvm/apply.rs
+++ b/crates/socket-patch-core/src/vendor/jvm/apply.rs
@@ -36,13 +36,20 @@
 };
 
 /// Whether `entry` was written by this backend: it has wiring and every
-/// record is one of this backend's kinds.
+/// record is one of this backend's kinds, OR it's a maven-ecosystem entry
+/// with a valid maven purl (covers empty-wiring reconstructed entries).
 pub fn is_jvm_entry(entry: &VendorEntry) -> bool {
-    !entry.wiring.is_empty()
+    if !entry.wiring.is_empty()
         && entry
             .wiring
             .iter()
             .all(|w| KINDS.contains(&w.kind.as_str()))
+    {
+        return true;
+    }
+    // Empty-wiring entries (e.g., from repair/reconstruction) that are
+    // maven-ecosystem with valid maven purls should still be treated as JVM entries
+    entry.ecosystem == "maven" && parse_maven_purl(&entry.base_purl).is_some()
 }
 
 /// Offline inputs have not been authenticated by independent registry checksums.
@@ -827,7 +834,7 @@
     }
     let (maven, gradle) = sides(&entry.wiring);
     (maven && maven_reactor::wired_checked(&read, &c).unwrap_or(true))
-        || (gradle && gradle::references(&read, &c))
+        || (gradle && gradle::references_checked(&read, &c).unwrap_or(true))
 }
 
 /// The liveness proof `vex` needs: every half of the entry is wired, and

diff --git a/crates/socket-patch-core/src/vendor/jvm/gradle.rs b/crates/socket-patch-core/src/vendor/jvm/gradle.rs
--- a/crates/socket-patch-core/src/vendor/jvm/gradle.rs
+++ b/crates/socket-patch-core/src/vendor/jvm/gradle.rs
@@ -1197,6 +1197,42 @@
     indexed && applied
 }
 
+/// Checked variant of [`references`] that returns an error when files
+/// cannot be read, for fail-closed GC ([`crate::vex::discover::Discovery::vendor_entry_in_use`]).
+pub fn references_checked(read: ReadFn<'_>, c: &Coords<'_>) -> Result<bool, String> {
+    let gav = format!("{}:{}:{}", c.group_id, c.artifact_id, c.version);
+    let index_bytes = read(INDEX_REL).ok_or_else(|| format!("cannot read {}", INDEX_REL))?;
+    let index_text = String::from_utf8(index_bytes)
+        .map_err(|_| format!("{} is not valid UTF-8", INDEX_REL))?;
+    let rows = index_rows(&index_text)
+        .ok_or_else(|| format!("{} could not be parsed", INDEX_REL))?;
+    let indexed = rows.iter().any(|r| {
+        let cols: Vec<&str> = r.split('\t').collect();
+        cols.first() == Some(&gav.as_str()) && cols.get(3) == Some(&c.uuid)
+    });
+    
+    let wiring = WiringTarget::vendored();
+    let mut applied = false;
+    let mut settings_found = false;
+    for rel in ["settings.gradle", "settings.gradle.kts"] {
+        if let Some(bytes) = read(rel) {
+            settings_found = true;
+            let text = String::from_utf8(bytes)
+                .map_err(|_| format!("{} is not valid UTF-8", rel))?;
+            let dsl = dsl::dsl_of(rel).unwrap_or(Dsl::Groovy);
+            if has_apply_line(&text, dsl, &wiring, "") {
+                applied = true;
+                break;
+            }
+        }
+    }
+    if !settings_found {
+        return Err("cannot read settings.gradle or settings.gradle.kts".to_string());
+    }
+    
+    Ok(indexed && applied)
+}
+
 /// The liveness proof `vex` needs for this layout: `c` is
 /// [`references`]d, the script is ours (line endings aside), and a re-plan
 /// over the committed tree is refused nowhere and degraded nowhere.

_{You can send follow-ups to the cloud agent here.}

[Mikola Lysenko (mikolalysenko)]

bugbot run

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e9bd805. Configure here.}

[Mikola Lysenko (mikolalysenko)]

[agent] Ready for review at e9bd80572b5805aa639cc82e19e47447e9dd4d32.

• CI: required ci-ok green (22:53Z). 529 success / 6 skipped / 0 failing of 563 check runs; 28 non-required macOS/Windows legs still queued on the runner backlog.
• Bugbot reviewed e9bd80572b; no unresolved review threads.
• Mergeable, no conflicts. The branch is 8 commits behind main (no overlap reported by GitHub); the merge queue re-tests against main.
• Reviewer focus: vendored-entry liveness now comes from a single discovery verdict.

---

Generated by Claude Code