Problem
`docs/building/schemas-and-sdks.mdx` lines 29-30 describe the protocol tarball sidecars (`.tgz.sig` and `.tgz.crt`) as if they're always available alongside any `{version}.tgz`. They're not — sidecars are produced only by the cosign step in `release.yml`, which fires on changeset version bumps. When a release happens out of band (e.g. a maintainer-triggered re-cut, an emergency artifact replacement), the `.tgz` lands on the CDN before `.sig` / `.crt` do.
A user following the table for an arbitrary version expecting `{version}.tgz.sig` to 200 will hit a 404 in that window. The SDK sync's `verifyCosignSignature` handles the 404 gracefully (logs "checksum-only trust — upstream predates signing" and proceeds), so this isn't user-breaking — but the docs should still be honest about it.
Surfaced by code-reviewer during pre-merge review of #3125.
Proposal
Add a one-line caveat next to the sidecar URLs in the table:
`{version}.tgz.sig` / `{version}.tgz.crt` — Sigstore signature + certificate. Generated by the cosign step in `release.yml` on each changeset version bump. Absent for some windows (out-of-band republishes, ongoing deploys); the sync flow falls back to checksum-only trust on 404.
Or factor a small "Sidecar availability" section under the table for a fuller treatment.
Out of scope
- Changing the actual cosign signing flow
- Promoting checksum-only trust to a permanent option
References
Problem
`docs/building/schemas-and-sdks.mdx` lines 29-30 describe the protocol tarball sidecars (`.tgz.sig` and `.tgz.crt`) as if they're always available alongside any `{version}.tgz`. They're not — sidecars are produced only by the cosign step in `release.yml`, which fires on changeset version bumps. When a release happens out of band (e.g. a maintainer-triggered re-cut, an emergency artifact replacement), the `.tgz` lands on the CDN before `.sig` / `.crt` do.
A user following the table for an arbitrary version expecting `{version}.tgz.sig` to 200 will hit a 404 in that window. The SDK sync's `verifyCosignSignature` handles the 404 gracefully (logs "checksum-only trust — upstream predates signing" and proceeds), so this isn't user-breaking — but the docs should still be honest about it.
Surfaced by code-reviewer during pre-merge review of #3125.
Proposal
Add a one-line caveat next to the sidecar URLs in the table:
Or factor a small "Sidecar availability" section under the table for a fuller treatment.
Out of scope
References