artifacts

var (
	// ErrNotFound means the channel has no such artefact-version. Usually a
	// typo or a version nobody has approved yet — the inventory is the answer.
	ErrNotFound = errors.New("artifacts: not published")

	// ErrUnverified means the bytes arrived but could not be trusted. It is
	// deliberately not more specific to the caller: a failed signature and a
	// mismatched digest are the same answer — do not use this.
	ErrUnverified = errors.New("artifacts: verification failed")

	// ErrTrustUnavailable means the trust anchors could not be established, so
	// the signature was never actually checked.
	//
	// Deliberately NOT ErrUnverified. The two demand different responses: a
	// failed signature must not be retried, and an unreachable anchor is
	// exactly the case that should be. Collapsing them meant a tool on a flaky
	// network received a permanent-looking security failure for a transient
	// condition — and the documentation told it never to retry.
	//
	// Retry it under a context with a bounded number of attempts. It is not a
	// signal that anything is wrong with the artefact, because nothing about
	// the artefact was examined.
	ErrTrustUnavailable = errors.New("artifacts: trust anchors unavailable")

	// ErrUnsigned means the artefact-version exists but no signature is
	// published beside its manifest.
	//
	// Distinct from ErrNotFound, which reads as "no such version" and sends a
	// reader to check their spelling. An unsigned publication is an incomplete
	// or interrupted one, and it is the publisher's problem rather than the
	// caller's.
	ErrUnsigned = errors.New("artifacts: published without a signature")

	// ErrWithdrawn means the channel has withdrawn this artefact-version.
	//
	// Its own sentinel, separate from index-unavailable, not-listed, a bad
	// signature and a stale index. Collapsing those loses the difference
	// between "this is dangerous" and "I could not check" — which warrant
	// opposite responses from whoever is on call.
	//
	// Terminal: a withdrawn version never returns. A correction is a new
	// version, so this is not a state to retry through.
	ErrWithdrawn = errors.New("artifacts: withdrawn")

	// ErrNotListed means the index does not mention this artefact-version.
	//
	// The index is a COMPLETE statement of what is approved, so an absent entry
	// means not approved rather than not mentioned. Distinct from ErrNotFound,
	// which is about the channel not holding bytes.
	ErrNotListed = errors.New("artifacts: not in the approved index")

	// ErrIndexUnavailable means the index could not be fetched or verified, so
	// no approval decision could be made. Like ErrTrustUnavailable it is a
	// retryable condition rather than a statement about the artefact.
	ErrIndexUnavailable = errors.New("artifacts: index unavailable")

	// ErrStaleIndex means the index verified but is too old to act on — past
	// its expiry, or older than one this client has already accepted.
	//
	// A signature proves an index was issued and says nothing about when. This
	// is the error that stops a replayed index restoring a withdrawn version.
	ErrStaleIndex = errors.New("artifacts: index is stale")

	// ErrMalformedIndex means the index verified and is not an index.
	ErrMalformedIndex = errors.New("artifacts: malformed index")

	// ErrInvalidIdentifier means a Ref or a manifest names something the
	// grammar does not admit — uppercase, Unicode, a path separator, a reserved
	// device name. Rejected rather than sanitised, because sanitising is what
	// let two distinct refs share one cache slot.
	ErrInvalidIdentifier = errors.New("artifacts: invalid identifier")

	// ErrIdentityMismatch means a correctly signed manifest describes a
	// different artefact-version from the one requested.
	//
	// Distinct from ErrUnverified and ErrNotFound on purpose. The signature is
	// genuine and the file may well be present — what is wrong is that the
	// publisher signed this manifest for something else, which is the signature
	// of a substitution or replay. Reporting it as a bad signature or a missing
	// file loses the only signal that says so.
	ErrIdentityMismatch = errors.New("artifacts: manifest describes another artefact-version")

	// ErrMalformedManifest means the manifest's signature was good but its
	// contents are not a manifest.
	//
	// Distinct from ErrUnverified on purpose. Parsing happens only AFTER the
	// signature is accepted, so reaching this means the publisher signed
	// something malformed — an operational fault in the channel, not an attack,
	// and it wants a different response from a failed signature.
	ErrMalformedManifest = errors.New("artifacts: malformed manifest")
)