docs: document content-addressed record key format on activity

[holkexyz]

Summary

• Record-level description on activity now documents the expected record key format: a content-addressed identifier in the pattern hc2:{sha256}, where the SHA-256 hash is computed from the complete claim content.

Why

The activity schema uses "key": "any" rather than the typical "key": "tid", but the reason and expected format were undocumented. In practice, hypercert record keys follow a content-addressing scheme (hc2:{sha256}) that binds the key to the claim content, preventing duplicate claims and enabling content-based lookups. Documenting this in the schema description ensures implementers use the correct key format rather than arbitrary strings or TIDs.

Test plan

• npm run check passes

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 0346d2b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hypercerts-org/lexicon	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 908d438c-79e4-42d9-902a-664dfdde7948

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/activity-record-key-format

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[aspiers]

See https://linear.app/hypercerts/issue/HYPER-124/decide-way-forward-for-hypercerts-id where I've commented on this.

[aspiers]

If we do go for this scheme (which I'm less enthusiastic about these days), then we would need to include a link to a public spec for exactly how to compute that hash. The SDK offers a reference implementation but it would need to be possible to implement that in any language.

[aspiers]

Converted to draft because we need to decide (quickly!) whether to stick with any and document the reasons why, or switch to tid. Tracking the decision in https://linear.app/hypercerts/issue/HYPER-124/decide-way-forward-for-hypercerts-id

[s-adamantine]

During the call yesterday with Holke, Adam, Ken and I:

• We discussed that relying on hc2-style content-addressed IDs in the record key is not enforceable at the protocol level: apps can put any value there, and the PDS only enforces uniqueness per repo, not format.
• Because of that, documenting hc2 as “the” expected record key format would give a false sense of reliability; it cannot be treated as a guaranteed, global identifier.
• Decision direction: don’t encode this hc2 expectation into the activity description; instead, plan to derive stable identifiers via indexers or other layers (and revisit global IDs/tokenization separately).
• A globally unique identifier will be more relevant if/when we decide to tokenize the certs.

[aspiers]

See also https://www.notion.so/rkey-for-org-hypercerts-claim-activity-337d7a3bc90d80c49e5bf653d4f374ba