docs(specs): amend S10 and S14 Maven contracts
Summary
Records three findings from the closed-beta pre-release Maven test run (binary built from
origin/main at the time, driven with real mvn 3.9 and Gradle clients, a controlled loopback
upstream with per-request failure modes, and a live Maven Central round trip).
-
S10 — SHA-1 redirect-mode backend asymmetry (new section, plus two inline refinements and one S14 pointer): the persisted
checksum-sha1user metadata resurfaces asx-goog-meta-checksum-sha1on GCS redirects — one of the four header names Maven Resolver'sXChecksumExtractorparses — and asx-amz-meta-checksum-sha1on S3, which Resolver does not parse, so S3-backed redirect deliveries fall back to the.sha1sidecar GET. Redirect responses also carry the storage backend's own object ETag (on S3 a multipart-upload ETag — blobs go through the driver's multipartWriter— not the object MD5), never AR's"sha256:<hex>". The wire-level requirement sentence in## API Contractsnow names the S3 exception, and the "SHA-1 is symmetric" claim in the MD5 asymmetry section is qualified. S14's "Cache hit (fresh)" points at the new section. -
S10 — hosted client conditionals (prescriptive): a matching
If-None-Matchon the hosted read path answers a bodyless304carrying the ETag — primary files and synthesized sidecars,GETandHEAD, both delivery modes; a condition match is never a download increment, the hostedlast_downloaded_ataccess bump is kept for a satisfied conditional, and the remote path's delivery-gated divergence is named. The API-contracts table gains the304row. This is a spec-first change: the closed-beta test verified the current shipped behavior (hosted answers200regardless of the validator); this amendment prescribes the fix, which lands in a follow-up MR that reuses the remote path's existingifNoneMatchMatcheshelper (tracked in #948). -
S14 — client resolution order (new section):
mvn dependency:get -DremoteRepositories=…the plugin appends the-DremoteRepositoriesentry after itspomRemoteRepositorieslist (defaulting to Maven Central outside a project) and resolves the artifact and its transitive dependencies against the combined list in order, so artifacts Central also holds never reach the proxy. ThemirrorOf=*mirror and project<repositories>shapes are the ones that route every read through the registry. Verified both ways in the test run.
Governing ADRs
- ADR-005 (artifact delivery mode): Amendment 1 documents redirect-mode wire behavior under it; no deviation.
- ADR-009 (uniform client URLs): unaffected; no deviation.
- ADR-007 (schema): unaffected.
Testing
Markdown-only. Linted by markdownlint-cli2, vale (--minAlertLevel=error), and lychee in CI; all
pass locally. Every claim in the amendments was verified end-to-end against a local build —
commands and observed responses are in the test report from the same run and can be re-run.
No behavior changes in this MR. The S10 conditional amendment prescribes behavior for the follow-up implementation MR.