fix(maven): veto the metadata merge on a hosted read failure

Summary

A hosted position's Lookup Hit is authoritative: it answered that this repository holds the coordinate. Its stored document is also the only copy of what that repository holds, because a hosted position has no cached copy to fall back to. So a read that then failed to serve it booked the position omitted and let the merge answer 200 merged_partial from the remaining positions, listing a remote's versions under a coordinate the hosted repository holds.

mavenMergeContributor now routes a hosted position through fromHosted, which wraps every failure of the stored read in virtual.ErrReadVetoed except one whose own context already ended. That case is the collection's cut, a sibling's veto or the caller leaving, not this position's failure, and re-wrapping it would misattribute the cut. Remote positions keep reading through fromBlob unwrapped, so a remote's cached-copy failure stays the best-effort omission the merge already serves around.

The six shapes a hosted stored read can fail on all veto: the blob gone to retention, a refused redirect, a mid-read blob fault, and a document that carries a DOCTYPE, is over maven.max_metadata_size, or does not parse. virtual.ErrReadVetoed also joins the read mapping's named server-error set, so the resulting 500 records the reason the taxonomy names.

Out of scope, and named so this MR is not read as closing the whole hazard: a resolution budget expiring mid-hosted-read still degrades to merged_partial. Issue #1467 owns that arm, along with npm's remaining post-Hit failure types.

The collector has no production caller yet. S30 step 14 wires it, and MR !3045 (merged) touches the same two Go files, so that MR rebases onto this one and re-applies the arm in its deferred-read shape.

Governing ADRs

None. A search over docs/adr/ finds no decision governing the virtual metadata merge's per-position veto. The ADRs that mention virtual repositories govern storage, the API, and retention.

Plan and spec amendments

S30 had no hosted-veto arm, so this is an arm to add rather than a claim to widen.

  • docs/specs/S30-maven-virtual.md: states the arm in the hosted bullet, overrides the best-effort paragraph with it, qualifies the malformed-input paragraph, adds its Error Cases row, and notes in Wide events that a vetoed read reaches neither success value.
  • docs/plans/2026-09-10-s30-maven-virtual.md Step 13: scopes its "no veto is armed" claim to a remote position and names the hosted one's veto, in the step text and in its Acceptance list.
  • internal/virtual/position.go: the PositionDataError comment cited S30 for a line S30 now draws for a remote position alone. Comment only.

Testing

Test-first: the first commit carries only the failing repro.

  • go test ./internal/format/maven/...: the six veto subtests, the sibling-cut carve-out, and the remote-omission negative all pass. Before the fix all six subtests failed on Expected error with "virtual: position vetoed the collection" in chain but got nil, and the carve-out test never vetoed at all and ran into resolution.resolve_timeout.
  • go test ./..., golangci-lint run ./internal/format/maven/..., and the comment-caps gate: clean.
  • The veto's 500 is asserted through writeMavenVirtualReadError, including that the response body carries no version from the remote whose document would have stood in.
  • No e2e scenario is added or affected: docs/testing/e2e/maven.md puts the package-level metadata merge out of the current catalog's scope and names S30 as its owner.
  • No user documentation is affected: nothing a customer can call, see, or configure changes, and the veto takes the existing 500 internal_server_error arm.

Closes #1495 (closed)

Merge request reports

Loading
Loading