Tracking: sequencing the remaining breaking changes before v3.0.0 GA

[TerryHowe]

Why this issue exists

v3.0.0-rc.1 is tagged. GA closes the breaking-change window, and v2 is GA so nothing breaking lands there either. There are currently a dozen-plus open issues that change exported signatures or observable contracts, and several of them mutate the same symbols. Taken in filing order, they would break the same exported functions two or three times inside one release window.

This issue is a sequencing proposal, not new scope. Every item below is an existing issue.

Status refreshed against main @ ff26996. Tiers 2, 3 and 5 are done; Tier 1 is 6/9 with only the scope half and #873 left. Original analysis kept below where it still applies.

---

Tier 1 — the auth cluster: one break, or three

These issues all mutate the same small set of exported symbols in registry/remote/auth and registry/remote/credentials.

Issue	Breaking?	Status
#1380 Resource type	additive	✅ merged (#1391)
#1381 derive repo path in Client.Do	no	✅ merged (#1398)
#1385 AppendRepositoryScope	yes	✅ merged (#1405)
#1382 CredentialFunc / TokenParams	yes	✅ merged (#1423)
#1383 token cache key ignores namespace	yes (silent)	✅ merged
#1384 Login / Logout host-keyed	yes	✅ merged (#1448)
#1451 typed Scope	yes	🔲 open
#1376 hints keyed on Resource	yes	🔲 open
#873 granular credentials interface	no (see below)	🔲 open, decided

The proposed order held up. #1380 → #1381 → #1385 → #1382 + #1383 → #1384 landed in that sequence, and no exported signature in the cluster was broken twice.

What is left

#1451 and #1376 are the scope half, and they still collide: both rewrite WithScopesForHost / AppendScopesForHost / GetScopesForHost. They should land as one change, not two. #1385's part of that collision is already resolved.

#873 is no longer blocked, and no longer breaking. Its stated dependency — "must be defined after #1382, or its key type is wrong on arrival" — is discharged. With the key type settled, every caller of credentials.Store uses exactly one of its three methods (NewCredentialFunc → Get, Login → Put, Logout → Delete), so the split is mechanical and source-compatible for callers and implementers alike. The issue body has been updated with the current scope.

Decided: the granular getter is keyed by serverAddress string, not properties.Resource. A Resource-keyed store interface would break every third-party store while pushing the Resource → server-address mapping into each implementation, and it does not resolve #1431 (a return-shape problem) or #1453 (already handled by #1457). If it is ever wanted it can be added additively as an optional ResourceGetter. Rationale recorded in the issue.

#873 also now carries the NamespaceMatcher embed fix — see #1455 below.

Follow-on issues the cluster produced

Namespaced credentials turned out to have consequences beyond the signatures. These were filed during the Tier 1 work and are part of finishing it:

• auth: the redirect origin check is host-level, so a same-host redirect carries a namespaced credential across namespaces #1430 — the redirect origin check is host-level, so a same-host redirect across a namespace boundary forwards one namespace's credential to another. Security-relevant; a direct consequence of auth: CredentialFunc and TokenParams should take a Resource instead of a host string #1382.
• auth: credential precedence is unspecified when the most-specific namespace match has no credentials #1431 — credential precedence is unspecified when the most-specific namespace match carries no credentials. Needs deciding with Introduce more granular interface into credentials package (decided) #873: one of its two options adds a method to whatever interface Introduce more granular interface into credentials package (decided) #873 defines.
• auth: credential helper lookup is host-exact, so a namespaced key bypasses credHelpers #1453 — credential-helper lookup is host-exact, so a namespaced key bypasses credHelpers entirely. PR fix(credentials): use the host's credential helper for a namespaced key #1457 open. Makes namespaced login unusable for ECR/GAR until fixed.
• auth: the legacy config fallback in GetAuthConfig matches path-bearing keys, so a host lookup can return a namespaced credential #1443 — ✅ closed (fix(auth): restrict legacy credential fallback #1449): the legacy config fallback matched path-bearing keys.
• feat(auth): let the store own the namespace walk when it matches namespaces #1455 — ✅ merged (dbb5bb4), landing NamespaceMatcher interface { Store; MatchesNamespace(string) bool }. It merged ahead of Introduce more granular interface into credentials package (decided) #873, so it embeds the full Store where it should embed the granular getter. Not a problem yet: the interface is not in v3.0.0-rc.1, so narrowing it costs nothing today. The fix has been folded into Introduce more granular interface into credentials package (decided) #873's scope. It needs to happen before GA.

---

Tier 2 — finish the registry.Reference deprecation ✅

#1387 and #1386 are closed (#1392, #1393). #1394 item 5 (the layering) remains part of that open design issue.

The silent-hazard concern was addressed as suggested: internal/interfaces now carries both ReferenceParser and LegacyReferenceParser, and content.go tries each in turn (content.go:61,68), so a third-party Target on the old signature still matches and still gets scope hints. The transition period is in place; the release note for when it is removed is still owed.

---

Tier 3 — security fixes that change parse output ✅

#1388, #1389, #1390 and #1396 are all closed.

#1388 and #1389 were fixed together by normalizing the registry host case in properties.NewReference (#1402), closing both fail-open bypasses with one change, as proposed. #1390 landed in #1397. #1396 is fixed.

---

Tier 4 — semantics and defaults

Each of these is defensible either way; the point is that not deciding is itself a decision once GA ships. This is now the tier with the most left in it.

• Should oras.Copy() follow manifests specified in the layers or the blobs field? #401 — 🔲 should Copy() follow manifests in the layers / blobs field? Milestoned v3.0.0, open since 2023. Traversal semantics are much harder to change post-GA.
• Reference parsing considers zero-length tags and digests to be valid #1191 — ✅ closed. Zero-length tags and digests now rejected.
• Retry MaxWait 3 seconds is too short! Jitter for 429/TooManyRequests? #1210 — 🔲 MaxWait: 3 * time.Second (retry/policy.go) effectively neuters Retry-After on 429s. Raising it makes retried operations take materially longer.
• Performance audit: 10 findings in the copy engine, content stores, and registry client #1395 finding 2 — 🔲 defaultConcurrency = 3 (copy.go), measured ~5.5x slower than 32 on a latency-bound 40-layer copy. Raising the default is an observable behaviour change. Finding 1 (the pooled 1 MiB buffer) landed in perf(content): actually use the pooled 1 MiB copy buffer #1418; the rest of that audit is non-breaking and can ship anytime.

---

Tier 5 — remove dead API while removal is still free ✅

#1374 is closed. #1394 item 1 is folded into that open design issue.

---

Explicitly not in the GA window

Additive, internal, or backward-compatible — ship whenever: #1395 findings 3-10, #1227, #1245, #576, #947, #986, #338, #126, #957, #949 (loosening only), #1361, #4. #898 is mostly additive (PackManifestOptions is a struct); only the panic-to-error change and any algorithm allowlist would break.

#1294 still deserves a call-out: oci.Store.GC hangs forever on a shadowed variable in gcIndex. Pure bugfix, non-breaking, and it should go in regardless of this sequencing. Still open.

---

What is actually left before GA

1. auth: make Scope a typed value instead of a string, and fix CleanScopes de-duplication (decided) #1451 + auth: scope hints are keyed per host, so namespaces on the same registry share one hint bucket #1376 as one change — the last signature collision in the auth cluster.
2. Introduce more granular interface into credentials package (decided) #873 — decided, not yet implemented. Carries the NamespaceMatcher embed fix that feat(auth): let the store own the namespace walk when it matches namespaces #1455 left behind: free to change while unreleased, breaking once GA ships it. auth: credential precedence is unspecified when the most-specific namespace match has no credentials #1431 is worth settling first so Getter is not defined twice, but does not block.
3. auth: the redirect origin check is host-level, so a same-host redirect carries a namespaced credential across namespaces #1430 — namespaced credentials leaking across a same-host redirect. Security-relevant and a direct consequence of Tier 1.
4. Tier 4 defaults (Should oras.Copy() follow manifests specified in the layers or the blobs field? #401, Retry MaxWait 3 seconds is too short! Jitter for 429/TooManyRequests? #1210, Performance audit: 10 findings in the copy engine, content stores, and registry client #1395 finding 2) — decide rather than let GA decide.