Module error 

Typed errors for content-addressing operations.

Every fallible operation in this crate returns ContentError. We use thiserror (not anyhow) so callers can match on the exact failure mode — encoding, decoding, verification, non-canonical input, or CID parsing — and so the error type stays part of the crate’s public contract.

Operation → variant map (FROZEN at 0.1.0)

This table is the legible contract: which operation can produce which variant. It is part of the frozen 0.1.0 error surface (README gate item #7) — adding a new operation/variant pair later is allowed (the enum is #[non_exhaustive]), but the rows below will not change meaning.

Rows added since the freeze (the additive path this note reserves): from_canonical_dagcbor_checked and ContentAddressable::from_canonical_form in 0.1.2 (issue #90), which is also what introduced LossyDecode — the first exercise of the #[non_exhaustive] decision below, and exactly the case it was kept for. (from_canonical_form is additionally the one deliberate stability exception 0.1.2 makes to the frozen 0.1.x Rust API; see docs/STABILITY.md. The error surface itself is unchanged apart from the added variant.)

Operation	Variant(s) it can return
to_canonical_dagcbor	EncodingError
from_canonical_dagcbor (deprecated 0.1.2)	DecodingError — and nothing else, which is the defect that deprecated it: it verifies neither canonicality nor the typed round trip
from_canonical_dagcbor_checked	DecodingError (not dag-cbor, or not a T), NonCanonical (valid but non-canonical bytes), LossyDecode (the decoded value’s to_canonical_dagcbor differs from the input), EncodingError (a re-encode failed)
ContentAddressable::from_canonical_form	the same four, with the last two arising from canonical_form rather than from to_canonical_dagcbor — plus anything else a custom canonical_form returns, propagated verbatim
ContentId::from_canonical_bytes_checked	DecodingError (not dag-cbor), NonCanonical (valid but non-canonical), EncodingError (re-encode failed)
ContentId::from_bytes / FromStr / TryFrom<Cid> / binary Deserialize	InvalidCid (not a CID at all) or InvalidCidProfile (a valid CID that is not the frozen profile)
content_id	propagates canonical_form’s error only (typically EncodingError)
verify	propagates content_id only; a mismatch is Ok(false), never an Err
ensure_content_id	propagates content_id, plus VerificationFailed on mismatch
from_canonical_bytes / from_blake3_content_digest	infallible — never returns an error

Frozen freeze decisions (0.1.0)

• #[non_exhaustive] is retained on purpose so a future variant (e.g. an UnsupportedCodec / DigestLength) can be added without a major version bump. Callers already must carry a _ => … arm. Do not remove it to chase exhaustive matching — that would forfeit additive evolution.
• No #[from] impls. Auto-From conversions are deliberately not provided: a #[from] bakes the source type into the public contract just as firmly as a field, and the two codec sources are exactly the unstable serde_ipld_dagcbor generics we hide behind a boxed dyn Error (see below). Construction stays explicit via map_err at the call sites. Do not “helpfully” add a #[from] — it re-leaks the generics into the frozen API.
• The codec source types are boxed. EncodingError/DecodingError carry their #[source] as a Box<dyn std::error::Error + Send + Sync + 'static> rather than the concrete serde_ipld_dagcbor::EncodeError<…> / DecodeError<…>. This keeps .source()/{source} diagnostics while decoupling the frozen signature from a codec-crate patch bump that changes those generics.

Enums

ContentError

The error type returned by all fallible operations in this crate.