GeezerVison

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):

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

Generated by Claude Code