Vendored re-runs outside the npm family exit 1 while a superseding patch is still building, instead of keeping the older vendored patch #1235

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

Kind: bug (inconsistent logic across vendored backends). Source: new finding; register E94. It is the #954 pattern for the other ecosystems, which #1008 lists under "Known residuals".

Problem

#1008 fixed #954 for the npm family only. When a package is already vendored at an older patch and the newer (superseding) patch has no prebuilt artifact yet (pending_build) or at all (build_failed, not_found, withdrawn), the vendor loop is meant to keep the older patch and report a benign skipped event (exit 0), the way hosted mode keeps its pin.

That rule is decided in two places, and only the npm backends' path reaches it:

• ServicePolicy::unserved only carries the "not served (yet)" code under ServiceTerminal::Failure. Under ServiceTerminal::Refused it maps both statuses to the generic vendor_prebuilt_required refusal:

  ServiceTerminal::Refused => self.hard("vendor_prebuilt_required", detail),
  ServiceTerminal::Failure(purl) => { /* failed Done + VENDOR_PREBUILT_PENDING / _UNAVAILABLE warning */ }

• ServiceTerminal::Failure is used only by npm_common.rs#L424 and npm_dir.rs#L871. Every other backend uses Refused: composer_lock.rs#L687, golang.rs#L483, gem.rs#L976, cargo.rs#L301, pypi.rs#L2571, and Maven/NuGet through service_archive_copy.``
• In the CLI, keep_older_vendored_patch only recognizes a failed VendorOutcome::Done carrying that warning, and refusal_is_benign does not include vendor_prebuilt_required. So a Refused outcome from any non-npm backend is a failure.
• The contract row and the scan --mode vendored paragraph at #L162 scope the skip to "npm family". So the gap is documented, but nothing about the rule is npm-specific: the older vendoring is equally in force for every ecosystem.

Proof (CLI run, executed twice on f3c6313). A throwaway test in tests/e2e_vendor_composer_crlf.rs vendored pkg:composer/psr/log@3.0.2 at patch A (exit 0), moved the manifest record to patch B, mocked the patch service to answer pending_build (then build_failed) for B, and re-ran vendor. Both runs printed:

status=pending_build exit=1 summary={... "skipped":0,"failed":1 ...} events=[{"action":"failed","purl":"pkg:composer/psr/log@3.0.2","errorCode":"vendor_prebuilt_required","error":"prebuilt dist zip is still building"}]
lock_unchanged=true
status=build_failed exit=1 ... "errorCode":"vendor_prebuilt_required","error":"prebuilt dist zip unavailable: build_failed"
lock_unchanged=true

The older wiring is untouched (lock_unchanged=true), so the project is still patched, yet the run fails. The npm equivalent, superseding_patch_without_a_served_artifact_keeps_the_vendored_one,`` passes with exit 0 and a skipped `vendor_prebuilt_pending` event. The test was reverted.

Symptoms

• Vendored npm re-scan exits 1 ("Failed to vendor", "1 failed") on every run while a superseding patch's artifact is pending_build / build_failed / not_found, although the vendored older patch is intact; hosted skips the same upgrade with exit 0 #954 (npm, fixed by Fix open npm issues #1008) is the same defect; no open issue covers the other ecosystems.

Impact: a scan --mode vendored / vendor job in CI fails on every run for Composer, Cargo, Go, RubyGems, PyPI (all flavors), Maven, Gradle/sbt and NuGet projects from the moment a superseding patch is published until the service builds it, or forever when it is build_failed/not_found. Priority similar to #954 (p2).

Proposed change

Decide "not served (yet)" once, in service_fetch, for every backend:

• Make ServicePolicy::unserved emit the unserved code under both terminals: for Refused, return Refused { code: VENDOR_PREBUILT_PENDING | VENDOR_PREBUILT_UNAVAILABLE, detail } instead of vendor_prebuilt_required (or keep vendor_prebuilt_required as the code and carry the unserved code alongside; pick whichever keeps the first-vendor failure message stable).
• Make keep_older_vendored_patch recognize the unserved code on a Refused outcome as well as on a failed Done, keeping the same vendor_entry_live check. A first vendor with no older patch still fails.
• Delete the npm-only special case: with both terminals carrying the code, the Failure/Refused split in unserved collapses to one arm. Drop "npm family" from the two contract passages and the VENDOR_PREBUILT_* doc comments in vendor/mod.rs#L625-L635.

Size and scope

vendor/service_fetch.rs, commands/vendor.rs, vendor/mod.rs doc comments, CLI_CONTRACT.md; under ~80 production lines. Backends that call settle need no change. Out of scope: the --vendor-source auto fallback that ServicePolicy::new ignores (#782, E28), and request/transport failures, which stay failures.

Acceptance criteria

• For Composer, Cargo, Go, gem, PyPI (requirements/uv at least), Maven and NuGet: vendored at patch A, re-run with patch B pending_build → exit 0, one skipped event with vendor_prebuilt_pending naming both uuids, lock/ledger/artifact byte-identical. Same with build_failed/not_found → vendor_prebuilt_unavailable.
• The unwired-older case still fails, as in superseding_patch_without_a_served_artifact_fails_when_the_old_one_is_unwired, for one non-npm backend.
• A first vendor (no older patch) with pending_build still fails, with its existing message.
• Existing service_pending_* backend tests and the npm Vendored npm re-scan exits 1 ("Failed to vendor", "1 failed") on every run while a superseding patch's artifact is pending_build / build_failed / not_found, although the vendored older patch is intact; hosted skips the same upgrade with exit 0 #954 tests stay green; update the ones that assert vendor_prebuilt_required for pending/unavailable only if the chosen shape changes that code.

Dependencies

None blocking. Touches files that #1009 and #1036 also edit (commands/vendor.rs region differs); rebase as needed.