Route JVM layout through one module and fix three JVM scope bugs

[Mikola Lysenko (mikolalysenko)]

Problem

Architecture audit §3.B / §3.F ("Maven repo path", "Root and JVM markers"): JVM layout facts were spelled in many places and had started to drift.

• About 13 production copies of the maven2 path construction (group.replace('.', "/") plus the artifact leaf), 4 copies of the socket-patch.vendor.json marker name, 2 coordinate validators in different modules, separate tree-root, orphan and captured-file lists in core and CLI, two copies of the tree-index row validator, and 4 JVM build-marker tables checked with 3 different stat rules (metadata, symlink_metadata, is_file).
• B65 (Agent-mode JVM crawl finds no Coursier cache for a scala-cli or sbt root that only SCALA_TOOL_MARKERS recognizes, because six marker lists disagree #1014, register E69): an sbt build whose only marker is project/build.properties (or a scala-cli build with only .scala-build/) got no JVM discovery at all. is_jvm_project returned early before the Scala-tool markers were consulted, which contradicts CLI_CONTRACT.
• B17: v5 JVM ledger entries are recorded as jvm, which is not an --ecosystems name. Under --ecosystems maven, every JVM entry was dropped from the vendor GC passes, from rollback's vendored leg and from repair's health loop.
• B18: maven_repo::service_preflight checked only the committed-tree hot path for JVM shapes. not_build_root, coordinate and ledger refusals, the sbt / scala-cli gate skips and empty patches all stop vendor_maven before it reaches the service, so a batched grant could name uuids the loop never fetched.

Change

A new vendor::jvm::layout module owns these facts, and every call site now goes through it:

• maven2 paths: group_path, version_dir, version_dir_path, file_name, artifact_path, registry_base (moved from maven_repo::maven_registry_base) and registry_url.
• Coordinates: is_path_safe (was maven_crawler::is_safe_maven_coordinate) and safe_coordinates (was jvm::safe_coordinates). Both grammars now sit in this one module, and the doc comment explains how they relate. They are not merged: the single-pom backend accepts coordinates the v5 writers refuse, and unifying them would change behavior (see Deferred).
• Committed trees: MAVEN2_TREE, GRADLE_TREE, COURSIER_TREE, VENDOR_TREES, ORPHAN_PATHS, CAPTURED_FILES, MARKER_FILE, tree_dir, and index_row (the shared Gradle / Coursier index row check).
• Ledger name: LEDGER_ECOSYSTEM and ledger_ecosystem() (jvm → maven). Revert dispatch, path::vendor_dir_symlink, redownload, hosted takeover and ecosystem_in_scope all use it. This fixes B17.
• Build markers:
  • BuildTool::markers() holds one table per tool.
  • marker_present applies one stat rule: the path exists, following symlinks.
  • has_build, is_jvm_build and is_scala_tool_build are the shared checks.
  • JVM_PROJECT_MARKERS is built from the same constants and is still basename-only for root detection.
  • is_jvm_project now uses is_jvm_build, which fixes B65.
• Gradle settings and scala-cli names: GRADLE_SETTINGS_FILES (Groovy, then Kotlin) and is_gradle_settings(rel) replace the two is_settings_file helpers, the settings arrays in gradle.rs and not_build_root, the Groovy/Kotlin pick for a new settings file and the CLI hosted matches!. SCALA_CLI_DIR replaces the .scala-build literals in sbt_evidence and scala_evidence.
• B18: the consolidation commit gathers the checks vendor_maven_jvm makes first into one jvm_prelude. The B18 commit makes service_preflight run that prelude too, and the preflight also applies not_build_root and the empty-patch no-op.
• The sbt reactor-wired probe now uses maven_reactor::BEGIN_MARKER / PIN_TAG instead of copying the literals.

Other behavior changes, all small:

• The single stat rule (metadata, which follows symlinks) changes two edge cases, and a layout test pins both:
  • A directory named like a build file now counts. Before, the Gradle and not_build_root checks used is_file, so a directory named build.gradle was not a Gradle build. Now it is one for the crawler, m2_gate, gradle_scan and not_build_root.
  • A dangling symlink at a marker no longer counts. Before, the Scala-tool gate used symlink_metadata, so a dangling .scala-build or project/build.properties symlink made the project a Scala-tool build. Now it does not.
• The eject snapshot now covers the maven2 and Gradle tree .gitattributes files, because it uses the shared captured-file list.
• The contract text now names project/build.properties and .scala-build/ as JVM-root markers.

Duplicates deleted (before → after)

What	Before	After
maven2 path construction (replace('.', "/"), production code)	14	1
local_repo_artifact_path / group_id_to_path helpers	3	0 (layout::artifact_path / group_path)
maven_registry_base + hand-built registry URLs	1 + 5	1 + registry_url
socket-patch.vendor.json constants / literals	4 + 2	1 (state's, re-exported)
Coordinate validators	2, in 2 modules	2, in 1 module (grammars unchanged)
Tree index row validators	2	1
Tree-root literals (.socket/vendor/maven2 / gradle / coursier)	9	3 constants
Orphan path lists (core + CLI)	2	1
Captured-file lists (core + group_commit)	2	1
JVM marker tables (JVM_PROJECT_MARKERS, SCALA_TOOL_MARKERS, GRADLE_MARKERS/SETTINGS, GRADLE_ROOT_FILES, jvm GRADLE_FILES, MILL/SCALA_CLI_MARKERS, project_has_gradle, not_build_root / sbt / buildSrc lists)	about 11	1 module
Gradle settings-file name checks (is_settings_file ×2, arrays ×2, CLI matches!, Groovy/Kotlin pick)	6	1 (GRADLE_SETTINGS_FILES / is_gradle_settings)
.scala-build literals (production)	2	0 (SCALA_CLI_DIR)
Build-marker stat rules	3	1, plus 2 deliberate exceptions (see below)

Two checks keep a different stat rule on purpose:

• scan/policy.rs::dir_markers keeps is_file. The root-marker report lists regular files, and it checks the JVM build files beside non-JVM manifests (package.json, Cargo.toml, ...) under the same rule. A comment there says so. As a result, a directory named build.gradle marks a Gradle build for the crawler but is not listed as a policy root marker.
• sbt_evidence keeps its regular-file check (see Deferred).

Testing

Failing-first: before the fixes, all four new or changed tests failed. With the fixes, they pass.

• vendor::maven_repo::tests::jvm_service_preflight_matches_what_the_backend_asks_for (B18)
• crawlers::maven_crawler::scala_cache_tests::local_scala_caches_only_for_scala_tool_projects (B65)
• crawlers::jvm_cache::tests::every_marker_makes_a_jvm_project (B65)
• commands::vendor::scope_and_hint_tests::jvm_ledger_entries_are_in_the_maven_scope (B17)

Commands run (macOS, all via the shared heavy-job limiter, CARGO_INCREMENTAL=0 -j4):

• cargo clippy -p socket-patch-core -p socket-patch-cli --all-features -- -D warnings -A unused_variables: clean. -A unused_variables only hides a macOS-only warning already on main, python_crawler.rs:2734 unix_default. CI runs on Linux.
• cargo test -p socket-patch-core --lib: 5581 passed, 1 failed. The failure is utils::digest::tests::production_digests_go_through_the_helpers, the B01 failure already on main (stale PENDING_INLINE_DIGESTS entries), which Fix main CI red on stale digest pending-list entries #1016 fixes. It is not caused by this PR.
• cargo test -p socket-patch-cli --lib: 862 passed.
• After the review fixes (head c081a8e):
  • cargo clippy -p socket-patch-core -p socket-patch-cli --all-features -- -D warnings -A unused_variables: clean.
  • cargo test -p socket-patch-core --lib -- vendor::jvm vendor::maven_repo crawlers::sbt_evidence crawlers::scala_evidence crawlers::maven_crawler: 365 passed. This includes the new layout::tests::{gradle_settings_names, tree_relative_constants_sit_under_their_tree, marker_present_edges}.
  • cargo test -p socket-patch-cli --bins --lib -- scan::: 248 passed.
  • cargo test -p socket-patch-cli --test e2e_maven --test e2e_sbt_vendor --test e2e_scala_cli_vendor --test e2e_sbt_hosted --test gradle_agent_cli --test contract_gradle_codes --test vendor_jvm_cli --test e2e_socket_yml_policy: all pass.
• cargo test -p socket-patch-cli --test e2e_maven --test e2e_sbt_vendor --test e2e_scala_cli_vendor --test e2e_sbt_hosted --test e2e_vex_vendor --test gradle_agent_cli --test contract_gradle_codes --test cli_parse_vendor --test in_process_rollback_vendored --test covgap_commands_vendor: all pass.
• Not run, left to CI: the real-build-tool and docker suites (e2e_*_build, docker_e2e_*).

Deferred

• Agent-mode JVM crawl finds no Coursier cache for a scala-cli or sbt root that only SCALA_TOOL_MARKERS recognizes, because six marker lists disagree #1014 is not closed. This PR fixes its proven defects A and B (the crawl gate) and moves its marker lists into one module. It keeps the existing rule that .mill-version makes a build ambiguous for sbt but is not a Mill build file for scala-cli, and sbt_evidence keeps its regular-file check on the shared sbt constants. Settling those is the issue's "decide once" step.

• B63 (the JVM upstream base is Central or SOCKET_MAVEN_REGISTRY only). It is not small: a fix would mean reading settings.xml mirrors and pom, Gradle and sbt resolvers. This PR does give it one place to land, layout::registry_base / registry_url, which now serves every JVM upstream URL including agent-mode jvm_jar.

• Merging the two coordinate grammars. is_path_safe and safe_coordinates still differ. Single-pom vendoring accepts coordinates that the v5 shapes refuse with unsafe_coordinates. Moving to one grammar changes behavior, which needs a decision.

• B62 (JVM trees invisible to orphan detection beyond the empty-ledger guard) belongs with Scan every vendored-write file for vendored references (#832, #958) #1015 / E61. This PR only consolidates the path list it would use (layout::ORPHAN_PATHS).

• The tree-relative constants (*_GITATTRIBUTES_REL, TREE_GITIGNORE_REL, GUARD_REL, TAIL_DIR, REPO_URL, the *-index.tsv paths) are still string literals in their backend modules, because concat! cannot take a const. layout::tests::tree_relative_constants_sit_under_their_tree checks that each one sits under its tree constant, so moving a tree root fails that test.

• Test fixtures (coursier_cache and scala_cache_tests helpers, test_support/service_fixture.rs, the bench crate) still spell the maven2 path themselves on purpose, so they act as an independent oracle.

• Maven and NuGet are lower priority per the maintainer. The scope here is the consolidation plus B17, B18 and B65.

🤖 Generated with Claude Code

---

Note

Medium Risk
Large touch surface across cache crawlers and in-place Maven patching path guards, but mostly consolidation; marker stat-rule and preflight alignment changes could shift which projects are scanned or granted downloads.

Overview
Introduces vendor::jvm::layout as the single source for Maven2 paths, coordinate guards (is_path_safe / safe_coordinates), vendor tree constants, Gradle/scala-cli build markers, and ledger_ecosystem (jvm → maven). Crawlers, vendor, scan, redirect, and CLI call sites are rewired to use it instead of duplicated helpers and marker tables.

Behavior fixes: sbt/scala-cli roots with only project/build.properties or .scala-build/ now trigger JVM cache discovery; --ecosystems maven includes ledger jvm entries; JVM service_preflight shares jvm_prelude with vendor_maven_jvm so grants are not issued when vendoring would refuse early. Build-marker detection uses one metadata-based rule (directories named like Gradle files count; dangling symlink markers do not). CLI contract documents the expanded JVM root markers.

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

---

Generated by Claude Code

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

[Mikola Lysenko (mikolalysenko)]

[agent] Ready for review at b441f55940ffa30c60ce213b490f02bfe4fff835.

• CI: required ci-ok green. 532 success / 7 skipped / 0 failing of 564 check runs. 25 non-required macOS/Windows native / install-proof legs are still queued on the runner backlog.
• Bugbot reviewed b441f55940 with no unresolved findings; no open review threads.
• Mergeable, no conflicts.
• Reviewer focus: the consolidated maven2 path helper and the --ecosystems maven handling of v5 jvm ledger entries (B17).

---

Generated by Claude Code