## What is wrong `docs/specs/S12-container-oci-hosted.md:794` states this rule for the cross-repository blob mount: > No source-side **business outcome** produces a status other than `201` or `202`, absent an infrastructure fault: a source that is missing, unresolvable, cross-namespace, unreadable, or itself tombstoned before the mount resolves it all take the `202` fallback, byte-identically. The word "byte-identically" is false. `mountFallback` calls `CreateSession`, and `CreateSession` opens a new upload session on every request through `store.NewSession`. `mountFallback` then writes that session id into the `Location` header, at `internal/format/oci/upload.go:803`. Two `202` fallbacks are alike in every field except that one, so they are not byte-identical. The sentence is branch-authored. `origin/main` at `7307bd94a` carries no "byte-identically" claim anywhere in its mount section. [!2332](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2332) therefore adds the claim and defers its correction in one merge request. ## The code carries the exception the spec omits `internal/format/oci/upload.go:770`, the doc comment on `mountFallback`: > `// mountFallback answers 202 with a fresh session, alike across every fallback reason but for its UUID so nothing leaks, or 500 if its CreateSession fails.` `internal/format/oci/upload.go:795-799`, the comment that precedes the header writes: > `// Byte-identical to handleInitiate: Location is the fresh session URL and` > `// Range is the upstream-compatible 0-0. Every fallback condition emits` > `// this exact header set so the responses differ only in the session UUID` > `// (which the indistinguishability property normalizes). The fallback` > `// opened a real session, so the request-close event carries its id.` `internal/format/oci/blob_finalize_liveness_race_test.go:366`, an assertion message: > `"the fallback 202 is byte-identical to an initiate's modulo the session UUID, so the source's state cannot be read off it"` Two commits on the branch wrote those qualifiers, and they are not the same commit: | Commit | Subject | What it qualified | | --- | --- | --- | | `c69990ff9581a863ae24856b8828a533bfef18d1` | `docs(oci): scope the blob-link comments the fence left over-general` | the assertion message at `blob_finalize_liveness_race_test.go:366`. Its body names finding O22, and its `upload.go` hunk kept "byte-identical across every fallback reason" and only appended the `500` clause | | `0f2dc2cdbe7a0d572cddbabb54de065c04a6b2a8` | `docs(oci): correct the claims this fixer's own edits left over-general` | the `mountFallback` doc comment at `upload.go:770`. Its body names no finding id | The review note that raised this item cites `5919066cb` and attributes the `upload.go` correction to finding O22. Neither half holds at the branch head. `5919066cb` is a pre-rewrite identity, and `git merge-base --is-ancestor 5919066cb HEAD` returns false. It resolves on the branch to `0f2dc2cdb`: same subject, same four files, same 10 insertions and 10 deletions. O22 was answered by `c69990ff9`, and that commit's O22 edit landed in the test file. The `upload.go` hunk of the same commit left the unqualified wording standing. ## The four surfaces that carry the claim Every coordinate below is measured at !2332's head `60fc9a3ef`. | Surface | What it says | Does it claim byte-identity | | --- | --- | --- | | `docs/specs/S12-container-oci-hosted.md:794` | the sentence quoted in `## What is wrong` | Yes, in the word "byte-identically" | | `docs/specs/S12-container-oci-hosted.md:786-792` | the mount status-code table. Its `:789` row maps "Any source-side business failure" to one `202 Accepted` with `Location: <upload-session-url>` | No. One row for every source-side failure states the equivalence without naming byte-identity | | `docs/specs/S20-a-lifecycle-closed-beta.md:1015` | "`202` with a normal upload session, the same answer an unresolvable source gets" | No | | `docs/testing/e2e/oci.md:44` | "A mount whose `from=` source is tombstoned before the mount resolves it still returns `202` with a normal upload session, and so does a mount whose destination is tombstoned but which takes that same fallback arm" | No | Only the first surface carries the false word. The other three state the same equivalence in weaker words, and each one is true as written. A change to `docs/specs/S12-container-oci-hosted.md:794` alone is enough for correctness. A change that also names the session UUID on the other three makes the record consistent. ## Two more unqualified claims live inside `upload.go` itself `internal/format/oci/upload.go:740` reads "The client-visible 202 stays byte-identical across reasons". `internal/format/oci/upload.go:848` reads "maps every reason to a byte-identical 202". Both are pre-existing on `origin/main`, at `:661` and `:786`. !2332 did not add them, so its "every added line" sweep did not reach them. They are listed here because they put the same contradiction inside one file, which `## The four surfaces that carry the claim` does not show. ## Why this is a separate work item !2332 found this defect, decided against correcting it, and disclosed the decision. Its description carries the decision under the heading `## One over-general claim survives, and is disclosed rather than corrected`: > The equivalence claim for the fallback `202` still stands unqualified. > `S12:789` says the source-side outcomes take the `202` fallback "byte-identically", the status table at `S12:782-787` states the same equivalence, and `S20-a:1010` and `docs/testing/e2e/oci.md:44` repeat it in other words. > The session UUID differs per request, so two such responses are not byte-identical. > `mountFallback`'s own body comment already carries the qualifier (`internal/format/oci/upload.go:759-763`), and so does `internal/format/oci/blob_finalize_liveness_race_test.go:366`. > Widening that qualifier into the three specs and the catalog is a fresh finding, not part of this fix. Four coordinates in that paragraph are stale at !2332's head, and this work item does not correct the description. `S12:789` is now `S12:794`, `S12:782-787` is now `S12:786-792`, `S20-a:1010` is now `S20-a:1015`, and `internal/format/oci/upload.go:759-763` is now `:795-799`. Take the coordinates from `## The four surfaces that carry the claim` instead. ## What closes this 1. Add the session-UUID exception to `docs/specs/S12-container-oci-hosted.md:794`, in the words `mountFallback` already uses. 2. Decide whether the three companion surfaces need the same qualifier, and record the decision either way. 3. Re-derive every line number when the change is written. `docs/specs/S12-container-oci-hosted.md` is also edited by [!2358](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2358) "docs(specs): reassign the hosted downloads_count writers off S18 (repository-column-writers plan: 1/5)". `internal/format/oci/upload.go` is also edited by [!2346](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2346) "fix(oci): re-arm the blob upload deadline on each read (upload-inactivity-deadline plan: 2/4)". Found in [!2332](https://gitlab.com/gitlab-org/ops/artifact-registry/-/merge_requests/2332) "fix(oci): fence the blob link against a repository tombstone". Related to [#1122](https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/1122).