BE-925: Reject links whose left and right entity are the same

[claude]

Requested by Tim Diekmann · Slack thread

🌟 Purpose

The Graph accepts a link entity whose left and right entity are the same entity, for example a friendship link from a person to that same person. We agreed to disallow these by default. This PR rejects link data whose left entity ID equals its right entity ID. Allowing self-links per link type is left for BE-926.

🔍 Changes

• Link validation reports a new LinkDataStateError::SelfReferential variant ("selfReferential" in the API), whose error names the entity. It sits next to the existing missing and unexpected link data errors, and the OpenAPI spec gains the matching variant.
• The check compares left_entity_id and right_entity_id as whole EntityIds, so it includes the web ID and draft ID.
• It runs only when link validation is enabled, so --skip-link-validation also skips it.
• Entity creation, POST /entities/validate, and entity patches all go through this validation.
• Unit tests in hash-graph-validation cover a self-link and a link between two entities. friendship.http now validates and then tries to insert a link from a person to itself, and expects both to be rejected.

⚠️ Known issues

Patching an entity reruns link validation on its unchanged link data. So once this is merged, any patch to a self-link that already exists, archiving included, fails validation unless link validation is skipped.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Oct 2, 2026 1:39pm UTC
petrinaut	Ready	Preview	Oct 2, 2026 1:39pm UTC
petrinaut-docs	Ready	Preview	Oct 2, 2026 1:39pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Oct 2, 2026 1:39pm UTC

[codecov]

Codecov Report

❌ Patch coverage is 98.64865% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 66.53%. Comparing base (25dd9ca) to head (31a76fe).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
libs/@local/graph/validation/src/entity_type.rs	85.71%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #9898      +/-   ##
==========================================
+ Coverage   66.50%   66.53%   +0.03%     
==========================================
  Files        1954     1954              
  Lines      215334   215408      +74     
  Branches     8420     8431      +11     
==========================================
+ Hits       143200   143327     +127     
+ Misses      70535    70477      -58     
- Partials     1599     1604       +5     

Flag	Coverage Δ
apps.hash-ai-worker-ts	2.04% <ø> (ø)
apps.hash-api	15.35% <ø> (ø)
hash-graph	14.11% <ø> (ø)
hash-graph-api	36.20% <ø> (ø)
hash-graph-atlas	80.00% <ø> (-0.01%)	⬇️
hash-graph-authentication	97.63% <ø> (ø)
hash-graph-postgres-store	31.94% <ø> (ø)
hash-graph-store	51.60% <ø> (ø)
hash-graph-validation	88.21% <98.64%> (+2.83%)	⬆️
hashql-compiletest	28.71% <ø> (ø)
hashql-eval	79.77% <ø> (ø)
local.hash-backend-utils	3.27% <ø> (ø)
local.hash-graph-sdk	10.02% <ø> (ø)
local.hash-isomorphic-utils	12.22% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[claude]

Both red integration checks come from this PR's check, not from main:

• Integration (hash-graph-postgres-store): links::self_loop_link and links::purge_archive_self_loop in the deletion tests create a self-loop link on purpose to cover the deletion code's self-loop handling. Link validation now rejects that insert (create_entities, "Could not insert into store").
• Integration (hash-graph-benches): the read-scaling "complete" seed links every entity to every entity, including itself, and those inserts are rejected the same way.

All three pass locally with the check reverted. Whether self-links should be rejected at all is being discussed in Slack, so I'm holding the fix until that's decided: either update these tests and skip entity_a == entity_b in the seed, or drop this PR.

---

Generated by Claude Code