spec: Clarify Referrers Tag Schema vs. alternative algorithms

From the referenced OCI spec:

  digest                ::= algorithm ":" encoded
  algorithm             ::= algorithm-component (algorithm-separator algorithm-component)*
  algorithm-component   ::= [a-z0-9]+
  algorithm-separator   ::= [+._-]
  encoded               ::= [a-zA-Z0-9=_-]+

But from the distribution-spec:

  Throughout this document, `<reference>` as a tag MUST be at most 128 characters in length and MUST match the following regular expression:

  `[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}`

Happily, the fist character of algorithm must match
algorithm-component, and its [a-z0-9] a subset of the tag regexp's
opening [a-zA-Z0-9_].  And the colon separating algorithm from encoded
was already addressed in the outgoing text.  But the digest definition
also allows + in the algorithm-separator and = in the encoded portion,
which the tag regexp does not allow, so with the incoming wording I'm
requiring that to be replaced by a - as well, so clients make
consistent choices when deciding how to handle that character while
forming distribution-spec referrer tags.

We need some overall truncation to keep the tag under 128 characters,
again so clients make consistent choices when trying to compress from
the strings the digest specification allows to the strings tags allow.
There is no requirement in the distribution spec as far as I can tell
that registries support tags up to 128 characters, but given that the
spec explicitly requires clients to not exceed that length, it seems
likely that registries will allow tags of that length, and not require
further truncation.

I'm requiring clients to truncate the algothim to 32 characters and
the encoded section to 64 characters, because that's one possible
reading of the outgoing "limit of 64 characters" parenthetical, at
least one client had implemented it that way [1], and Brandon
explicitly requested the 32-and-64 approach [2].

And clients are obviously free to create whatever tags they like that
the registry will accept.  The MUST I'm adding does not forbid that.
It only clarifies the single distribution-spec Referrers Tag
associated with a given digest, because if there could be multiple
Referrers Tag for each digest, all distribution-spec
referrer-retrieving clients would have to iterate over that whole set
of possibilities, in case some distribution-spec referrer-pushing
client happened to use one of that digest's other Referrers Tag
formats.

[1]: https://github.com/regclient/regclient/blob/dbb1434fd4b8b650983e8c51933789712e05eeaa/types/referrer/referrer.go#L157
[2]: #563 (review)

Signed-off-by: W. Trevor King <[email protected]>

spec.md

@@ -721,14 +721,17 @@ A client querying the [referrers API](#listing-referrers) and receiving a `404 N
 
 ##### Referrers Tag Schema
 
-```text
-<alg>-<ref>
-```
+The Referrers Tag associated with a [Content Digest](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md#digests) <sup>[apdx-3](#appendix)</sup> MUST match the Truncated Algorithm, a `-` character, and the Truncated Encoded section, with any characters not allowed by [`<reference>` tags](#pulling-manifests) replaced with `-`.
+The Truncated Algorithm associated with a Content Digest MUST match the digest's `algorithm` section truncated to 32 characters.
+The Truncated Encoded section associated with a Content Digest MUST match the digest's `encoded` section truncated to 64 characters.
 
-- `<alg>`: the digest algorithm (e.g. `sha256` or `sha512`)
-- `<ref>`: the digest from the `subject` field (limit of 64 characters)
+For example, the following list maps `subject` field digests to Referrers Tags:
 
-For example, a manifest with the `subject` field digest set to `sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` in the `registry.example.org/project` repository would have a descriptor in the referrers list at `registry.example.org/project:sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`.
+| Digest | Truncated Algorithm | Truncated Encoded | Referrers Tag |
+| ------ | ------------------- | ----------------- | ------------- |
+| sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha256 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
+| sha512:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha512 | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa | sha512-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa |
+| test+algorithm+using+algorithm+separators+and+lots+of+characters+to+excercise+overall+truncation:alsoSome=InTheEncodedSectionToShowHyphenReplacementAndLotsAndLotsOfCharactersToExcerciseEncodedTruncation | test+algorithm+using+algorithm+s | alsoSome=InTheEncodedSectionToShowHyphenReplacementAndLotsAndLot | test-algorithm-using-algorithm-s-alsoSome-InTheEncodedSectionToShowHyphenReplacementAndLotsAndLot |
 
 This tag should return an image index matching the expected response of the [referrers API](#listing-referrers).
 Maintaining the content of this tag is the responsibility of clients pushing and deleting image manifests that contain a `subject` field.