Vendor single-module Maven poms through the suffixed jvm planner and retire the legacy <repository> backend (#973)

[Mikola Lysenko (mikolalysenko)]

[agent] Implements the maintainer's decision on #973: every Maven root now vendors through the suffixed JVM planner, and the pre-v5 same-GAV <repository> backend is removed. Breaking v5 change. See the new "Vendored Maven" section in docs/migrating-to-v5.md.

Closes #973, closes #263, closes #274, closes #716. Refs #971, #622, #972.

What changes

• Routing (vendor/jvm/mod.rs): Detected::shape maps any root pom.xml without a Gradle build to Shape::MavenReactor. A single-module pom is a reactor of one. It gets the <version>-socket.<hex8> pin, the <dependencyManagement> pin, .mvn/maven.config, the socket-patch-vendor fallback repository and the .socket/vendor/maven2 tree, all in a jvm ledger entry. Shape::Other now means there is no pom, Gradle, sbt or scala-cli build. It is refused as vendor_jvm_shape_unsupported with reason no_build_file.
• Deleted from vendor/maven_repo.rs: about 600 production lines and their inline tests:
  • MavenPrelude/maven_prelude and vendor_maven_single;
  • materialise_and_write and acquire_upstream_pom;
  • artifact_in_sync and sidecar_matches;
  • build_repo_edit and its anchor helpers;
  • the comment-stripping declares_modules (Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716);
  • project_has_gradle and local_cache_shadow_warning;
  • the jvm_shape/legacy_mixed_root bridge.
• Kept, revert only: revert_maven_opts with revert_repo_record, repository_block and strip_empty_repositories. v4-era ledgers still unwind byte for byte through vendor --revert, remove, rollback and the hosted takeover.
• Legacy roots are refused, not migrated. If a root's ledger still holds a maven_pom_repository entry, Maven vendoring on it is refused whole as vendor_jvm_shape_unsupported with reason legacy_maven_root. Nothing is written, service_preflight plans no download for it, and jvm_gate_preflight keeps a hosted pin there. The remedy is socket-patch vendor --revert, then vendor again.
• sbt detection: a root pom wired by the planner now counts as "already wired by the Maven backend" even when it has no <modules>.
• fetch_registry_bytes is untouched (it belongs to Bound registry downloads by ApiTimeouts instead of a 60 s total deadline (#872) #876).

Things reviewers should know

• No Maven Wrapper means two warnings. Without .mvn/wrapper/maven-wrapper.properties, which covers most single-module projects, vendor reports vendor_jvm_degraded with maven_f_outside_root and maven_mirror_of_all. This is the planner's existing contract. It is pinned in tests and documented, and VEX is not withheld.
• A tampered jar is accepted on Maven 3.9.2+. On 3.9.2 and later, Maven reads the committed tree through maven.repo.local.tail, a local repository it does not checksum. A tampered jar left with its stale .sha1 is therefore built. Before 3.9.2 the fallback checksumPolicy=fail repository rejects it. Reactors already behave this way. The real-Maven capstone pins both behaviours, and VEX never attests a tampered tree. If maintainers want a build-time check here, that is a follow-up.
• 8-hex prefix collisions (existing limitation). Two patches of the same version whose uuids share their first 8 hex digits produce the same suffixed string. The planner's revert then cannot tell them apart and keeps the first entry as drifted. The shared ecosystem fixture used two such uuids, so Maven's second fixture uuid changed.
• The artifact-barrier crash test now runs nuget instead of maven. The JVM tree is written durably as it goes, so a Maven run gives that barrier nothing to sync.
• The branch is rebased onto origin/main c5be5d1. utils::digest::tests::production_digests_go_through_the_helpers failed before the rebase because its file list was stale; Fix main CI red on stale digest pending-list entries #1016 on main fixed that.

Docs updated

• docs/ecosystems.md, docs/usage.md, docs/maven-vendoring.md, docs/sbt-support.md, crates/socket-patch-cli/CLI_CONTRACT.md.
• New "Vendored Maven" section in docs/migrating-to-v5.md. It says a v5 single-module project is attested by vex only from the committed .socket/vendor/state.json.

Review findings fixed (ad4f7bc, now rebased)

• The CLI_CONTRACT VEX discovery row for vendored Maven now says it covers pre-v5 <repository> wiring only. A v5 pin is gated by its ledger entry.
• The migration guide now documents ledger-only VEX for v5 Maven vendoring.
• Renamed maven_vendor_command_wiring_reattests_without_manifest_or_ledger to maven_vendor_command_wiring_reattests_from_its_ledger_only, which matches what the test asserts.
• Not fixed, out of scope: the 8-hex pin collision is a general planner limitation (reactors and sbt have it too) and should get its own issue.

Tests

• After rebasing onto c5be5d1 (main had also touched maven_repo.rs and vendor/mod.rs), these were re-run: core vendor:: vex:: (2955 passed), and CLI vendor_jvm_cli, vendor_ledger_schema_e2e and e2e_vex_lockfile, all green.
• cargo test -p socket-patch-core --lib -- vendor:: vex::: 2943 passed. New:
  • a single-module plan, idempotent re-plan and byte-exact unplan (LF and CRLF);
  • legacy_maven_root refusal for a single and a mixed root, then revert and re-vendor;
  • the no_build_file refusal;
  • the Vendored Maven refuses a single-module EAR pom as a multi-module aggregator because two declares_modules disagree #716 commented-<modules> pom.
• cargo test -p socket-patch-cli --test vendor_jvm_cli --test contract_gradle_codes --test vendor_ledger_schema_e2e --test vendor_group_commit_e2e --test e2e_vex_lockfile --test e2e_vex_vendor --test e2e_vex --test in_process_vendor --test in_process_scan --test in_process_rollback_all_ecosystems --test ecosystem_dispatch_e2e --test maven_sidecar_cli --test e2e_vendored_production --test in_process_get_hosted_ecosystems: all green.
• e2e_vendor_maven_build (ignored, real Maven 3.9.16 + Maven Central) passes locally. The CI matrix legs are unchanged.
• docker_e2e_vendor_maven was rewritten for the new layout and compiles (--all-features). It was not run locally.
• cargo clippy --workspace --all-features --all-targets shows no new warnings in the touched files. The -D warnings failure in crawlers/python_crawler.rs on macOS also happens on main.

CHANGELOG.md is not touched; it is written at release time.

🤖 Generated with Claude Code

---

Note

High Risk
This is a breaking vendoring and attestation contract for Maven: legacy projects are hard-refused until revert, and builds depend on suffixed coordinates, .mvn config, and ledger-backed VEX rather than the old repository wiring.

Overview
Breaking v5 change: every Maven root (including single-module pom.xml) now vendors through the suffixed JVM planner—<version>-socket.<hex8>, .socket/vendor/maven2/, .mvn/maven.config, and the socket-patch-vendor fallback repository—instead of the retired pre-v5 same-GAV file:// .socket/vendor/maven/<uuid>/ + <repository> wiring.

Roots whose ledger still has maven_pom_repository are refused whole (legacy_maven_root) until vendor --revert and a fresh vendor; revert/remove paths for old ledgers stay. VEX for v5 Maven pins is ledger-only (no attribution from pom.xml + tree without state.json). Detection treats a lone pom as MavenReactor; Shape::Other / no_build_file applies only when there is no JVM build at the root.

Docs (CLI_CONTRACT, ecosystems, migrating-to-v5, maven-vendoring) and Maven e2e/docker tests are updated for the new layout, wrapper-less vendor_jvm_degraded warnings (maven_f_outside_root, maven_mirror_of_all), and removal of vendor_maven_local_cache_shadow.

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

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] CI status: fixed the real failures and rebased onto origin/main (head 2e0040f).

• e2e_vendor_maven_build on Maven 3.6.3 / 3.8.9: the planner wiring was fine. The tamper probe re-resolved against a local repository that the fresh-checkout step had already filled with the suffixed artifact, so old Maven used the cached copy and never re-checked the checksumPolicy=fail fallback repository. The probe now drops the cached suffixed version first, the same cold re-resolve the docker twin and the pre-Decide: vendor single-module Maven poms through the suffixed-version jvm planner and retire the same-GAV <repository> wiring #973 test do. Passes locally on Maven 3.6.3 and 3.9.16.
• test (windows-latest): tree_snapshot keyed files by the OS path, so removing .socket/vendor/state.json did nothing on Windows. Keys are now /-separated.
• lock-diff (vlt): a downstream symptom of the matrix cells that never got a runner. It is not a code failure.

The CI run for 2e0040f was cancelled by a repo-wide manual cancel at about 23:17Z that hit several branches. I did not re-run it. It needs a re-run once PR CI is back on.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

[agent] Merged main, CI green; ready for review.

---

Generated by Claude Code

[cursor]

Stale Bugbot comment from a previous run.

[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 0178c50. Configure here.}

[Mikola Lysenko (mikolalysenko)]

Burn-down agent: labeled Ready for review at 0178c50.

• CI: 427/427 non-skipped checks green (ci-ok success), 14 skipped
• Bugbot: reviewed 0178c50, no unresolved findings.
• Mergeable: yes, no conflicts with base.

---

Generated by Claude Code