## Why this issue exists [docs/plans/2026-08-21-remote-conformance.md §Band B candidates, raised at Step 19](https://gitlab.com/gitlab-org/ops/registry-conformance/-/blob/184ced1f8aca45ff9031cbf76ee8393d8a12cb47/docs/plans/2026-08-21-remote-conformance.md#band-b-candidates-raised-at-step-19) records three spec-amendment candidates and states their route: all three ship as one MR against `docs/specs/` before Step 20 opens, and Step 20's `Depends on` names this issue. The plan also records that none of the three was filed, which is the deferred-gap state that section otherwise forbids. This issue closes that gap. The earlier four candidates from Band A shipped as #53 (landed as `fbd20bc`, spec MR !262), so they cannot carry these. Raised by !261 (npm remote foundation and walking skeleton, Steps 16-19). **Widened in review of !282** to carry the rest of the npm band's (`Band B`) candidates: Amendments 4 to 6 (Band B 4, 5, 6, raised at Steps 21 to 23) and Amendment 8 (Band B 8, raised in review of !263) join the original three (now explicitly Band B 1 to 3), and Amendment 9 (Band B 9, raised in review of !282) joins them too — eight of the npm band's nine candidates in total. Band B 7 is not narrow and is routed to #54 instead (the divergence index for the reference validation that raised it), which is why this issue's amendments are numbered 1 to 6, 8 and 9 with no 7. ## Amendment 1: S08 §Security Considerations overstates the redirect perimeter for `--upstream-url` The bullet says the flag "gets exactly the `--registry-url` treatment and no more: ... and the library client's `CheckRedirect` policy beyond it, including `--allow-redirect-host` and the unconditional HTTPS→HTTP downgrade rejection." That holds for the seeding publish and the packument read. It does not hold for the two tarball methods Step 16 adds, which the seeding path also calls: `HeadTarball` and `GetTarballAtVettedURL` install a redirect-disabled client of their own so they can resolve one hop themselves, which bypasses `CheckRedirect` entirely. They re-implement the downgrade rejection locally and drop the host lock on purpose, to admit the object-storage or CDN hop a tarball read legitimately takes. So a redirect hop on the seeding read is gated by scheme and not by `--allow-redirect-host`. Step 19 confines the *initial* URL to `--upstream-url`'s origin (`conformance.SameOrigin`), which is stricter than the bullet promises; the hop after it is looser. **The amendment is to say which**, rather than leave a reader to infer a host lock that is not there. It amends the spec's description of the perimeter; it does not close the hop. Closing the hop is tracked separately (see §Out of scope). ## Amendment 2: S08 classes `<format>.remote.preflight` as `Relay`, and AC #13's byte comparison is unsatisfiable for npm's §Per-format rows puts `npm.remote.preflight` in the `Relay` class, and AC #13 makes a relay row pass "only when the bytes are identical and the format's own integrity metadata agrees with them". The npm preflight reads a packument, which the registry synthesizes (`_id`, `_rev`, a `time` map off the registry clock, an absolute `dist.tarball` it owns), so no suite-authored fixture can be byte-identical to one and there is no correct value to compare against. AC #24 is what actually governs the row. **The amendment is either a carve-out on AC #13 for the preflight rows, or a class of their own.** The OCI and Maven preflights are to be checked against the same question rather than assumed different. **Open note from the widening below:** the plan's own instruction for this widening says to "extend Amendment 2 to the rows the entry now names," but none of Amendments 4, 5, 6, 8 or 9 below are preflight rows (they cover tarball-url rewriting, tarball-relay digests, repeat-read, dist-tags-relay and the settle read-back), so it is not obvious from this issue alone which row(s) that instruction means. Whoever drafts the `docs/specs/` MR should re-check `docs/plans/2026-08-21-remote-conformance.md`'s widening paragraph against the full Band B set before relying on this note's reading. ## Amendment 3: S04 §Entry points says three functions are exported from `pkg/conformance`, and there are now more than three The section opens "Three functions are exported from `pkg/conformance`" and lists `RunModule`, `Run` and `SelectDescriptors`. Step 5a already exported `SeedAndSettle`, `NewSeedFailureCase`, `PreflightFailureMessage` and the `SeedAttempts` constant without amending it, and Step 19 adds `SameOrigin`. This is the same completeness problem S06 §`pkg/client/npm` method surface has and takes seriously: a controlled surface list constrains nothing once it is known to be partial, and a reader auditing `pkg/conformance`'s public API against S04 gets a wrong answer today. **The amendment either completes the list, or says explicitly that the section names entry points rather than the whole exported surface.** Raised at Step 19 but not caused by it: the drift starts at Step 5a. ## Amendment 4: S08 AC #19 permits a vacuous pass, and does not say what "under" compares AC #19 reads "passes only when every `dist.tarball` in the relayed packument is under `--registry-url` and none is under `--upstream-url`". Two gaps, both of which fork the implementation observably: - **The universal is vacuously true over an empty `versions` map.** A relay that serves `{"name":"...","versions":{}}` satisfies "every `dist.tarball` is under `--registry-url`" because there are none, so the row passes against a repository that relayed nothing. `npm.remote.packument-relay` catches that document, but AC #29 requires every row to pass alone, so this row cannot lean on that one having run. Step 21 therefore also requires the seeded version to be present with a non-empty `dist.tarball`. That is an addition to the AC, not a narrowing of it, and it is recorded here rather than left in the code because the next format's equivalent row (`oci.remote`, Step 31) faces the identical question and should not have to re-derive the answer. - **"Under" has no comparison pinned.** A bare string prefix accepts `http://host/ns/npm/npm-remote-evil/...` as "under" `http://host/ns/npm/npm-remote`, which is a different repository. Step 21 compares scheme, host and whole path segments, with the host compared through `conformance.CanonicalHost` so that two spellings of one DNS name are one host and two DNS names are never one. Two implementers reading the AC as written emit different verdicts on that URL, which is what makes this worth a clause rather than a comment. One sentence each closes both. ## Amendment 5: S08's `npm.remote.tarball-relay` row names `dist.integrity`, and the existing hosted helper does not require it The row reads "The advertised tarball URL serves bytes matching the packument's `dist.integrity`", but `pkg/conformance/npm/tarball_verify.go`'s `verifyTarballDigests` requires only that **at least one** of `dist.shasum` and `dist.integrity` be present, and checks each only when present. Reused as-is, the row would pass on a SHA-1 `shasum` match against a relayed packument that dropped `integrity` entirely, which does not establish what the row claims. Requiring `integrity` is safe here specifically because this is a remote row over a suite-seeded fixture: `client.BuildPublishBody` always computes both digests, so the upstream packument this run seeded always advertises `integrity`, and a relayed document missing it is a relay defect rather than a legitimately older registry. That reasoning does **not** transfer to the hosted `npm.tarball.*` rows, whose fixture is not necessarily the suite's, which is why `verifyTarballDigests` should keep its current shape and this row should not reuse it. The amendment worth making is one clause in S06 §Operation: Tarball download saying which digests a *relay* must preserve, so the distinction between the hosted helper's permissiveness and this row's strictness is stated somewhere other than a Go comment. ## Amendment 6: S08 AC #16 admits a vacuous pass, the same shape as Amendment 4's AC #16 requires a repeat read's second response to be "byte-identical to the first". Two zero-byte responses satisfy that, so a repository serving nothing twice passes the row. Step 22 therefore also requires the response to be non-empty and to carry the seeded version, and reports `StatusFail` otherwise. This is reachable on the tarball path only: an empty packument fails the client's JSON decode before the comparison runs. That asymmetry is worth the clause rather than an argument against it, because a row whose vacuity depends on which of its two artifacts is being read is harder to reason about than one that rules it out for both. The amendment is one clause saying an artifact that is absent or empty is not a repeat-read pass. It travels with Amendment 4: both are universally-quantified criteria that are trivially true over nothing, and the OCI band's `oci.remote.repeat-read` (Step 35) inherits the identical question. ## Amendment 8: `npm.remote.dist-tags-relay`'s seeded-version anchor asserts more than any spec text carries The row requires the relayed packument to carry the seeded version before it compares the two documents. S08 §Per-format rows asks only that the two documents agree, and AC #29's ban on depending on another row having run is not the same as requiring an anchor, so a registry conformant to the text but serving two agreeing documents out of one stale fill fails a clause no spec carries. The anchor is the right call and `remote_disttags.go` argues it; this entry is about the route rather than the assertion. It is the same shape as Amendment 4 (`tarball-url-rewritten` requiring the seeded version with a non-empty `dist.tarball`, beyond AC #19's bare universal) and Amendment 6 (`repeat-read` rejecting two empty responses, beyond AC #16's literal "byte-identical"): each closes a vacuous pass the AC as written admits, and each needs the AC to say so. Those two carry a route and this one did not, which is the gap. It travels with them. (Raised in review of !263. Band B 7, the fourth candidate raised alongside this one, is not narrow and is routed to #54 instead — see "Why this issue exists" above.) ## Amendment 9: npm's settle read-back reports 200 for any accepted 2xx, so a bodyless tarball read clears the poll `seedReadBack` assigns `result.Status = http.StatusOK` after any accepted read, and `GetTarballAtVettedURL` accepts the whole 2xx range. A `204` or `206` tarball read is therefore reported as a `200`, and on the confirmed-write path `pkg/conformance/seed.go` §`satisfies` takes readability alone as the post-condition, so the settle clears on a read that served no tarball and the row goes on to read through the proxy against a coordinate the upstream never served. That is the negative-caching outcome AC #14 and S08 §Seeding and asynchronous upstreams put the poll there to prevent. It is the same defect !282 fixed for Maven in `remoteSeedReadBack`, in a different band rather than a variant: Maven's callback surfaced the real status and accepted too wide a set, npm's overwrites the status before anyone can judge it, which also means no npm arm can currently observe the case. OCI is not affected; its read-back gates on `200` internally. Two halves, and only the first is a spec question. Whether AC #14's "confirmed readable" pins a status is the amendment, and the sentence it carries is that a read-back confirms readability only when it answers `200`, so that both halves are written against one wording rather than two. That sentence is carried by #76's Maven 6 entry, not this one. Maven 6 records the same reading from the Maven side, where the fix chose `200`. This entry raises the question from npm's side and defers the wording there rather than restating it, so this issue and #76 cannot amend AC #14 in parallel or drift apart on what it says. Whether npm's callback should stop overwriting `Status` is a defect fix in the npm band and needs no amendment either way, since a reported status that was never received is wrong under any reading. Stopping the overwrite is not the whole of that fix: the settle clears on `err == nil && s.satisfies(res)` (`pkg/conformance/seed.go` §`settle`) and `satisfies` reads readability and the fixture bytes, never the status, so a `204` reported honestly as a `204` still settles the poll on a read that served no tarball. The fix has to make the read-back return a non-nil error on a non-200, which is what routes the status through `settlePollShortCircuits`; Maven's `remoteSeedReadBack` already does exactly that with its `notReadableError`, so the npm callback mirrors it. **Client precondition, tracked separately, not by this amendment:** mirroring the Maven fix needs npm's `GetTarball` (`pkg/client/npm/tarball.go`) to expose a terminal status first, since it currently returns `([]byte, string, error)` with no status on the success path — there is nothing for a read-back to reject a non-200 on. The chosen shape follows the `PublishResponse` precedent already in the same package (`pkg/client/npm/publish.go`) rather than narrowing `GetTarball`'s acceptance to a bare `200` (which would make the status unavailable to any other caller). This is a client code change, not a spec amendment, so it does not belong in this issue's `docs/specs/` MR; it is tracked in [#79](https://gitlab.com/gitlab-org/ops/registry-conformance/-/issues/79). (Raised in review of !282.) ## Out of scope Two adjacent items are tracked elsewhere and must not be folded in here: - **The credential on a cross-host tarball hop** is #55. Its `resolveOneRedirect` half is !274, still open against `main`; its `resolveVettedHop` half is routed to !261, the MR that authors `resolveVettedHop`. - **Confining the hop's target host** is #68. Amendment 1 documents that the hop is gated by scheme only; it does not propose a host gate, and its final wording has to match whatever perimeter #68 lands. ## Acceptance - [ ] All eight amendments (1 to 6, 8 and 9) land in one MR against `docs/specs/`. - [ ] Step 20's `Depends on` in `docs/plans/2026-08-21-remote-conformance.md` names this issue (already does; the MR shipped after Steps 20-25, see "Why this issue exists"). - [ ] §Band B candidates is updated to record all eight as filed to this issue. - [ ] Amendment 2's "extend to the rows the entry now names" open note above is resolved one way or the other, not left unresolved in the spec MR.