[HYPER-536] feat(lexicons): add app.certified.graph.entityFollow - #235
[HYPER-536] feat(lexicons): add app.certified.graph.entityFollow#235aspiers wants to merge 2 commits into
Conversation
Add a follow record that targets a record rather than an account. The new lexicon is structurally identical to app.certified.graph.follow (same `key: tid`, same `createdAt`, optional `via` strongRef, and optional `signatures` fields). The only difference is `subject`, which is a string with `format: at-uri` referencing the record being followed, instead of a string with `format: did` identifying an account. This lets clients express "follow this activity/claim/ collection" alongside the existing "follow this account" relationship without overloading the meaning of graph.follow. Because `subject` is an unconstrained at-uri, an entity follow may reference a record in any collection, including one governed by a lexicon outside this repository. Consumers should resolve the referenced record before assuming a particular shape. Register the NSID in the app.certified.authWrite permission set. Note this widens the effective grant of an already-consented set; see docs/design/permission-sets.md for the set-growth semantics. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: 3835a1a The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
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 |
|
Warning Review limit reached
Next review available in: 50 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds ChangesEntity Follow
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error)
✅ Passed checks (6 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@ERD.puml`:
- Around line 205-213: The non-facet optional signatures property is missing
from the entity-follow documentation. In ERD.puml lines 205-213, update
entityFollow to include signatures? and adjust the nearby omission rationale if
necessary; in .agents/skills/building-with-hypercerts-lexicons/SKILL.md lines
468-496, explicitly document the optional signatures property.
In `@README.md`:
- Line 49: Correct the relationship-map legends so scalar DID/AT-URI references
are distinguished from strongRef or union references: update the legend at
README.md line 49 and apply the equivalent correction at
.agents/skills/building-with-hypercerts-lexicons/SKILL.md line 333, preserving
the entityFollow.subject scalar at-uri representation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 50c58e0f-4be0-4a84-b5aa-4b29db9772fe
📒 Files selected for processing (8)
.agents/skills/building-with-hypercerts-lexicons/SKILL.md.changeset/add-graph-entity-follow.mdERD.pumlREADME.mdSCHEMAS.mdlexicons/app/certified/authWrite.jsonlexicons/app/certified/graph/entityFollow.jsontests/validate-graph-entity-follow.test.ts
The lexicon-map legend claimed every arrow is a `strongRef` or union reference, but two arrows are scalar identifiers: `graph/follow` points at an account via a `did` string, and the new `graph/entityFollow` points at a record via an `at-uri` string. Adding the entityFollow arrow turned a latent inaccuracy into a pattern, so correct the claim in both README.md and SKILL.md rather than describing only the new arrow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| "subject": { | ||
| "type": "string", | ||
| "format": "at-uri", | ||
| "description": "AT-URI of the entity record being followed." | ||
| }, |
There was a problem hiding this comment.
The other way of doing this is an open union, as proposed by @Ashex in #236. That would allow follows to be not just weak refs but also strongRefs and anything else people want. That may or may not be practically useful - I'm not sure at this point, but I guess the point is that with an open union we don't have to know or care right now because it's always expandable later. The only minor downside is that it then needs to be wrapped in an object.
|
Superseded by #236. |
Summary
Adds
app.certified.graph.entityFollow— a follow record that targets a record rather than an account.It is structurally identical to
app.certified.graph.follow(samekey: tid, samecreatedAt, optionalviastrongRef, and optionalsignaturesfields). The only difference issubject:graph.followgraph.entityFollowsubjectstring/format: didstring/format: at-uriThis lets clients express "follow this activity/claim/collection" alongside the existing "follow this account" relationship, without overloading the meaning of
graph.follow.Notes for reviewers
subjectis an unconstrainedat-uri. An entity follow may therefore reference a record in any collection — including one governed by a lexicon outside this repository. Consumers should resolve the referenced record before assuming a particular shape, and treat the collection portion of the URI as untrusted input. Flagging this explicitly in case a narrower constraint is preferred.Permission set growth. The new NSID is added to
app.certified.authWrite, so apps already holdinginclude:app.certified.authWritegain create/update/delete on the new collection once the updated set is published. Perdocs/design/permission-sets.md, this widening is silent on the OAuth path — no re-consent is triggered. That is the documented and intended behaviour of set growth, but it is a consent-surface change and worth a deliberate look.ERD arrow is representative, not exhaustive. Since
subjectcan point at any record,entityFollow::subject --> activityis drawn to keep the diagram readable rather than fanning an arrow out to every record type. A comment inERD.pumlsays so.Changes
lexicons/app/certified/graph/entityFollow.jsonlexicons/app/certified/authWrite.jsontests/validate-graph-entity-follow.test.tsERD.pumlentityFollownode + arrowREADME.md,SKILL.mdSCHEMAS.md.changeset/add-graph-entity-follow.mdminorNew exports:
GRAPH_ENTITY_FOLLOW_NSID,GRAPH_ENTITY_FOLLOW_LEXICON_JSON,GRAPH_ENTITY_FOLLOW_LEXICON_DOC, and theAppCertifiedGraphEntityFollowtype namespace.Testing
npm run checkpasses: 196/196 tests, up from 182 onmain.That is 10 new tests in
validate-graph-entity-follow.test.ts, plus 4 doc-snippet tests auto-generated from the code blocks added toREADME.md/SKILL.md.The test worth noting asserts that a bare DID is rejected as
subject— confirming theat-uriformat genuinely distinguishes this lexicon fromgraph.followat validation time, rather than only documenting the intent. A companion test asserts an out-of-repo collection (app.bsky.feed.post) is accepted.The
git diff --exit-codeSCHEMAS.md gate is also clean.🤖 Generated with Claude Code
Summary by CodeRabbit