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).

  1. S10 — SHA-1 redirect-mode backend asymmetry (new section, plus two inline refinements and one S14 pointer): the persisted checksum-sha1 user metadata resurfaces as x-goog-meta-checksum-sha1 on GCS redirects — one of the four header names Maven Resolver's XChecksumExtractor parses — and as x-amz-meta-checksum-sha1 on S3, which Resolver does not parse, so S3-backed redirect deliveries fall back to the .sha1 sidecar GET. Redirect responses also carry the storage backend's own object ETag (on S3 a multipart-upload ETag — blobs go through the driver's multipart Writer — not the object MD5), never AR's "sha256:<hex>". The wire-level requirement sentence in ## API Contracts now 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.

  2. S10 — hosted client conditionals (prescriptive): a matching If-None-Match on the hosted read path answers a bodyless 304 carrying the ETag — primary files and synthesized sidecars, GET and HEAD, both delivery modes; a condition match is never a download increment, the hosted last_downloaded_at access bump is kept for a satisfied conditional, and the remote path's delivery-gated divergence is named. The API-contracts table gains the 304 row. This is a spec-first change: the closed-beta test verified the current shipped behavior (hosted answers 200 regardless of the validator); this amendment prescribes the fix, which lands in a follow-up MR that reuses the remote path's existing ifNoneMatchMatches helper (tracked in #948).

  3. S14 — client resolution order (new section): mvn dependency:get -DremoteRepositories=… the plugin appends the -DremoteRepositories entry after its pomRemoteRepositories list (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. The mirrorOf=* 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.

Edited by Moaz Khalifa

Merge request reports

Loading
Loading