BCR notation question: Content-addressed envelope references in examples

[ChristopherA]

Question

In the BCR examples (PRs #149-#156), I need to show "this envelope references another envelope by its content identifier." I've been using CID(name) as shorthand, but I can't find this defined in BCR-2026-002 (Envelope Notation).

Looking at the notation spec, I see:

• Digest(...) — for cryptographic digests
• UUID(...) — for unique identifiers
• String literals — for named subjects

What's the correct notation for examples where an envelope subject is "the envelope identified by its digest"?

For example, in supersession patterns:

{
    "Alice" [
        'foaf:knows': "Bob"
    ]
} [
    'signed': {
        Signature [
            'supersedes': Digest(abc123...)   // <-- What goes here in readable examples?
        ]
    } [
        'signed': Signature
    ]
]

Options Considered

1. Digest(abc123...) — Requires actual hex, hard to read in conceptual examples
2. "my-assertion" — Loses the semantic that it's content-addressed, not just a string label
3. Define CID as illustrative notation — Would need to be standardized

Context

This affects all 8 BCRs in PRs #149-#156, with 97 uses of CID(...) across the examples.

Is there an established pattern I'm missing, or should I propose a notation extension for this use case?

/cc @wolfmcnally

[wolfmcnally]

I deliberately designed Envelope to not need a CID-type construct. The intent was always that you refer to immutable digital objects such as envelopes by their Digest. Internally the digest is 32 bytes, but in Envelope Notation we only print the first 4 hex digits, which (absent a LifeHash) is an easy way to distinguish particular digests (and hence envelopes) with a negligible failure rate.

Digest(abc123...)   // <-- What goes here in readable examples?

The pseudocode I use in examples is like what I showed you, for instance if the original envelope to be superseded spelled "Bob" as "Bobb", then I'd call it something like Digest(alice-knows-bobb-signed) which also implies the signature is included in the digest. In almost any case where you're writing examples with multiple distinct envelopes you can just say Digest(A), Digest(B), etc. The point here is not technical accuracy but didactic effectiveness.

Now there is another path: just elide the entire envelope and then embed the elided envelope where the referent envelope goes:

'supersedes': ELIDED

Unlike Digest, this implies that the original envelope could be fit into that slot like a key into a lock. Digest implies that's not the intent. Either way, you know the exact identity of the envelope that is the referent of the assertion's object. We deliberately don't show any of the Digest under an ELIDED, but it's there, and it's identical to what Digest carries.

[ChristopherA]

This clarifies things. I've updated all 8 BCRs to use Digest(...) with descriptive names.

Here's an example — a peer endorsement with transparency disclosures (from BCR-2026-011):

{
    Digest(security-code-reviewers-endorsement) [
        'isA': 'PeerEndorsement'
        'endorsementTarget': XID(alice)
        'endorserStatement': "I reviewed 8 of their security-focused PRs. All demonstrated understanding of constant-time operations, proper key handling, and defense in depth."
        'endorserRelationship': "Project maintainer for crypto library; merged their contributions over 6 months"
        'endorsementBasis': "15 years security engineering; maintain similar libraries at 2 other organizations"
        'endorsementContext': "Cryptographic implementation and secure coding practices"
        'disclosedLimitations': "Only reviewed their crypto code; cannot speak to UI/UX or project management skills"
        'disclosedBias': "We have become professional friends through this collaboration"
        'validFrom': 2026-02-02
        'signed': Signature
    ]
}

The descriptive digest name makes it clear what the envelope represents.