Summary

Make recipe-evidence verification pin on the content digest and stop defaulting
evidence pushes to a shared :v1 tag — so a committed pointer stays verifiable
regardless of registry tag drift, and distinct attestations never collide on one
tag. Includes the doc clarifications that motivated the change.

Motivation / Context

aicr evidence verify pulled the OCI artifact by the pointer's bundle.oci
tag, then checked the pulled digest against bundle.digest. Because tags are
registry-rewritable, a later push to the same tag floated it to a different
artifact and broke re-verification of any already-committed pointer (the pull
returned the new artifact; the digest check then failed). The push side made this
worse: every tag-less --push defaulted to a shared :v1, so unrelated recipes
collided on one tag immediately. Users and agents also tended to copy the
human-readable bundle.oci tag into verify, which refuses tag-only refs.

Fixes: N/A
Related: N/A

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Documentation update

Component(s) Affected

• Docs/examples (docs/, examples/)
• Other: pkg/evidence (recipe-evidence emit + verify)

Implementation Notes

• Verifier (pkg/evidence/verifier/fetch.go): when the pointer carries a
  content digest, materializeFromPointer now pulls by digest
  (registry/repo@sha256:… derived from bundle.oci via the new
  pointerPullRef), not by the tag — so the exact attested bytes are fetched even
  if the tag has since moved. The post-pull digest cross-check stays as
  defense-in-depth. The no-digest path (local pointer + --bundle) is unchanged.
• Emitter (pkg/evidence/attestation): dropped the :v1 default. When
  --push omits a tag, the emit/publish orchestration derives a unique per-recipe
  tag, <recipe-slug>-<fingerprint>, where the fingerprint is the first 12 hex of
  the bundle's manifest digest (deterministic, not random). An operator-supplied
  tag is still honored.
• Behavior change to note: the exported attestation.Push now returns
  ErrCodeInvalidRequest if handed a tag-less reference instead of silently
  defaulting — tag derivation is the orchestration layer's responsibility
  (effectiveEvidenceRef). Both real flows (validate --emit-attestation and
  evidence publish) derive a tag first, so this only affects direct API callers.
• Docs: the CLI reference, demo, validation, and recipe-development guides now
  explain that the sha256: digest is the canonical pin (verify pulls by digest),
  the tag is a human-readable label, and aicr auto-derives a unique one.

Testing

go test ./pkg/evidence/... ./pkg/cli/...      # pass
go vet ./pkg/evidence/...                     # clean
golangci-lint -c .golangci.yaml run ./pkg/evidence/attestation/... ./pkg/evidence/verifier/...  # 0 issues
./tools/check-docs-mdx                        # OK

New tests: pointerPullRef (digest-pinning, tag drop, passthrough, invalid ref);
deriveEvidenceTag / sanitizeOCITag / manifestFingerprint; Push tag-required
error. Per-package coverage: pkg/evidence/attestation 72.8%, pkg/evidence/verifier
64.7% (new functions covered).

Risk Assessment

• Medium — Touches the evidence trust path (verify fetch + push tag) and
  changes an exported function's contract (Push now requires a tag).

Rollout notes: Backward-compatible for existing committed pointers — they carry
bundle.digest, so verification now pulls by digest (and can even re-verify
pointers whose tag had drifted, as long as the digest still resolves). No pointer
schema change.

Checklist

• Tests pass locally (make test equivalent on affected packages, with -race via go test)
• Linter passes (golangci-lint, 0 issues)
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality
• I updated docs for the user-facing behavior change
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)