docs: fold v3 design notes into the docs PR

Consolidates the documentation-only changes into a single PR so they can be
reviewed together and thinned out in one place: adds
docs/design/signedby-tag-resolution.md and
docs/design/config-credentials-coupling.md, previously proposed separately.

The config-credentials note is the version that describes the design as a
proposal. A later revision on the v3 working branch marks it implemented, but
the shared configfile package it refers to has not landed on main yet, so that
wording would be inaccurate here.

Signed-off-by: Terry Howe <terrylhowe@gmail.com>

Author: TerryHowe

docs/design/config-credentials-coupling.md

@@ -0,0 +1,130 @@
+# Design: decoupling `credentials` from `config` without a global
+
+Status: **proposal** — recommend settling before the v3 API freeze.
+
+## Problem
+
+`credentials.NewStore` depends on a package-level mutable variable that a
+*different* package populates as an import side effect.
+
+`registry/remote/credentials/store.go`:
+
+```go
+// defaultConfigLoader is set by the config package during init.
+var defaultConfigLoader ConfigFileLoader
+
+var ErrNoConfigLoader = fmt.Errorf("no config loader registered; import the config package or use NewStoreFromConfig")
+
+func SetDefaultConfigLoader(loader ConfigFileLoader) {
+	defaultConfigLoader = loader
+}
+
+func NewStore(configPath string, opts StoreOptions) (*DynamicStore, error) {
+	if defaultConfigLoader == nil {
+		return nil, ErrNoConfigLoader
+	}
+	// ...
+}
+```
+
+`registry/remote/config/config.go`:
+
+```go
+func init() {
+	credentials.SetDefaultConfigLoader(func(configPath string) (credentials.ConfigFile, error) { /* ... */ })
+}
+```
+
+Three consequences:
+
+1. **Action at a distance.** Whether `credentials.NewStore` works depends on
+   whether some *other* package was linked in. A caller who imports only
+   `credentials` gets `ErrNoConfigLoader` at runtime, and the fix is to add an
+   import they do not otherwise use — the kind of thing that gets deleted by a
+   later "remove unused import" cleanup and fails in production.
+2. **Unsynchronized global.** `SetDefaultConfigLoader` writes a package variable
+   with no mutex. Set from `init()` it is safe, but the function is *exported*,
+   so any caller can rewrite it at any time from any goroutine. That is a data
+   race by construction, and it is racy across the whole process — one library
+   swapping the loader changes behaviour for every other consumer.
+3. **A ten-method interface exists only to break an import cycle.**
+   `credentials.ConfigFile` mirrors `config.Config` (`GetAuthConfig`,
+   `GetAuthConfigHierarchical`, `PutAuthConfig`, `DeleteAuthConfig`,
+   `GetCredentialHelper`, `CredentialsStore`, `SetCredentialsStore`,
+   `IsAuthConfigured`, `Path`, `Save`). Every change to config file handling now
+   has to be made in two places that must stay in sync.
+
+The underlying cause is just an import cycle: `config` needs `credentials` for
+`Credential`/`AuthConfig` types, and `credentials` needs `config` to load a
+config file.
+
+## Proposal
+
+Move the shared types into an internal package that both can import, so the
+cycle disappears and the global is unnecessary.
+
+```
+registry/remote/internal/configfile/    (new)
+    authconfig.go   — AuthConfig, DecodeAuth
+    configfile.go   — the ConfigFile interface, Load
+```
+
+- `credentials` imports `configfile` for the interface and loader.
+- `config` imports `configfile` for the same types and provides the concrete
+  implementation.
+- Neither imports the other. `init()`, `SetDefaultConfigLoader`,
+  `ConfigFileLoader`, and `ErrNoConfigLoader` are all deleted.
+
+`credentials.NewStore` becomes:
+
+```go
+func NewStore(configPath string, opts StoreOptions) (*DynamicStore, error) {
+	cfg, err := configfile.Load(configPath)
+	if err != nil {
+		return nil, err
+	}
+	return NewStoreFromConfig(cfg, opts), nil
+}
+```
+
+which works with no phantom import and no ordering dependency.
+
+`credentials.AuthConfig` and `credentials.ConfigFile` stay as thin aliases of the
+internal types so the public API does not move:
+
+```go
+type AuthConfig = configfile.AuthConfig
+type ConfigFile = configfile.ConfigFile
+```
+
+## Alternatives considered
+
+**Keep the global, add a mutex.** Fixes the race but not the action-at-a-distance
+or the duplicated interface. It also leaves an exported process-wide setter,
+which is the more consequential design problem.
+
+**Merge `config` and `credentials` into one package.** Removes the cycle
+outright, but the two have genuinely different audiences — plenty of callers want
+credential resolution without containers-registries.d parsing — and it would be a
+much larger public API change.
+
+**Have `config` own everything and make `credentials` config-free.** Arguably the
+cleanest long-term shape, but it inverts the existing dependency direction and
+would move `Store`, `DynamicStore`, and the native-helper handling. Too large for
+the current window.
+
+## Migration impact
+
+- `SetDefaultConfigLoader`, `ConfigFileLoader`, `ErrNoConfigLoader`: removed.
+  These exist only in v3 pre-release, so no released API is affected.
+- `credentials.NewStore`: unchanged signature, no longer requires the caller to
+  import `config`. This is strictly a relaxation — code that imported `config`
+  keeps working.
+- `credentials.AuthConfig`, `credentials.ConfigFile`: unchanged as far as callers
+  are concerned (type aliases).
+
+## Recommendation
+
+Do this before the v3 API freeze. Afterwards, removing an exported setter and
+an exported error becomes a breaking change, and the two-copy interface has to
+be maintained for the life of v3.

docs/design/signedby-tag-resolution.md

@@ -0,0 +1,136 @@
+# Design: `signedBy` policy evaluation for tag references
+
+Status: **proposal** — needs a decision before v3 GA.
+
+## Problem
+
+A `signedBy` policy requirement can never be satisfied when the image is
+referenced by tag.
+
+`DefaultSignedByVerifier.Verify` needs the manifest digest, because that is what
+a simple-signing payload binds to (`critical.image.docker-manifest-digest`). It
+obtains one via `parseImageDigest`, which scans the reference for `@` and errors
+out if there is none:
+
+```go
+func parseImageDigest(ref string) (digest.Digest, error) {
+	for i := len(ref) - 1; i >= 0; i-- {
+		if ref[i] == '@' { /* ... */ }
+	}
+	return "", fmt.Errorf("reference %s does not contain a digest", ref)
+}
+```
+
+But policy is evaluated *before* resolution. `Repository.Resolve` and
+`Repository.FetchReference` call `checkPolicy(ctx, reference)` with whatever the
+caller passed in — usually a tag:
+
+```go
+func (r *Repository) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error) {
+	if err := r.checkPolicy(ctx, reference); err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	// ...
+}
+```
+
+So for `registry.example.com/app:v1` under a `signedBy` policy:
+`checkPolicy` → `IsImageAllowed` → `evaluateSignedBy` → `Verify` →
+`parseImageDigest` fails → `Verify` returns an error → the evaluator returns
+`(false, err)` → the pull is denied. Every time, regardless of whether a
+perfectly valid signature exists.
+
+This fails closed, so it is not a security hole. It is a functional gap: the
+feature is unusable for the most common way people name images.
+
+## Why it is not a one-line fix
+
+The obvious move — resolve the tag first, then evaluate policy — inverts the
+current ordering, and the ordering exists for a reason: policy should be able to
+reject a request *before* the client talks to the registry about it. Scope- and
+transport-level requirements (`reject`, `insecureAcceptAnything`) are meaningful
+pre-flight; signature requirements inherently are not.
+
+There is also a re-entrancy hazard. Resolving a tag inside the verifier means
+calling back into `Repository.Resolve`, which calls `checkPolicy` again. The
+`policyCheckedKey` context marker prevents infinite recursion but only if it is
+threaded correctly through the verifier.
+
+## How containers/image handles it
+
+`containers/image` splits the decision in two. `PolicyContext.IsRunningImageAllowed`
+operates on an `UnparsedImage` that has already been fetched far enough to know
+its manifest digest, while reference-level rules are applied earlier against the
+parsed reference. Signature requirements only ever see a resolved image.
+
+## Options
+
+### 1. Two-phase policy evaluation (recommended target)
+
+Split requirements by what they need:
+
+- **Pre-resolve**: `reject`, `insecureAcceptAnything`, and any future
+  reference-shaped rule. Evaluated in `checkPolicy` as today.
+- **Post-resolve**: `signedBy`, `sigstoreSigned`. Evaluated after the descriptor
+  is known, against `ImageReference` carrying the resolved digest.
+
+Sketch:
+
+```go
+func (r *Repository) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error) {
+	if err := r.checkPolicyPreResolve(ctx, reference); err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	desc, err := r.Manifests().Resolve(withPolicyChecked(ctx), reference)
+	if err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	if err := r.checkPolicyPostResolve(ctx, reference, desc); err != nil {
+		return ocispec.Descriptor{}, err
+	}
+	return desc, nil
+}
+```
+
+Cost: the `Evaluator` needs to partition requirements and expose two entry
+points, and every mutating/reading path in `repository.go` needs the second
+call sited correctly. `Fetch` already has a digest, so it feeds the post-resolve
+phase directly.
+
+Risk to watch: a requirement set containing *only* post-resolve requirements
+must not let a pre-resolve pass be mistaken for an allow. The partition must
+track that at least one phase actually evaluated the requirement.
+
+### 2. Verifier resolves the tag itself
+
+Give `DefaultSignedByVerifier` a resolver and have it turn a tag into a digest
+on demand.
+
+Cheaper — no change to the evaluator's shape — but it puts a network call inside
+a policy verifier, needs `withPolicyChecked` threaded through to avoid
+re-entering policy, and means the digest the signature is checked against is
+fetched by a different code path than the one that will actually pull the
+content. That last point is a TOCTOU seam: the tag could move between the
+verifier's resolve and the caller's.
+
+### 3. Document `signedBy` as digest-only
+
+Make `parseImageDigest`'s failure an explicit, documented limitation, and have
+`Verify` return a clearly-worded error naming the constraint.
+
+Cheapest and honest, but it substantially reduces the feature's value — most
+users pull by tag.
+
+## Recommendation
+
+Target **option 1**. It matches containers/image semantics, avoids the TOCTOU
+seam in option 2, and is the only option under which `signedBy` is actually
+usable as specified.
+
+Ship **option 3** as the interim state in the meantime: an explicit error and a
+documented limitation are much better than the current behaviour, where a
+correctly-signed image pulled by tag is denied with a message about digest
+parsing.
+
+Shipping v3 GA with `signedBy` silently unusable for tag references is the
+outcome to avoid.