feat: add app.certified.graph.follow lexicon by s-adamantine · Pull Request #209 · hypercerts-org/hypercerts-lexicon

s-adamantine · 2026-05-05T11:39:36Z

Adds a social-graph follow record under the app.certified namespace that is schema-compatible with app.bsky.graph.follow:

same record key (tid)
same required fields (subject: did, createdAt: datetime)
same optional via field (com.atproto.repo.strongRef)
same lexicon description

This lets feed-builders and view services index certified.app follows with the same logic they already use for Bluesky follows, and gives the certified.app ecosystem a primitive social graph.

Also includes:

generated TypeScript types and exports (GRAPH_FOLLOW_NSID, GRAPH_FOLLOW_LEXICON_JSON / DOC, AppCertifiedGraphFollow)
8 validation tests in tests/validate-graph-follow.test.ts
regenerated SCHEMAS.md
README.md, SKILL.md, and ERD.puml updates documenting the new lexicon
changeset (minor)

The strongref-documentation linter rule is satisfied by noting in the via description that the referenced record may conform with any lexicon (mirroring bsky's open use of the field for things like starter packs).

Summary by CodeRabbit

New Features
- Added certified social graph follow primitive supporting account-to-account relationship records with optional mediator references.
Documentation
- Added comprehensive guides with TypeScript examples for constructing and managing follow records.
- Updated schema definitions and relationship mapping diagrams.
Tests
- Added validation test suite ensuring follow records meet required field specifications.

Adds a social-graph follow record under the app.certified namespace that is schema-compatible with app.bsky.graph.follow: - same record key (tid) - same required fields (subject: did, createdAt: datetime) - same optional via field (com.atproto.repo.strongRef) - same lexicon description This lets feed-builders and view services index certified.app follows with the same logic they already use for Bluesky follows, and gives the certified.app ecosystem a primitive social graph. Also includes: - generated TypeScript types and exports (GRAPH_FOLLOW_NSID, GRAPH_FOLLOW_LEXICON_JSON / DOC, AppCertifiedGraphFollow) - 8 validation tests in tests/validate-graph-follow.test.ts - regenerated SCHEMAS.md - README.md, SKILL.md, and ERD.puml updates documenting the new lexicon - changeset (minor) The strongref-documentation linter rule is satisfied by noting in the via description that the referenced record may conform with any lexicon (mirroring bsky's open use of the field for things like starter packs).

changeset-bot · 2026-05-05T11:39:39Z

🦋 Changeset detected

Latest commit: 8ec051f

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

claude

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

coderabbitai · 2026-05-05T11:39:49Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ae77c515-b270-4c59-9cdb-32be3a20ffd5

📥 Commits

Reviewing files that changed from the base of the PR and between 254fcf0 and 8ec051f.

⛔ Files ignored due to path filters (2)

ERD.png is excluded by !**/*.png
ERD.svg is excluded by !**/*.svg

📒 Files selected for processing (7)

.agents/skills/building-with-hypercerts-lexicons/SKILL.md
.changeset/add-graph-follow-lexicon.md
ERD.puml
README.md
SCHEMAS.md
lexicons/app/certified/graph/follow.json
tests/validate-graph-follow.test.ts

📝 Walkthrough

Walkthrough

This PR introduces a new app.certified.graph.follow lexicon to the hypercerts repository, defining a schema-compatible social-graph follow relationship record with required subject and createdAt fields and an optional via strongRef. The addition includes the JSON schema definition, type exports, documentation examples, entity relationship mapping, and comprehensive validation tests.

Changes

App Certified Graph Follow Lexicon

Layer / File(s)	Summary
Data Shape `lexicons/app/certified/graph/follow.json`, `SCHEMAS.md`	Lexicon `app.certified.graph.follow` defined as a `record` keyed by `tid` with required `subject` (DID string) and `createdAt` (datetime string), plus optional `via` strongRef field.
Type Exports & Changeset `.changeset/add-graph-follow-lexicon.md`	Changeset declares minor version update and exports `GRAPH_FOLLOW_NSID`, `GRAPH_FOLLOW_LEXICON_JSON`, `GRAPH_FOLLOW_LEXICON_DOC` constants and `AppCertifiedGraphFollow` type namespace under `@hypercerts-org/lexicon`.
Entity Relationship Mapping `ERD.puml`	New `follow` dataclass entity added with `subject`, optional `via`, and `createdAt` fields; relationship arrow added from `follow::subject` to `contributorEntity` labeled `"follows"`.
Documentation & Examples `README.md`, `.agents/skills/building-with-hypercerts-lexicons/SKILL.md`	Lexicon reference tables and "Following another account" pattern section added with TypeScript example showing record construction using `GRAPH_FOLLOW_NSID`, mirroring `app.bsky.graph.follow` behavior.
Tests `tests/validate-graph-follow.test.ts`	Vitest suite validating positive cases (minimal and with optional `via`), and negative cases covering missing required fields, invalid DID/datetime formats, missing strongRef fields, and missing `$type`.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

hypercerts-org/hypercerts-lexicon#195: Modifies the same AI agent skill documentation file (.agents/skills/building-with-hypercerts-lexicons/SKILL.md) that this PR extends.
hypercerts-org/hypercerts-lexicon#196: Updates certified-lexicon documentation and examples alongside README/SKILL guidance similar to this PR's documentation scope.

Suggested reviewers

aspiers
Kzoeps

Poem

A follow is born, declared with care,
Through schemas neat and patterns fair,
With subject and createdAt as friends,
The graph grows rich—a link that bends.
🐰✨

🚥 Pre-merge checks | ✅ 7

✅ Passed checks (7 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main change: adding a new lexicon for app.certified.graph.follow, which aligns with all the file modifications and the core objective of the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Lexicon Documentation Sync	✅ Passed	All lexicon files, README.md, SCHEMAS.md, and ERD.puml are properly synchronized. The new app.certified.graph.follow lexicon has complete documentation with matching properties across all files.
Lexicons Styleguide Compliance	✅ Passed	The lexicon conforms to styleguide: proper lowerCamelCase naming, singular nouns for records, correctly marked required fields, complete field descriptions, and proper strongRef documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feature/add-graph-follow-lexicon

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

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

s-adamantine · 2026-05-05T11:44:54Z

Filed #210 to track the follow-up lexicons (block, list + listitem, listblock, starterpack, verification) discovered while scoping this PR.

claude Bot reviewed May 5, 2026

View reviewed changes

s-adamantine mentioned this pull request May 5, 2026

Expand app.certified.graph.* with the rest of the social-graph primitives #210

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add app.certified.graph.follow lexicon#209

feat: add app.certified.graph.follow lexicon#209
s-adamantine wants to merge 1 commit intomainfrom
feature/add-graph-follow-lexicon

s-adamantine commented May 5, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

changeset-bot Bot commented May 5, 2026

Uh oh!

claude Bot left a comment

Uh oh!

coderabbitai Bot commented May 5, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

s-adamantine commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

s-adamantine commented May 5, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

changeset-bot Bot commented May 5, 2026

🦋 Changeset detected

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

coderabbitai Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

s-adamantine commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

s-adamantine commented May 5, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 5, 2026 •

edited

Loading