feat(entities): entity-connectivity report — hubs and orphans

[boskodev790]

what

vouch entities — a read-only entity-connectivity report over the whole graph.

vouch's model note says entities "anchor relations and aggregate the claims
that mention them." health.status counts entities and vouch neighbors walks
the edges around one node, but nothing says, in a single pass, which entities
are load-bearing and which are dead. this reports:

• most connected — entities ranked by total connectivity (a hub view),
  with the breakdown that produced it
• orphaned entities — no claim mentions them, no relation joins them, no
  page references them; proposed once and never used, so a curator can prune or
  merge them

connectivity sums three things that point at an entity: claim.entities
mentions (deduped per claim), relation endpoints (a self-loop counts once, and
a non-entity endpoint like a claim or page id is ignored), and page.entities
references. every entity is therefore either connected or orphaned —
connected_total + orphan_total == entities_total.

why

the entity graph is where knowledge concentrates; this shows where. orphan
entities are the graph's dead weight (a propose-entity that no later claim
ever cited); hubs are where a rename or merge has the most blast radius. safe
from cron via --format json.

surface

strictly a viewport. composes store.list_entities, list_claims,
list_relations, list_pages; writes nothing, logs no audit event, never
touches a proposal. cli-only, so no new kb.* method (the four-site method
surface and test_capabilities are untouched). no storage, model, migration,
or on-disk-layout change. named to match the existing vouch pages /
list-pages split — a rich view alongside the raw list-entities dump.

• src/vouch/entity_graph.py — new module: pure build() plus text / markdown
  / json renderers with a stable to_dict() json contract
• src/vouch/cli.py — vouch entities, next to vouch digest
• tests/test_entity_graph.py — 11 tests (hub sum, self-loop-once, both
  endpoints, non-entity endpoint ignored, per-claim dedup, orphan detection,
  ordering + non-silent truncation, and the cli)
• CHANGELOG.md — [Unreleased]

example

entity graph @ 2026-07-10T09:20:00+00:00
entities: 42  connected: 39  orphaned: 3

most connected (20)
    17 conn  (12 claim / 4 rel / 1 page)  acme-example  [company]  Acme Example
     9 conn  (7 claim / 2 rel / 0 page)   alice-example  [person]  Alice Example
     ...
orphaned entities (3)
  legacy-vendor  [company]  2026-05-02  Legacy Vendor
  ...

validation

• python -m pytest tests/ -q --ignore=tests/embeddings → 1099 passed, 37 skipped
• python -m mypy src → clean
• python -m ruff check src tests → clean

no linked issue — a self-contained read-only viewport that changes neither the
object model, the kb.* surface, the on-disk layout, the bundle format, nor
the audit shape, so per contributing it doesn't need a vep. happy to file one
if you'd rather track it.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 79e5ca13-e5fe-41b3-bc21-69f3aca2ce54

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

---

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