multihash as the unifying substrate: subsume kyln / nessie / agent-mesh / agent-store BLAKE3 conventions

[hartsock]

Summary

Decide how content-addressable uses multihash / multicodec / multibase to subsume the other BLAKE3 identifier conventions in the workspace (kyln-core, nessie-store, agent-mesh-protocol envelope, agent-store), so that every consumer speaks this crate's real CIDv1 and the crate becomes the single home of content identity — which is why the crate exists.

This is a design issue, not a bug: nothing is broken, but four wire-compatible yet API/text-incompatible conventions coexist, and agent-bridle is about to lean on content identity for artifact authority + evidence (agent-bridle ADR 0028 sketch, in flight). That work should not be the fifth convention.

The four conventions today (verified 2026-08-16)

Where	Binary form	Text form	Codec	Hash algos	Structured-value canonicalization
content-addressable (ContentId)	real CIDv1 via cid/multihash crates	multibase base32-lower b… (frozen); digest_hex() = bare 64-hex (frozen)	dag-cbor 0x71 — "fixed forever for 0.1.x, not selectable" (README "Alpha status" §3)	BLAKE3-256 only (0x1e, 32 bytes)	canonical dag-cbor (to_canonical_dagcbor)
kyln-core (ContentId / crypto::Cid)	hand-rolled [0x01, 0x55, 0x1e, 0x20, digest] — byte-identical to a spec CIDv1(raw, blake3-256) (kyln-core/src/crypto.rs:165-201, all varints single-byte)	to_hex() = hex of the whole CID envelope (content_id.rs:70-72) — i.e. multibase base16 minus the f prefix	raw 0x55	BLAKE3 (0x1e); codes for sha256/512 exist	ciborium CBOR w/ BTreeMap ordering (content/canonical.rs), not dag-cbor; ObjectId in the store = bare digest
nessie-store (Digest)	to_multihash_bytes() = spec multihash <code><len><digest> (nessie-backend-core/src/digest.rs:158-190)	"<algo>:<hex>" with multiformats names blake3 / sha2-256 (digest.rs:71-75)	none (no CID envelope)	BLAKE3 (0x1e) and SHA-256 (0x12) first-class — REAPI face pins SHA-256	bespoke domain-tagged length-delimited (nessie.Tree.v1, nessie.ActionResult.v1, nessie.Attestation.v1)
agent-mesh-protocol envelope payload_cid, Fingerprint; agent-store content_hash	bare [u8; 32] BLAKE3	hex via blake3::Hash::to_hex	none	BLAKE3	n/a (opaque payload bytes / chained log)

Related, already in this crate: from_blake3_content_digest([u8;32]) is the guarded no-rehash door for BLAKE3-native upstreams (README lines 35-45), but it stamps 0x71, and the doc rightly warns that stamping dag-cbor on non-dag-cbor content mints a CID whose codec "is a lie" (content_id.rs:158-166). #53 (chunked-dag) explicitly defers "a deliberate raw-leaf profile decision" as a follow-up. agent-mesh-protocol's authority/provenance module already depends on this crate for typed CIDs (AuthorityId/GrantId), while its envelope layer still uses bare 32-byte digests.

What multiformats already give us (the good news)

• Binary: every one of the four is already a valid multihash payload; kyln's is already a valid CIDv1. Nothing needs re-hashing to become spec-conformant.
• Text: kyln hex is f + hex; nessie blake3:<hex> ↔ multihash(0x1e, hex); bare-digest-hex is this crate's digest_hex(). FromStr already tolerates non-base32 multibases "as a convenience, not a contract" (README §2).
• Algorithm agility: multihash's code byte is exactly the seam for nessie's SHA-256 peer and for kyln's sha256/512 codes, without changing what ContentId mints.

So the divergences that remain are policy, not encoding: codec (0x71 vs 0x55 vs none), text form, which algorithms may be minted vs merely verified, and canonicalization of structured values.

Questions to decide

1. Raw-leaf profile. Do we add a second frozen typed identifier — e.g. RawContentId (CIDv1, raw 0x55, BLAKE3-256, 32) — for byte artifacts (files, chunks, envelope payloads, log lines), alongside ContentId for dag-cbor values? kyln's ContentId would then be byte-identical to it and could migrate by type swap; agent-mesh/agent-store bare digests would wrap into it losslessly. Or do we keep exactly one profile and require artifacts to be ChunkLeaf { kind, data: bytes } dag-cbor nodes (feat(chunked-dag): chunked file + directory DAG (sized links) #53's MVP stance), so every CID stays 0x71? Trade-off: one profile = one presentation contract, but every foreign raw CID becomes "foreign forever"; two profiles = kyln/agent-mesh subsumed at zero cost, but the frozen-surface grows (does that violate FREEZE-MINIMALLY, or is an additional type outside the "0x71 fixed forever" clause because that clause is about ContentId?).
2. Verified-import of foreign CIDs. A Cid-parsing entry (ContentId::try_from_cid / an AnyCid enum) that classifies by (codec, hash code): dag-cbor+blake3 → ContentId; raw+blake3 → RawContentId (if adopted); anything else (e.g. raw+sha2-256 from REAPI) → verifiable-not-mintable interop value. This is how nessie's SHA-256 world is represented here without this crate ever minting SHA-256.
3. Text-form policy. Canonical stays base32-lower b…. Do we bless explicit to_multibase(Base)/from_multibase and document the legacy parsers (kyln envelope-hex = base16 sans prefix; nessie algo:hex) behind a default-off legacy-formats feature with a deprecation path, or refuse them and make consumers convert at their edge?
4. Structured-value canonicalization. kyln's ciborium canonical CBOR and nessie's bespoke length-delimited encodings mint different CIDs from dag-cbor for the same logical value. Migrating them is a re-naming ceremony (identity moves). Do we (a) provide to_canonical_dagcbor + conformance vectors as the target and let each repo migrate, (b) additionally offer nessie's Tree/ActionResult and kyln's ProvenanceLink as shapes in this crate (feat(chunked-dag): chunked file + directory DAG (sized links) #53 DirNode/FileNode already covers Tree), so the migration is "depend on the crate" rather than "re-implement"?
5. The from_blake3_content_digest door. After (1), should it be re-pointed at the raw profile (where a bare content digest is honest) and the 0x71 variant restricted to callers who know the digest is over canonical dag-cbor?

Proposed acceptance

• One decision record (this crate's ADR style, feat(formal): algebra-of-laws encoding decision records (ADRs) #40) answering 1–5.
• Conformance vectors for whatever is added (tests/vectors.json discipline, test: golden conformance vectors + Rust↔Python byte-parity gate #12/feat(merkle): conformance vectors freeze structure bytes at rc1 #33/feat(conformance): portable vectors + TS/Dart/Java byte-identity #35): at minimum a kyln envelope-hex ↔ RawContentId/Cid round-trip vector and a nessie sha2-256:<hex> ↔ multihash vector.
• A migration checklist per consumer: kyln-core, nessie-store, agent-mesh-protocol envelope, agent-store — each ends with content-addressable as its identity dependency and no local hash/CID types.
• agent-bridle ADR 0028 (artifact authority + evidence) cites the outcome as its identity contract rather than choosing a codec locally.

Non-goals

• Changing ContentId's frozen profile (BLAKE3-256 / dag-cbor 0x71 / 32 bytes / v1) or its presentation contract.
• Minting SHA-256 CIDs in this crate.
• Anything about the ADR-0025 branch in agent-bridle; this is about the crate as the shared substrate, not that document.

[hartsock]

Resolution (decided 2026-08-16)

Reframing first, because it decides everything else: there are not four incompatible content-addressing systems here — there are four policies sitting on essentially compatible multiformats machinery. What differs is codec semantics, canonicalization, textual presentation, and minting policy. So content-addressable becomes the shared identity algebra without becoming the shared storage implementation. That is the boundary.

The five questions, answered

1. Raw profile — YES. Two first-class, typed profiles, not one polymorphic type:

ContentId     = CIDv1(dag-cbor, blake3-256)   identity of canonical structured values
RawContentId  = CIDv1(raw,     blake3-256)   identity of opaque byte strings / artifacts

Forcing artifacts through dag-cbor is tidy but semantically wrong: CID(dag-cbor, blake3(encode(ChunkLeaf{kind, data}))) is the identity of a representation containing the artifact, not of the artifact. When Bridle says "authority X permits artifact Y", Y must identify the thing whose authority is being discussed, not a wrapper. This does not violate FREEZE-MINIMALLY: the frozen statement "ContentId means CIDv1 + dag-cbor + BLAKE3-256" remains exactly true; we add a second theorem "RawContentId means CIDv1 + raw + BLAKE3-256". Explicitly not doing ContentId { codec, hash } — that moves semantics from the type into runtime state.

2. Foreign verification — YES. A codec/hash-aware verified type that can represent identities the crate refuses to mint:

enum VerifiedCid {
    Content(ContentId),
    Raw(RawContentId),
    Foreign(Cid),      // parsed + verified, not mintable here (sha2-256/REAPI, …)
}

                 CIDv1
                   │
          ┌────────┴────────┐
       mintable          verifiable
          │                 │
    ┌─────┴─────┐           │
 dag-cbor      raw        foreign codec/hash
 BLAKE3       BLAKE3      combinations
    │           │           │
ContentId  RawContentId   SHA-256, REAPI, …

Algorithm agility in the verifier, no algorithm ambiguity in the minter.

3. Text — canonical output only; liberal verified input at the edges. Emit base32-lower b… only. Legacy readers (kyln CID-envelope hex, blake3:<hex>, sha2-256:<hex>, bare digest hex) live behind explicit adapters, e.g. legacy::kyln::parse, legacy::nessie::parse, legacy::bare_blake3::parse — never taught to ContentId::from_str. Migration conveniences must not become permanent wire protocol.

4. Canonicalization — standardize dag-cbor + vectors; do NOT absorb domain schemas. Dependency direction stays content-addressable ← {kyln, nessie, agent-mesh} ← agent-bridle. This crate owns the algebra of identity, canonical serialization primitives/profiles, parsing, verification, conformance vectors. DirNode/FileNode are defensible (generic DAG shapes); nessie ActionResult and kyln ProvenanceLink are not — they stay in their domains. Otherwise this crate wakes up as libgilamonster.

And the hard part is named honestly: moving a logical object from an old canonicalization to canonical dag-cbor is an identity migration, not a serialization migration — anything referencing CID A does not reference CID B. Model it explicitly:

IdentityMigration { from: VerifiedCid, to: ContentId /* or RawContentId */, reason: MigrationKind }

signed/attested where appropriate. That becomes useful to provenance systems later.

5. from_blake3_content_digest — move/deprecate in favor of the honest raw profile. RawContentId::from_blake3_digest(..) is honest. If a dag-cbor digest constructor must exist it is explicit and lower-level (ContentId::from_dag_cbor_digest(..), asserting dag-cbor semantics in its name). The normal API stays ContentId::from_canonical_value(&v) / RawContentId::from_bytes(bytes) so callers rarely inject digests.

6. A law to freeze

CID profile is semantic, not cosmetic. Codec + multihash algorithm + digest jointly constitute identity. RawContentId(digest X) never compares equal to ContentId(digest X), even though the digest bytes match. Different profiles never compare equal merely because their digests do.

Corollary for consumers: authorization compares typed, normalized CID bytes — ArtifactRef<RawContentId> → canonical CID bytes — never textual forms. This closes the whole "same digest, different interpretation" bug family at the OCAP boundary.

Sequencing

Do this before artifact authority lands (agent-bridle ADR 0028, PR Gilamonster-Foundation/agent-bridle#381). Once capability grants carry artifact identities, changing what those identities mean gets expensive.

Deliverables (unchanged from the acceptance section, now concrete)

• Decision record in this crate's ADR style (feat(formal): algebra-of-laws encoding decision records (ADRs) #40) capturing 1–6.
• RawContentId + VerifiedCid (+ legacy::* adapters behind a default-off feature), with conformance vectors: kyln envelope-hex ↔ RawContentId round-trip; sha2-256:<hex> ↔ multihash ↔ VerifiedCid::Foreign; a profile-inequality vector (Raw(X) != Content(X)).
• Deprecation of from_blake3_content_digest with the replacement named.
• Per-consumer migration checklist (kyln-core, nessie-store, agent-mesh-protocol envelope, agent-store), each ending with content-addressable as its only identity dependency and IdentityMigration records where identities move.

[hartsock]

Implementation PR: #85 (RawContentId, VerifiedCid, law 6, unstable-legacy adapters, unstable-migration IdentityMigration, raw vectors + PyO3 face, ADR 0003). Consumer migrations (kyln-core, nessie-store, agent-mesh envelope, agent-store) are the follow-up checklist in the ADR.