Artifact Registry ADR 005: metadata documents are always streamed

Why is this change being made?

ADR-005 says the Artifact Registry picks between redirect and proxy delivery from two axes: the instance default storage.delivery_mode, and the per-namespace namespaces.delivery_mode_override. Read as written, that governs every download.

Two format read paths already do not obey it, for a reason the ADR does not record:

• OCI image manifests and indexes force a stream (issue 362, landed in artifact-registry!991).
• npm packuments and dist-tags documents are about to, in issue 1128 / artifact-registry!2307, which is held pending this MR.

A redirected metadata document arrives as application/octet-stream: a pre-signed object storage URL serves the object's stored Content-Type, and every storage driver writes that type at commit time. Its clients are entitled to read application/vnd.oci.image.manifest.v1+json, application/json, or application/vnd.npm.install-v1+json before parsing, and only the service can set a response header.

The reason the fix is a streamed response, rather than a correct type on the stored object, is that content type is a property of how a format interprets a blob and not a property of the blob itself. That is a decision the storage layer already took and recorded: blob_storage_blobs carries no content_type column, because the same bytes can be referenced by different formats under different media types. Deduplication is what makes it a constraint rather than a preference: the blob table's uniqueness is (namespace_id, sha256) with no format component, and a commit that finds the destination object already present skips the write and applies no metadata to it, so a digest reachable under two formats gets one type, set by whichever format wrote first. One attribute on one object cannot carry two correct media types.

The first deviation was tracked outside the ADR. Per the Artifact Registry's AGENTS.md, a deviation needs an explicit escalation and an amendment here, and the second one is what makes this a rule rather than a one-off, so it is recorded now rather than tracked again.

What does this change?

Changes to 005_artifact_delivery_mode.md:

1. A new subsection under Decision, ### What the axes govern: artifact content, not metadata documents. It scopes the two axes to artifact content (container layers and blobs, Maven artifacts, npm tarballs), names the four metadata documents that are always streamed, gives the reason above with its two sources in the Artifact Registry repo, bounds the cost, and notes that the mechanism is the existing WithForceStream blob-open option, which already outranks both axes. No new configuration knob.
2. The same subsection names what the exemption does not reach: hosted Maven primary files, maven-metadata.xml included, are served by the ordinary Maven download path, whose redirect arm sets no Content-Type at all. Closing that belongs to the Maven workstream.
3. A fifth Negative consequence: neither axis is observable on a metadata read, so the exemption has to be documented rather than inferred from behavior.
4. Alternative 4, the pre-signed URL response-content-type override, with why it was rejected. Its first con is that Cloud CDN URL-prefix signing refuses a URL that already carries a query string, so the parameter turns every CDN-served redirect into an error rather than into a long journey; the threading cost through both drivers and all three URL-decorating middlewares comes after that hard stop. Its last con separates bytes from requests: the offload given up is a small share of download bytes and not a small share of download requests.
5. Alternative 5, setting the correct content type on the object at write time, recorded on its own terms. It is the cheaper of the two candidates issue 1128 put forward, it is a different proposal from Alternative 4 because it changes the object rather than the URL, and the ADR had never opened it. It loses on the reason above rather than on cost.

Four links are added to References: the two reports, and the two Artifact Registry documents the reason rests on.

The subsection names the artifact-registry commit its symbol and document citations were checked at, so a reader can re-run them.

Author checklist

• markdownlint-cli2: 0 issues.
• vale: 0 errors. Warnings go from 5 at the merge base to 10 on this branch, and all five new ones are handbook.Spelling: four on "packument", which 007_database_schema.md already uses and which draws the same warning there, and one on "dedup", from quoting the literal heading First-write-wins on dedup in the Artifact Registry's docs/dev/storage.md. The five carried over from the merge base are three on "CAs", one on "proto", and one gitlab_base.LatinTerms on "via".
• The Artifact Registry mirror of this ADR at docs/adr/005_artifact_delivery_mode.md is byte-identical to main here, so the daily sync will carry this through without a conflict. Checked at artifact-registry f4aabe6b0 against handbook origin/main.

/cc @jdrpereira @prozlach