Add org.hypercerts.claim.acknowledgement sidecar lexicon

[s-adamantine]

Summary

This PR introduces the org.hypercerts.claim.acknowledgement lexicon, which facilitates explicit approval for associating records (subjects) with a specific context (e.g., activity-project inclusion, collection membership).

Key Changes

New Lexicon: org.hypercerts.claim.acknowledgement for tracking approvals and association consents.
Flexible Subjects: Supports multiple subjects being approved for a single context.
Contextual Approval: Explicitly links approval to a target record via the context field.
Auto-generated Types: Updated API and TypeScript types to include the new lexicon.

Use Case Example

A user provides acknowledgement for their Hypercert Activity (subject) to be included within another user's Collection (context).

{
  "$type": "org.hypercerts.claim.acknowledgement",
  "subjects": [
    {
      "uri": "at://did:plc:abc/org.hypercerts.claim.activity/123",
      "cid": "bafy..."
    }
  ],
  "context": {
    "uri": "at://did:plc:xyz/org.hypercerts.claim.collection/456",
    "cid": "bafy..."
  },
  "given": true
}

Summary by CodeRabbit

• New Features

  • Introduced new acknowledgement capability with support for context references, consent status indication, optional comments, and creation timestamps

• Documentation

  • Updated documentation and lexicon specifications for the new acknowledgement feature

• Chores

  • Released minor version update for lexicon package

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 3a549bc

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]

Warning

Rate limit exceeded

@s-adamantine has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 18 minutes and 9 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 2a10d1c and 3a549bc.

📒 Files selected for processing (3)

• ERD.puml
• README.md
• lexicons/org/hypercerts/acknowledgement.json

📝 Walkthrough

Walkthrough

This PR introduces a new acknowledgement lexicon as a sidecar record to track acknowledgements or consents, removing the project dataclass from the schema and establishing a new data structure that shares the same TID as activity records.

Changes

Cohort / File(s)	Summary
Acknowledgement Lexicon Definition lexicons/org/hypercerts/acknowledgement.json	New lexicon file defining the acknowledgement record schema with required fields (contexts, given, createdAt), optional comment field, and sidecar pattern alignment to activity records.
Schema Model Updates ERD.puml	Replaces org.hypercerts.claim.project dataclass with org.hypercerts.acknowledgement dataclass; updates entity relationships to remove project-to-activity and project-to-location connections; introduces acknowledgement-to-activity sidecar relationship.
Documentation & Changelog .changeset/add-acknowledgement-lexicon.md, README.md	Adds changeset entry for minor release describing new acknowledgement lexicon; documents new org.hypercerts.acknowledgement sidecar with properties and sidecar pattern explanation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• adding project schema (and keeping collections consistent) #33 — Adds and expands the org.hypercerts.claim.project schema, directly inverse to this PR's removal of the project entity and introduction of acknowledgement in its place.

Suggested reviewers

• aspiers

Poem

🐰 A project becomes acknowledgement today,
With contexts and consents in a sidecar way,
Activities now nod in agreement together,
Sharing one TID through the lexicon tether! ✨

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Lexicon Documentation Sync	❌ Error	README.md line 442 references project acknowledgements, but JSON schema and ERD only define collection contexts, creating documentation-code inconsistency.	Remove 'projects' reference from README.md line 442 to align documentation with actual schema and ERD constraints.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main change: adding the org.hypercerts.acknowledgement sidecar lexicon to track acknowledgements and consents.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Lexicons Styleguide Compliance	✅ Passed	The acknowledgement.json lexicon file complies with the atproto lexicon style guide with valid ID, version, clear descriptions, and comprehensive property documentation.

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@ERD.puml`:
- Around line 321-323: The ERD references an undefined entity: change the
invalid relation "acknowledgement::contexts --> project" to point at the correct
sidecar entity or remove it; specifically update the acknowledgement::contexts
relation to reference collectionProject if acknowledgement contexts should
target the former project sidecar, otherwise delete the
acknowledgement::contexts --> project line so acknowledgement::contexts only
links to existing entities like collection.

In `@README.md`:
- Around line 641-642: Remove the duplicate horizontal rule in README.md by
deleting one of the two consecutive '---' separators so only a single horizontal
rule remains; locate the consecutive '---' entries and remove the redundant one
to restore proper section separation.

🧹 Nitpick comments (1)

ERD.puml (1)

192-214: Consider adding sidecar relationships to collection entity for consistency.

The acknowledgement entity shows an explicit sidecar relationship to activity (line 321), but the collection sidecar entities (collectionLocation, collectionProject, collectionHyperboard) don't show their relationship to the collection entity.

For diagram clarity and consistency, consider adding dotted relationships:

collectionLocation .. collection : "sidecar (same TID)"
collectionProject .. collection : "sidecar (same TID)"
collectionHyperboard .. collection : "sidecar (same TID)"

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Remove duplicate horizontal rule.

There are two consecutive --- separators here.

✏️ Proposed fix

 **Sidecar Pattern**: This record shares the same TID as its parent collection record but uses a different collection namespace. This allows hyperboard-specific user/contributor displays to be added to collections for sponsorship billboard functionality.
 
 ---
 
----
-
 ### org.hypercerts.acknowledgement (Sidecar)

🤖 Prompt for AI Agents

In `@README.md` around lines 641 - 642, Remove the duplicate horizontal rule in
README.md by deleting one of the two consecutive '---' separators so only a
single horizontal rule remains; locate the consecutive '---' entries and remove
the redundant one to restore proper section separation.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@README.md`:
- Around line 452-465: The README's acknowledgement sidecar text mentions
"collections or projects" but the ERD/schema only links
acknowledgement::contexts to collections; update to keep docs and schema aligned
by either (A) removing "projects" from the Sidecar Pattern and the Properties
description for the contexts field (`contexts`, `acknowledgement::contexts`) so
it only references collections, or (B) extend the ERD/schema to permit project
targets and document that change (update `acknowledgement::contexts` schema and
any ERD links to include project target type). Locate the `contexts` property
and the "Sidecar Pattern" paragraph in the README and apply the chosen
consistent change.