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.mdStep 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: thePositionDataErrorcomment 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 onExpected error with "virtual: position vetoed the collection" in chain but got nil, and the carve-out test never vetoed at all and ran intoresolution.resolve_timeout.go test ./...,golangci-lint run ./internal/format/maven/..., and the comment-caps gate: clean.- The veto's
500is asserted throughwriteMavenVirtualReadError, 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.mdputs 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_errorarm.
Closes #1495 (closed)